Editing GUI specifications

The point-and-click philosophy of LavaPE implies in particular that a few mouse-clicks suffice to produce a default form representation from a given class declaration. This automatic mapping is governed by the following simple principles some of which have not yet been implemented (NYI) so far, however:

Member variables of the class are mapped to the data fields of the form.
The identifiers of variables are used as explanatory text to the left of the data field unless you specify alternative texts/positions.
If the type of a member variable is again a user-defined class then this member variable is represented by a nested form ("group box") or possibly also by a pop-up form, provided you have generated a form representation for this member type previously.
Member functions are represented by tool buttons or menu items that trigger the member functions if they are clicked/selected from the menu (NYI).
The member functions of inherited classes (Lava supports multiple inheritance!) are placed in separate toolbars or menus of their own (NYI).

The representation of an elementary data field depends on the type of the corresponding member variable:

Integer, Float, Double, and String are represented by small single-line text edit windows. For String multi-line text edit windows may be used alternatively.
Boolean variables are represented by check-boxes.
Enumerated types may be represented by combo-boxes, pop-up menus, groups of radio-buttons, or groups of normal push buttons.
Chains (= doubly-linked lists) of some element type are represented by horizontal or vertical lists, usually of variable length.
Constant default values may be specified for elementary fields.
Non-elementary field types that are defined by another Lava type are put into a nested rectangular box. The fields of the corresponding sub-form are positioned relative to this containing sub-form box.

GUI service classes / implementations: How to generate and edit forms

You can generate a default form representation GUI_of_XY of an existing class XY with a single mouse-click:

After you have selected class XY in the declaration tree, you simply click on the tool button ("Make GUI service for selected class").
This generates a new GUI service class GUI_of_XY (icon: ) as well as its implementation (icon: ). You may open its properties dialog by clicking the scissors tool button and, for instance, change its name then.
Select the GUI service implementation node and click the "Open form view" tool button on the declaration toolbar, which has the same icon as the GUI implementation node. The form view is opened, consisting of two panes: the actual form view (WYSIWYG, read-only) on the left, and the properties pane on the right. The latter consists of a form structure tree in the upper half, and the actual field properties pane in the lower half.
Now you can select a form field, either in the form view, or in the form structure tree, and edit its properties in the field properties pane.
You can intersperse "intermediary text" after any field of the form by selecting this field in the form structure tree and pressing the return key. (Alternatively you can click the "intermediary text" button .)
You can control the horizontal and vertical positioning of fields.
You can specify initial default values for individual fields. They override the values provided by XY's default initializer.

Note: If class XY has a member of some class Z then a GUI service class and implementation is generated also for class Z if none existed so far (or one is selected if Z has a GUI service already). Or more generally: GUI service classes are generated recursively where required, or selected from the existing ones. (This selection can be modified afterwards.)

Adding handlers (callbacks) to individual fields of forms

The context menu, either on an input field in the form view (left pane), or in the form structure tree (upper half of right pane) allows you to add a new handler to the field or to attach an appropriate existing handler to it. (On text edit fields you must proceed to the "Lava" sub-menu of the context menu.)

The handler function is created as a member function of the respective GUI service implementation. The function property dialog expects you to select a GUI event type to be handled. For input fields, Lava provides presently only one GUI event type "New value", which is signaled when a new value has been entered in an input field. Lava passes the original value and the newly entered value as input parameters to the handler. The handler may pass a modified value to its (optional) output parameter.

If a Lava class XY contains an optional member variable optvar then it ill be represented by a push button in the corresponding form representation of XY. It can be pushed to insert the form representation of optvar in place of the button. On the push button, as well as on the form representation, you can invoke the context menu to assign a handler to the "Insert/delete optional" event, which is signaled when you attempt to insert or delete an optional item.

Likewise, Lava classes that are derived from the Lava Chain class provide "Insert/delete chain element" events, which are signaled when you attempt to insert or delete a chain element. Again you may control by corresponding handlers whether the insert/delete operation is accepted, and in the insert case you may optionally return the element to be inserted to the Lava run time system (or else default initialization, see above, will be applied to the element).

More than one GUI event handler may be attached to the same input field, optional or chain element. Typically this is used to provide specialized behaviour in specialized contexts:

For instance, assume fld is an input field in GUI service F_XY and F_XY is in turn used as a sub-form in GUI service F_Z. Then you may attach a "New value" handler to fld in F_XY and another one in F_Z. The latter will be used whenever fld is used in the F_Z context, the former whenever F_XY is the top level GUI service or the "parent" GUI service doesn't have a "New value" handler for fld. The Lava run time system will always invoke the uppermost handler in the form/sub-form hierarchy if several handlers exist for an input field, optional or chain element, i.e., the handler belonging to the most special usage context.

How to present/fill out a form

Every GUI class contains two member functions FillOut and Edit that can be called in order to present the form representation F_XY of an object xy of type XY. Before you can call FillOut and Edit you must create an object f_xy of type F_XY. The object xy serves as input parameter to FillOut and Edit.

FillOut first generates a copy of xy. this copy is presented to the user. The copy may be modified by the user then. Clicking the OK button terminates the editing process and FillOut passes the modified copy through its output parameter to the caller.

You can use FillOut also to present and fill out an empty form: Simply pass the input parameter "Ø" (the "null" object") to FillOut ("empty input form").

Edit presents its input object xy directly to the user (rather than a copy of it) and allows the user to edit it "in place", provided xy is a state object.

Summary: FillOut uses its input parameter, which is a value object, as a template for the initialization of a separate output object which may be modified by the user after initialization and which is returned finally as an output parameter. Edit accepts a state object as input parameter and enables you to modify it "in place". Both FillOut and Edit are terminated by clicking the OK button.

In contrast to this FillOut andEdit mechanism, persistent Lava component objects may be edited "directly" without explicit invocation of a forms editing method (but using the same kind of Lava GUI services as FillOut and Edit).