Gled GUI

When speaking of Gled GUI, one should not forget that Gled in itself is not so much an application, but rather an application framework, and therefore its default GUI, the subject of this document, is a tool for the developer, used for introspection and interaction with the data and applications state. In this domain, Gled GUI is quite quite powerful, interactive and immediately reflects application development, but one should not forget that it is tool for developing and debugging, not an interface for application end-users. It does provide, however, the framework and element for quick building of application GUI: at this time, the best way is subclassing of the default Gled GUI implementation in the Eye, but soon, and interactively editable GUI building framework will be developed to allow application GUI building directly from the Gled GUI.

Gled, when started in GUI-mode (ie., as gled rather than saturn), opens a single top-level window: the message console, which is the "main" window of the application. The message console receives messages from the Saturn (Gled server-client) and has widgets which enable the user to load new library sets (or libsets) an open a new user-interacting front-end with GUI, called Eye (see Inside the Eye in gledparadigms). Therefore, the user usually wants to spawn a new Eye from the message console or start Gled with the CINT startup script eye.C, which spawns an Eye automatically at startup. (The underlying architecture of the GUI is fully decoupled from the client-server, permitting more than one Eye per saturn. Subclassing of Eye class permits full customisation of the GUI and development of independent application GUI. See gledparadigms and gledarch for details.)

The Eye opens its own top-level window, called the Shell. This is where most of the user interaction takes place since Shell contains some general GUI setting widgets and an embedded Nest, Gled's object browser. The Shell allows any number of secondary Nests (object browsers) and any Nest can spawn an interactive GL rendering window called a Pupil.

By double-clicking an object label in the Nest window, or by right-clicking on the object in the Pupil (interactive GL render view window) and selecting Open view ..., a Full View of the lens (an instance of a gled object or Glass) can be opened. Lens Full View is automatically built from autogenerated widgets for GUI-exported lens object member variables and methods. This allows fast object inspection and editing, and the individual widgets for member variables and methods can be used in different contexts, as explained later (Nest basics.

Some widgets spawn their own utility windows (dialogs, color-pickers etc.).

It should be noted that Gled, even in GUI-mode, still runs the CINT interactive C/C++ interpreter in the terminal where it was started from. Even more, the right-click context menu in the Nest has an option to export the current object directly to a variable in CINT, so immediate interaction in the CINT is available (more info: Using the lens and link labels). Note also that CINT implements GNU-Readline-like command line editing and completion, including completion on C++ object methods and members. (See ROOT documentation for reference, http://root.cern.ch/root/Cint.html.)

img/overview_image

Gled windows

The Message console (top left) is the toplevel or "main" window of the application: any Gled application with active GUI component will open this window. Above the message console's text canvas are widgets for loading libsets, spawning eyes and shutting down the application. Usually you want to start Gled with a startup script that besides loading your objects and libsets opens an Eye (ie. eye.C. The fist widget of the Eye is the Shell (bottom right). The Shell contains some GUI control elements at the top and the Eye message console at the bottom, with a swallowed Nest window in the middle. Any number of stand-alone Nest windows can be opened (see middle left) with the New->Nest command in the Shell or any Nest. Pupils (interactive GL rendering views of the scene) can be opened with the New->Pupil command (top right). Full view windows which display lens data can be opened by double-clicking on a label in a Nest or from a context-menu of the Pupil (two smaller windows at top middle). Gled opens also a CINT interactive C/C++ session on its standard output (shown in a rxvt terminal at bottom left).

Shell and Nest

The Shell is the main interaction window. It contains the shell part, where shell's global settings for source and sink (Object collection editing with Nest) of the current Eye are located; under the shell part of the Shell window, a swallowed Nest is located. The Nest contains target settings (local to each Nest) and Nest menus. Note that any number of bare nest windows can be spawned using the nest New->New Nest menu option in the nest.

The main part of the Nest window is the object graph browsing widget, explained bellow.

img/shell_overview

Shell contains a nest and a message window

The Shell is the most important window of the Eye. It contains some controls for the GUI, a Nest for interaction with the object graph and the GUI, and a message console and input for the Eye. Currently, prefixing a message with the name of an Eye and a colon sends the message directly to that Eye's console. Note that it is the Nest that allows opening of new nests and pupils from its New menu (displayed).

Nest basics

The main widget of Nest is the object graph browser. The left part shows a tree-like view of the object collection while the right can show either links for each lens (default) or a custom selection of object-view widgets for the lenses. This can be toggled with View->Links/Custom menu action (or ctrl-v, all keyboard shortcuts are shown next to the menu labels). The custom view can be edited with the View->Edit Custom command (Editing and setting custom lens views). Some useful predefined custom views are available as a pup-up selection with the View->Predef Custom menu action. This allows for good control over which member values can be manipulated and which methods can be called directly from the Nest, and thus the Nest is quite an efficient specialised editor.

img/nest_edit_custom

Nest with custom view

The nest on this screenshot has been configured with a custom view of Pos and Rot widgets for ZNodes (see dialog mislabelled MTW_Layout; this setting is available among the predefined ones). The View menu is displayed where custom views can be selected and the editing dialog called.

Resizing

The double-diagonal-arrow resizer button opens a size-control dialog for resizing all widgets of the current Eye (size is based on the size of fonts; useful for viewing complex object collections on limited screen estates). Note that a global resizer button on the main message console controls the whole Gled instance.

The button with two vertical bars (resembling a pause on audio devices) opens a control widget that you can use to set the size of table columns for the widgets in the nest.

Each lens in the browser is represented by a labelled button (the name of the label is the Name member variable of the lens). Double-clicking on the label will open the full-view window for the lens, where all the widgets generated for its member values and methods are shown.

The label is preceded by two collapsors. The right one is list collapsor: it will toggle the display of all list members of the lens (you can think of list-members as folder contents of standard file-system tree browsers). The left one is link collapsor: It will toggle the display of all non-null links. Note that links precede lists if both are open, and each link is preceded with the link name.

This permits fast browsing of lens aggregations using both link and list aggregations methods. But as lens aggregates are not necessarily tree structures the resulting graphs can be circular and it is for that reason, lens aggregations are not represented as tree widget. (Note also that ZNode lenses do form a tree structure with their list contents, and their parents can be accessed through the Parent link.)

img/shell_decollapsed

List and link (de)collapsors and decollapsed contents

On the left in the lens-list, the arrow-shaped link collapsor and triangle-shaped link collapsor icons are marked. On the right, two different arrow-shaped icons are used for the link decollapsor and link-list decollapsor (the latter dereferences the link to the list, and decollapses also the list: this is a very common operation, thus this shortcut is provided.) A decollapsed link can be clearly distinguished by the link name, which is marked in front of the lens widget. Note how icons change when decollapsed. The icons are dark red when inactive, showing that there is no contents to show (decollapse).

By default, the link display (on the right) lists all links of the lens with link names for labels. Each label is preceded by two collapsors - the first collapsor toggles the display of this link's contents on the left part of the lens browser, while the second one toggles also the display of list contents for links to lists (one level deeper).

Both link collapsors are dark-red when the link is null. The right callapsor is red when the link does not point to a list.

Editing and setting custom lens views

Custom lens view display can be edited with View->Edit Custom menu action. Syntax for custom view for a class is <class_name>(member_name[{width}][,member1_name[{width}]]). You can specify multiple classes, using a colon to separate them. Example for displaying the name for all lenses and radius and LOD of all Spheres:

	ZGlass(Name[10]):Sphere(Radius,LOD[4])

Do not forget that Custom has to be enabled for this to have any effect. You should get this result:

Note that the custom view widgets will work just as well as the corresponding widgets of the full view windows. This is good for quick editing of lenses.

A number of predefined custom views can be selected with the View->Predef Custom menu action.

ZNode custom view

ZNode custom view, available as one of the predefined views, is a slightly special case. It would be specified as follows:

	ZNode(Pos,Rot)

The difficult part is that the Pos gled-widget is composed of three number-input fltk-widgets for x, y and z offsets of the ZNode, and the Rot widget is in the same way composed of a, b and c rotation angels. This can be misleading since both widgets display their internal labels and Pos and Rot never appear as labels in the lens' full-view window.

On the other hand, these widgets are prefect for rapid scene editing.

Double-clicking on a lens label will open the full-view window for that lens. Double clicking on a link label will dereference the link and open the full view window for the lens the link is pointing to.

Right clicking on the label will open a context menu (the locator menu). The first level offers some utility functionality (setting the lens to source and sink, setting "Beta" and "Gamma" links on current nest and exporting it to a variable accessible from CINT, where a dialog will prompt you for a variable name to export the lens to). The Method sub-menu contains a menu per class from the glass inheritance tree of the lens, listing all methods from each class.

Object collection editing with Nest

Target, Source, Sink

Gled methods can be called using the MIR (method invocation request) mechanism. A MIR uses a specific calling environment, called a context. All GUI actions are realized as MIR calls from the Eye, and method arguments are passed as elements of the MIR context. (For more information about MIR context and routing see Propagation of Light in gledparadigms.)

MIR context elements are caller (when using the GUI, this is always the Eye), recipient (the Saturn on which the method has to be authenticated for beamed MIRs), alpha (always used for the lens for which the MIR is sent) and two "positional" context elements, beta and gamma (the "arguments"). While general MIR calls can be built in the GUI using the "Beta" and "Gamma" links of the current shell's ShellInfo, the standard GUI actions will build MIR calls automatically for the user.

The Nest with its interface for lens graph manipulation uses three different concepts for stating the purpose of a GUI action: target, source and sink.

Target points to the lens for which the MIR is sent (the target lens therefore becomes the alpha of the MIR context). For GUI actions, this is the lens that gets modified.

Source is the lens argument used for those GUI actions that set a link (Set Link) or add to a list, (ie. Push, Unshift and Insert). For any of these actions, source must point to something with lens contents.

Sink is used with the Yank command which takes target and adds it at the end of the list sink is pointing to.

Setting target, source and sink with locators

Gled GUI provides several ways to set target, source and sink: two special selections or locators can be used, called point and mark, and for the target, the bellow mouse "virtual locator" is also available. It is important to distinguish target, source, and sink from locators. The user can control which locator is active for which function with the target selection widget on each Nest (since Target is nest-specific) and similar widgets for source and sink on the Shell.

Important: Locators (point and mark) are indicated with color feedback on labels, while target, source and sink are indicated with color feedback on collapsors. The colors correspond with the colors on the control widgets.

The Bellow Mouse setting can only be used for target. For source, there is a special option for creating new lenses: Creator (see Creating lenses). Sink also provides a special option: /dev/null - in this case, removal commands do not move the lenses, but delete them instead. (This is the default.)

The point can be set on lenses with normal mouse click on the lens name. Both locators can be moved using the keyboard, point with cursor_up and cursor_down, mark with S-cursor_up and S-cursor_down. Point can be set on links (on the right when link display is selected) with a mouse click, and mark can be set on links with a mouse click-and-right drag (where you should drag inside the widget. The label color changes for feedback: selected lens or link gets orange for point and blue for mark.

The current setting of target and source is shown on collapsors: green for source and pink for target. Notice how link collapsors are used when links are selected while graph-node collapsors are used otherwise.

Target is nest-specific, meaning that each nest can have its own target and its own setting for target-locator relationship. Source and sink are global, but both can be controlled also from the Set menu on nest window.

The Set menu provides a number of shortcuts for setting Source, Mark and Sink: Set->Point as Source (F1), Set->Point as Sink (F2), Set->Mark as Source (Shift-F1) and Set->Mark as Sink (Shift-F2). The Set menu on nest window allows also swapping of point and mark with Set->Exchange point and mark [X]. Source and sink can be exchanged with Set->Exchange source and sink [Shift-X].

Links use source and target, where target has to be set to a link-name label of a lens (on the right side of the object aggregation browser; not on the decollapsed link under the lens on the left), and source has to be set to the lens that the link will point to.

Use Action->Set link [s] to set links and Action->Clear link [c] to clear links.

When using Creator for source, new lenses will be instantiated and set as link.

A link can also be set with drag and drop: click on the lens label on the left and carry it to the link label on the right; when the mouse pointer changes to indicate that the widget is suitable for dropping, release the mouse button and the link is set.

img/nest_with_actions

Nest with the Action menu

The Action menu in Nest (available also in the Nest swallowed in Shell) provides easy access to GUI actions and displays all shortcuts.

When links are cleared, lenses that were referenced by the link will be put into the sink unless the sink is /dev/null. Lenses that are not otherwise referenced will be put into the orphanage list of their Queen (unless a sink was defined and they were put there instead) or deleted, depending on the settings of the Queen (more on Queens:Kings and Queens in gledparadigms).

Note that the source lens has to correspond to the class of link (Gled will attempt a dynamic cast to that class and report an error if it fails.) The most common case of this is a link to a list which will refuse to accept lenses that are not ZList class or its descendant.

A link can be set also with the locator menu's method sub-menu (right-click context menu on the label) using appropriate SetLinkName method with the lens to be referenced selected by the "Beta" link of the current nest (See Building MIRs with GUI).

Manipulating lists

Lists can be manipulated with list manipulation commands from Action menu. Set the list as target and the lens to be added to the list as source. Set source to Creator for adding new lenses to the list.

Use Action->Push [p] to append to the list and Action->Unshift [u] to add at the top of the list.

To remove from lists, use Action->Pop [o] to remove from the end of the list and Action->Shift [h] to remove from the tail.

To insert in the middle of the list set the lens before which you want the new list member to be inserted as target and use Action->Insert [i]. To remove from the middle of the list, set the lens to be removed as source and use Action->Remove [e].

Mnemonic help: Note that adding commands use the first letter of the shortcut, and removing commands use the second letter.

A link to list can be selected instead of the list and the GUI will dereference the link and use list commands on the target list itself, if possible.

A list can also be manipulated with drag and drop: click on the lens label on the left and carry it to the list label on the left or to the link-to list label on the right; when the mouse pointer changes to indicate that the widget is suitable for dropping, release the mouse button. The action performed is always Push (append to the end of the list).

A list can be also manipulated with the locator menu's method sub-menu (right-click context menu on the label) of the list, using appropriate methods from the ZList class or one of its descendants. Set lenses to be used with "Beta" and "Gamma" link of the current nest (See Building MIRs with GUI). This method is far more involved than the standard GUI bindings.

Creating lenses

Lenses are created with insertion commands (Action->Push, Action->Unshift, Action->Insert) and link setting commands (Action->Set Link) simply by setting source to Creator. This ensures that the object-graph node for the new lens is set immediately.

To select what lens should be created, the libset should be selected with the Lid selection menu and then any glass in that libset can be selected with the Cid selection menu. (Not that a libset may have to be loaded first using the Load Libset widget on the Gled Message Console window to become available.)

Using sink

Sink is the target for yank commands.

Currently sink always pushes at the end of the list and throws an error if it is not set to a list.

If a list or a link to list is used as sink, removed and yanked lenses (and lenses that were cleared from links) will be pushed at the end of the sink list.

Building MIRs with GUI

While the GUI has special shortcut command for the most often used methods of ZGlass and ZList (and their descendants' implementations), any context method can be called using the locator menu's method sub-menu (right-click context menu on the label).

The method submenu lists all classes in the class hierarchy of the current lens that define any context methods. Each class is a sub-menu, listing all the context methods in that class.

(Note that ZGlass is missing, for example, since it defines no methods, and non-context methods, such as Sphere::SetRadius, are not displayed since they cannot be invoked via a MIR context; you must build MIRs for such methods by manipulating relevant widgets in the full view of the lens.)

Each context method is followed by two numbers in parenthesis. The first number indicates how many context arguments are expected (Alpha, which is always the current lens, is ignored, so 0 means just Alpha, 1 means Alpha and Beta and 2 means Alpha, Beta and Gamma). For beta and gamma arguments, beta and gamma links of the current nest are used. Use link manipulation methods or Set as Beta and Set as Gamma of the locator menu to set Beta and Gamma.

The second number is the number of additional arguments. When additional arguments are required, a dialog will spawn to select them.

Some context methods require additional streamed data, provided as a post-MIR. Such MIRs currently cannot be build with the GUI.

Using multiple nests

Multiple nests allow you different views of the object aggregation. Nests are useful also as scratch-pads. Since each nest has its own locators, they are useful for working with different locator contexts.

A new nest can be spawned by the New->Nest action on any nest window (of swallowed nest in the Shell).

The new nest will be empty: it will show only one member, its own NestInfo. You have to populate the new nest by adding members to the NestInfo.

Full views

Full view is composed of all widgets for a given lens, organised in a vertical structure which follows the class hierarchy of the lens.

View of main classes

ZGlass full view

Since all lenses are ZGlass descendants, all full views start with the standard ZGlass member-variable widgets Name and Title. These are read-write widgets so you can easily edit names and titles of lenses. (They are also available in the nest's predefined custom view under Nest->View>Predef Custom->ZGlass.)

The SaturnID is a read-only value, representing the ID of the current lens in the object ID space (good for debugging, etc.)

Each ZGlass has a read-only boolean indicator MIRActive which shows whether the lens is currently accepting MIRs.

ZList full view

Many glasses inherit from ZList but ZList itself has no visible widgets int the full view. You can access the list members using nest's list view. In the future, ZLists may be limited to allow only a defined glass of list members and this setting will be presented as a widget in the full view.

ZNode full view

ZNode contains relative positional offset represented with the Pos widget which contains three sub-widgets, x, y and z and relative rotational offset represented with the Rot widget which contains three sub-widgets, a, b and c. (These widgets are also available in the nest's predefined custom view under Nest->View>Predef Custom->ZNode.)

ZNest implements an object tree using links and lists. A a <ZList> descendant it stores its children as list members and its parent as the value of the Parent link. It's full view contains the KeepParent boolean toggle which controls whether the ZNode should keep its previous parent when it becomes member of a new list, or the parent should be changed to the new list.

Widget types and how to use them

Widgets are auto-generated from Project7 commands in C++ comments next to class member variable and class method declarations, where perl methods for widget creation are specified directly.

Note that standard FLTK keyboard navigation is available. See documentation for Value for notes on special mouse bindings.

Textor

Uses Fl_Input. Read and write widget for text etc. Standard FLTK bindings apply, including selections and pasting. Enter or widget-leave will update the value.

Text_Out

Uses Fl_Output. Read-only widget for text. (But Set method may be available.)

Value

Uses Fl_Valuator. Read and write widget for numerical values. Range and step for the value can be set (limiting the value to an int, for example). Standard FLTK bindings apply, including selections and pasting. Enter or widget-leave will update the value.

Mouse drags can be used to manipulate the value. Left-mouse dragging will modify the value by the defined step (for precision editing), while middle-drag uses a 10-multiplier and right-drag uses a 100-multiplier. The value is updated at each mouse-drag manipulation immediately.

ValOut

Uses Fl_Value_Output. Read-only widget for numerical values (see Value for details). (But Set method may be available.)

Bool

Uses Fl_Light_Button. Widget used to represent and toggle boolean member values.

BoolOut

Uses Fl_Light_Button. Readonly widget used to represent boolean member values. (But a Set method may be available nevertheless.)

PhonyEnum

Uses Fl_PhonyEnum (a custom Gled FLTK widget). Fl_PhonyEnum behaves as a drop-down selector menu for C++ pseudo-enumerations, so that logical names can be used instead of cryptic index values for choices.

MButt

Uses Fl_Button to produce a standard button. Intendet to start lens methods that do not require any context-arguments.

ColorButt

Uses Fl_ColorButt. Displays the selected color and starts a color-selector transient dialog on click.

Filor

Uses Fl_File_Name (a custom Gled FLTK widget). File name can be edited as text. Use right click to open a FLTK file selector.

Pupils

Pupil navigation

The pupil is an interactive GL rendering window with a number of navigation bindings:

Pupil context menu

Right-click on the mouse will display a list of lenses under the pointer (using GL picking; the size of the picking are under the pointer can be controlled with the PickW and PickH member-values view the full view of the pupil and BuffSize is the buffer size for picking, limiting picking depth). For each lens, its render stack is displayed as a sub-menu.

The Open view ... is often very practical since it opens a full view on the current object of the rendering stack menu.

Manipulating Pupils with PupilInfo

A new Pupil can be spawned from any Nest using New->Pupil menu command. This will create a lens (gled-object) called PupilInfo and open a GL rendering window. (While you can close the pupil's GL rendering window, there is currently no way to open it again, so please avoid that.)

The Pupil and GL rendering is controlled with the setting of PupilInfo's member variables. All PupilInfos of a given Nest are members of a single list (usually called PupulInfos), linked to by the Pupils link from the Nest itself. To access the Pupils, you should simply de-collapse the linked list of the Nest. (The PupilInfo should always be the first member of its lens graph).

PupilInfo's are lists: the Pupil creates the render-graphs by descending the contents of the PupilInfo as list. So, to render a scene, simply add it to the PupilInfo (via Push or Unshift, or with drag-and-drop).

(Note that you can't add a single item twice to have it rendered twice since the renderings will overlap: use a ZNodeLink> object and set it to link to the object you want to figure twice in the rendering scheme, so that you can use it's ZNode transformation to displace the rendering location.)

The next important feauture of the PupilInfo is the camera control: the viewpoint can be free (use the bindings to move it freely) or attached to an object as a camera. To attach the viewing point, set the PupilInfo's CameraBase link to the object: navigation will now work as offset to the object.

Use LookAt to set the focus point of the camera/viewport.

You can also set the up-vector for the camera by setting the UpReference link to a lens. You can choose one of the axes by setting the UpRefAxis member value: it is an index into (x, y, z).

There is a number of GL rendering settings that can be set in the PupilInfo:

MaxDepth

Sets the maximum depth for the GL context.

ClearColor

Sets the "background" or "clear" color for the rendering window.

FOV

Sets the Field of View in degrees. The default is 90. Use smaller values for zoom and larger values for large-angle camera effect.

NearClip / FarClip

Sets the clipping planes for GL rendering: no vertices closer of further than this plane will be rendered.

FronMode / BackMode

These PhonyEnum enumerators are used to set the rendering modes for front and back-sides of the polygons. Fill, Line and Point are available. Note that pushing the camera inside a full object will allow you to see the back-sides of the polygons, rendered in line-mode (wireframe) by default.

LiMo2Side

Toggles the use of 2-sided GL light model: this should be used whenever the back-sides of polygons should be rendered in fill-mode and shaded correctly.

Blend

Toggles the blend function: no alpha values (transparency) are used if this is off. Note that transparent object have to be rendered in correct order in GL, and Gled does not reorder objects in the rendering tree.

PupilInfo's Pupil GUI settings:

CHSize

Crosshair size (in percent). Use 0 to turn off the crosshair.

PickW and PickH

Width and height of the picking rectangle in pixels. The picking rectangle is used when objects are selected for right-click menu.

MSRotFac and MSMoveFac

Controls for rotation and motion sensitivity for mouse navigation.