For this project first an overview of all controls is given, each with the information of how to create it. After that the details per package are provided.

GUI Controls

Layouts

HBox

creation: componentFactoryFx.createHBox()

VBox

creation: componentFactoryFx.createVBox()

GridPane

creation: componentFactoryFx.createGridPan()

Simple Controls

Label: TODO

Menus

MenuBar

creation: componentFactoryFx.createMenuBar()

Menu

creation: componentFactoryFx.createMenu()

Dialogs

For all dialogs, customized versions of javafx.scene.control.Alert are used.
As for all GUI controls, these are created via the ComponentFactoryFx.
The dialogs with a specific kind of information (Error, Exception, Warning, Information) have an icon to identify this kind of information, therefore the graphic of these dialogs cannot be specified.

Error dialog

This dialog is shown in case of an error.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, being ‘Error’.
• Header text and ‘error icon’.
  The header text describes what went wrong.
• Content text and ‘OK’ button.
  The content text provides additional details, often the system error message.

creation: componentFactoryFx.createErrorDialog(String headerText, String contentText)

Exception dialog

This dialog is shown to report an exception.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, being ‘Exception occurred’.
• Header text and ‘error icon’.
  The header text describes what went wrong.
• Content text and ‘OK’ button.
  The content text shows the exception stacktrace.

creation: componentFactoryFx.createExceptionDialog(String headerText, Exception exception)

Warning dialog

This dialog is shown to report a warning.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, being ‘Warning’.
• Header text and ‘warning icon’.
  The header text describes what is not ok.
• Content text and ‘OK’ button.
  The content text describes the proposed solution.

creation: componentFactoryFx.createWarningDialog(String headerText, String contentText)

Information dialog

This dialog is shown to inform the user about something.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, as specified
• Header text and ‘information icon’.
  The header text is a short text.
• Content text and ‘OK’ button.
  The content text is to provide more details.

For a short message, only use the header text. Otherwise, the header text shall provide a short description and the context text shall provide more details.

creation: componentFactoryFx.createInformationDialog(String title, String headerText, String contentText)

Application information dialog

This dialog is shown to inform the user about something, using a specific graphic.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, as specified
• Header text and an icon as specified.
  The header text is a short text.
• Content text and ‘OK’ button.
  The content text is to provide more details.

For short information, only use the header text. Otherwise, the header text shall provide a short description and the context text shall provide more details.

creation: componentFactoryFx.createApplicationInformationDialog(String title, Image image, String headerText, String contentText)

Application information dialogs with formatted text

These dialogs are typically used to show larger informational texts.
There are two versions available:

The only difference between these two dialogs is how the formatted text is specified; as HTML or markdown.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, as specified
• Header text and an icon as specified.
  The header text is a short text.
• Content text
  The formatted specified text (specified in HTML or markdown format)
• ‘OK’ button.

For short information, only use the header text. Otherwise, the header text shall provide a short description and the context text shall provide more details.

creation:
componentFactoryFx.createMarkdownTextDialog(String title, Image image, String headerText, String contentText)

componentFactoryFx.createHtmlTextDialog(String title, Image image, String headerText, String contentText)

Confirmation dialogs

These dialogs are shown to let the user accept or reject a proposal. There are two versions, so you can chose the one which best fits to the question asked.

Contents of these dialogs:

• Title bar with:
  • Application icon
  • Title, as specified
• Header text and ‘question icon’.
  The header text is descriptive version of the question.
• ‘OK’ and ‘Cancel’ buttons, or ‘Yes’ and ‘No’ buttons and content text.
  The content text repeat the question in a short format.

creation:
componentFactoryFx.createOkCancelConfirmationDialog(String title, String headerText, String contentText)
componentFactoryFx.createYesNoConfirmationDialog(String title, String headerText, String contentText)

Choise dialog

This dialog lets the user choose one of a list of options. The options are presented in a combo box.

Contents of this dialog:

• Title bar with:
  • Application icon
  • Title, as specified
• Header text and ‘question icon’.
  The header text shall describe what is to be chosen.
• Combo box with an optional short text, options (in a combo box) and ‘OK’ and ‘Cancel’ buttons.

This dialog is created via:
public Alert createChoiceDialog(String title, Image image, String headerText, String contentText)

Information per package

package goedegep.jfx

This package provides customized JavaFx classes. The classes can be provided as follows:

• Via the factory ComponentFactoryFx
  This factory provides methods to get customized instances of the plain JavaFx classes.
• As customized classes which extend the JavaFx classes
  This is needed so other classes can further extend these classes. These classes are named ‘JavaFx<JavaFxClass>’ (e.g. JavaFxStage provides a customized version of javafx.stage.Stage).

class CustomizationsFx

A helper class to store the Customization per module and access them by their module name.

package goedegep.jfx.eobjecttreeview

This package provides a TreeView for a hierarchical EObject. The main features are:

• EObjectTreeView extends javafx.scene.control.TreeView
  So all functionality of the JavaFx TreeView is available.
• Customization of which parts are shown and how
  The tree view is highly customizable. However this can also be completely omitted.
  In this case all information is derived from the EObjects.
• GUI customization
  By default the customization is obtained via DefaultCustomizationFx.getInstance(). But you can set the customization by specifying a CustomizationFx.
• View mode/Edit mode
  When you are browsing through the tree view, you don’t want to see all the attributes for which no value is provided. Therefore two different modes of operation are defined.
  The tree view is either in ‘view mode’ or in ‘edit mode’. In ‘view mode’ attributes which have no value are not shown and the items cannot be changed,
  in ‘edit mode’ all attributes are shown (unless the Descriptor specifies that there aren’t to be shown) and the items can be changed.
• ObjectSelector
  The tree view implements the ObjectSelector interface. This normally provides an object of a specific type. A tree however contains items of different types.
  This also means that some context information is required. Therefore objectSelected() provides the selected tree item (instead of the value).
  It should be noted that from the tree item you can easily get its value, but the other way around is not easy and in case of simple values not possible.
• Drag and Drop support
  Via Drag and Drop EObjects can be moved within the tree. An EObject can of course only be moved to a location which supports the type of the item to be moved.
  The move is a real move, meaning that the object is really moved (instead of creating a clone of the object and then deleting the object).
  Apart from this standard functionality, it is possible to set functions to check whether a drop is possible and to handle the drop.

Overview of the classes:

• EObjectTreeView
  This class provides a tree view for a hierarchy of EObjects.
• EObjectTreeCell
  This class provides the TreeCell for the EObjectTreeView
• EObjectTreeCellHelper
  This interface is used by a TreeCell to delegate the content specific work to a helper class.
• EObjectTreeCellHelperAbstract<D extends EObjectTreeItemDescriptor>
  The common part for any EObjectTreeCellHelper implementation.
• EObjectTreeCellHelperForAttributeList
  This class is a tree cell helper for the ‘list’ node of an attribute of type many.
• EObjectTreeCellHelperForAttributeListValue
  This class is a tree cell helper for a single value of an attribute of type many.
• EObjectTreeCellHelperForAttributeSimple
  This class is a tree cell helper for a simple attribute.
• EObjectTreeCellHelperForObject
  This class is a tree cell helper for an object.
• EObjectTreeCellHelperForObjectList
  This class is a tree cell helper for a list of objects.
• EObjectTreeDescriptor
  This class provides a presentation descriptor for the EObjectTreeView.
  It specifies the structure of the tree. It specifies which items are shown and how.
• EObjectTreeItemDescriptor
  This class forms the common part for descriptors for an item in an EObjectTreeView.
• EObjectTreeItemAttributeDescriptor
  This class is an EObjectTreeItemDescriptor for an item of type EObjectTreeItemType.ATTRIBUTE_SIMPLE.
• EObjectTreeItemAttributeListDescriptor
  This class is an EObjectTreeItemDescriptor for an item of type EObjectTreeItemType.ATTRIBUTE_LIST.
• EObjectTreeItemAttributeListValueDescriptor
  This class is an EObjectTreeItemDescriptor for an item of type EObjectTreeItemType.ATTRIBUTE_LIST_VALUE.
• EObjectTreeItemClassDescriptor
  This class is an EObjectTreeItemDescriptor for an item of type EObjectTreeItemType.OBJECT.
• EObjectTreeItemClassListReferenceDescriptor
  This class is an EReference specific descriptor for an item in an EObjectTreeView.
• EObjectTreeItemClassReferenceDescriptor
  This class is an EObjectTreeItemDescriptor for an item of type EObjectTreeItemType.CLASS_REFERENCE.
• NodeOperationDescriptor
  This class describes the available operations for an item in a tree.
• ExtendedNodeOperationDescriptor
• EObjectTreeItem
  This class represents EObject tree items.
• EObjectTreeItemContent
  This class contains all data needed to be stored in a tree item.
• EEnumEditorDescriptor
  This class is a descriptor for an EEnum editor.
• EObjectTreeItemType
  This enumeration defines the types of the items in an EObjectTreeView.
• PresentationType
  This enumeration type specifies the ways (String) values can be presented.

Tree items
A TreeView consists of items of type TreeItem.  The items in the tree have to contain all relevant information. In this case:

• The value of the item
• The type of information stored in the item
  This is used to select the right tree cell helper.
• The EStructuralFeature represented by this item.
  Needed to change the value.
• Presentation information (the presentationDescriptor)
• A reference back to the tree view.

This information is stored in objects of type EObjectTreeItemContent. Therefore the type EObjectTreeItem (for the items in the tree) is of type TreeItem<EObjectTreeItemContent>.

Tree structure
The structure of the tree is as follows.
The root node is an OBJECT node for the EObject to be shown.
An OBJECT node has the following content:

• eObjectTreeItemType = OBJECT
• object = the eObject
• eStructuralFeature = null
• presentationDescriptorTreeNode = the corresponding descriptor

An OBJECT node has one child for each EStructuralFeature of the eObject, which is either an EAttribute or an EReference.

Tree cell helpers
A TreeCell is used to render an item in a TreeView. Although the rendering largely depends on the type of the item, there is only a single type of TreeCell, which is created by a factory set via setCellFactory(). Here the TreeCell is of type EObjectTreeCell which itself is a TreeCell<EObjectTreeItemContent>.
To avoid that EObjectTreeCell gets very complex, we use tree cell helpers to do the type specific work. These helpers all implement the EObjectTreeCellHelper interface.
The common part is implemented by EObjectTreeCellHelperAbstract, which is a generic type with a subtype of EObjectTreeItemDescriptor as parameter.
For each type defined by EObjectTreeItemType there is a subtype of EObjectTreeCellHelperAbstract.
A TreeCell instance is also reused to render different items. Each time the TreeCell instance is assigned to an item, the method updateItem is called. Therefore this method creates the right helper for the item type and then delegates the work to the helper by calling updateItem on the helper.

How it works together

The root of the tree is always an EObject (EClass).

package goedegep.jfx.objectcontrols

This package provides a set of GUI controls to show and enter object values.
JavaFx controls don’t all operate on an object. For example, if you use a TextField to show or enter a date, you have to do the conversion from date to String yourself.
If you are building an editor,  you have to know whether a value has been entered and if this value is valid.
The ObjectControls in this package try to solve this. They are all JavaFx controls wrapped as anObjectControl.

What has to be supported by an ObjectControl?

• Consistent presentation of information
  Example: your application shows dates as dd-mm-yyyy, but the user can enter the date as d-m-yyyy. Then when the user goes to the next field in the editor, the entered date should be reformatted to the dd-mm-yyyy format.
  Therefore, when a control loses focus, it has to redraw the value.

Implementation details

Use JavaFx beans properties as much as possible for the properties optional, filled in and valid. TODO not valid anymore

interface goedegep.jfx.objectcontrols.ObjectControl

GUI controls, like TextField, represent the value of an object, but the control itself is unaware of the object type.Therefore a set of controls is defined which are object type aware.
For example, if you want to show a LocalDate as text and allow the user to edit this value:
•To show the LocalDate, it has to be formatted to a String.
In this interface this is taken care of by the method setValue, where the formatting is to be done by the implementing class.
•The other way around is even more complicated.
To use the text from the TextField to set a LocalDate, you first have to parse the text to create a LocalDate.In this interface this is taken care of by the method getValue, where the parsing is to be done by the implementing class.
But there is more, you want to know whether the user has to enter a value, has entered a value and whether the value is valid. This is discussed below.
Optional
An edit window typically has several controls. A ‘save’ button is often only enabled if all required values are filled in.The isOptional method can be used to check on this. An implementing class typically provides a constructor with an ‘isOptional’ parameter.

Filled in
Indicates that something is entered, it may be valid or not. The isFilledIn method can be used to check on this.

Valid
An edit window typically has several controls. A ‘save’ button is often only enabled if all required values are valid.
Valid is defined as: •Either: the control is optional and nothing is filled in
•
•Or: What is filled in can be translated to an object of the type of the control.
The isValid method can be used to check on this.

• React to changes
• Edit objects (not just Strings)
  A JavaFx TextField provides the functionality to edit Strings. To edit e.g. a Date you have to convert the date to text and after editing you have to convert it back from text to a Date.

Note: It would be more logicl if ObjectControl would extend ObservableValue, but this gives a conflict on getValue() in ObjectInputEEnumComboBox. The type parameter for ObjectInputEEnumComboBox is <T extends Enumerator>, while the ComboBox is of type <Enumerator>.
On the other hand this is not a problem. The addListener() for a ChangeListener is not needed and instead of getValue() ObjectControl defines getObjectValue().