Using the XXL Visual Builder

Default Selection

• There is at most one selected object. Its corresponding icon is "highlighted" (background and foreground colors are inverted).

• The selected object can change automatically when creating new objects (for instance Motif "Manager" widgets are always implicitly selected).

• as said before, you can also explicitly select an object:
  • by clicking with mouse button 1 (usually the left button) on its icon
  • by clicking on its text, when visible
  • by control-clicking on its corresponding widget (when any).

• you can explicitly De-select all objects by clicking in the background white area of the Graph View

Adding or Changing Links Between Object Icons

Changing the Object Name

A new name is automatically computed at the object creation time when double-clicking on class names. This name can be changed once the object has been created by:

• selecting this object (if not already)
• changing the object name displayed in the Edit Bar (located below the Menu Bar)
• validating this change by pressing the Enter or Return keys

XXL Release 97.11 also allows to specify object names before object creation:

• Simple-click on a class name in the left panel
• Change name in the Edit Bar
• The click once again on class name or click on the CREATE button in the Edit Bar.

Changing the Object Class

The object class can also be changed once the object has been created. This can be done by:

• typing the ENTER key on the Class Field in the Edit Bar
• then double-clicking on the new Class Name in the left panel.

! Note that changing object class may lead to errors if the new object is not compatible with the children and/or the parents that were already linked to it (errors will be detected and listed to the user and offending links will automatically be removed).

3. Editing the Graph View (Changing the Links)

The Graph View is fully editable: objects can be selected, moved, edited and links between objects can also be changed interactively. Depending on the object class, icons may contain all or some of the following areas:

! Note that the color of the icons indicate the meta-class of the corresponding objects (for instance, Interface icons have a specific color, Widget icons have a different one and so on).

Selecting Icons

• Push or click with any Mouse Button on the name area to select icons

Moving Icons

• Push with Mouse Button 1 (left button) on the name area to move icons
• Push with Mouse Button 2 (middle button) to move the icon and its children (this will move the whole subtree of objects)

Opening the Icon Menu

A pop up menu is associated to each kind of icon. What this menu actually contains depends on the meta-class of the corresponding XXL object. To open this menu:

• Push with Mouse Button 3 (right button) on name area to open the icon menu

Deleting Links

To delete incoming links (i.e. links that are coming from one or several parents):

• Push with Mouse Button 3 (right button) on the icon to open its associated pop up menu
• Then click on the Unlink button

Adding Links

• Push with Mouse Button 1 (left) on the child area of the (parent) icon
• Move the mouse while keeping Button 1 pressed (an arrow that materializes the link will appear and follow the mouse)
• Release Button 1 on the (child) icon you want to link to the parent icon.

• the Builder will display an error message if these two objects have incompatible classes and can not be linked together
• you did not drop the mouse at the right place : try again !

Moving Links

• change the order of the corresponding objects in the source code
• change the ordering of widgets in the Widget View if the parent widget is a Motif RowColumn (or any variant such as Menus, RadioBoxes, etc.).

Minimizing and Maximizing Sub-Hierarchies

Double clicking on the child area of the icon alternatively minimizes and maximizes its children (the whole subtree will alternatively be hidden or shown).

Alternate way: Select icon then type Control-M

Changing the Object Name and Class

This can be done by changing the Class and Name of the selected object in the Edit Bar (see Section 2: Building New Interfaces from Scratch).

Redraw and Refresh

To Redraw a single hierarchy (or sub-hierarchy):

• Open theIcon Menu (right button on icon) then click on Redraw
• or: Select icon then type Space

• Open the Graph View Menu (right button on background) then click on Refresh
• or: Open File Menu then click on Refresh
• or: Type Control-F

4. Editing Widget Properties

The XXL Builder provides a complete Resource Editor that can show and modify interactively almost all the resources of Motif widgets. To edit Widget Resources:

• push with Mouse Button 3 (right button) on the icon to open its associated pop-up menu,
• then click on Resources (or Properties)

! Note : once opened, the Resource Editor will automatically be updated each time another Widget object is selected.

Resource specifications are stored in two kinds of XXL Objects:

• Args objects are used to specify resources at widget creation time
• Set objects are used to modify resources once the widget is created

Both kinds of objects can store a list of resource specifications. These objects must be linked as children of the Widget object(s) they are supposed to apply on. They can be shared by several Widget objects (they can have several Widget parents) thus allowing to apply the same resource specifications to a group of Widgets.

The Resource Editor automatically manages (creates and updates) Args and Set objects (note that Args objects are used by default, but this can be changed if needed). At last, these objects can also be modified by changing their source code directly (see Section 7: Editing the Text View).

Note: that certain Motif resources cannot be changed dynamically once the widget has been created (this is indicated in the Motif Reference Manual). Such resources must only be specified by means of "Args" objects.

5. Layout (Geometry Management)

XXL simplifies the way to deal with the geometry management capabilities of the underlying toolkit. In Motif interfaces, geometry is ensured by specialized widgets, called Geometry Managers that can control the layout of their child widgets in three different ways as explained in the following subsections. These three cases are handled differently by the XXL Builder.

Explicit Geometry (BulletinBoard and DrawingArea)

These managers do not control automatically the geometry of their children. Geometry is then set by direct manipulation:

• by Control-Pushing with Mouse Button 1 (left button) to set position
• by Control-Pushing with Mouse Button 2 (middle button) to set size

Implicit Geometry (RowColum, Menus and variants)

The child widgets are automatically aligned in a row, a column, or a matrix. Their size is computed dynamically and their physical position depends on their rank in the widget tree.

The XXL Builder ensures this correspondence dynamically: this means that the ordering of widgets is dynamically changed in the Widget View when changing the left-to right order of the corresponding icons in the Graph View (by moving them with the mouse).

Note that the order of the XXL descriptions in the source code (in the Text View) are also changed when moving the icons in the Graph View.

Constrained Geometry (Form Widget)

The children can be attached one to another, or to a virtual and elastic grid. XXL offers a special-purpose object (called Attach) to specify such constraints and a specialized editor to configure them interactively in the Builder. To open this editor:

• Open the Resource Editor
• Select the Geometry filter
• Click on Geometry Constraints

Such constraints can also be specified textually as follows:

	 (Attach, 
		 "menubar",  "top:FORM,    left:FORM, right:FORM",
		 "message",  "top:menubar, left:FORM, right:FORM",
		 "scrollbox","top:message, left:FORM, right:FORM, bottom:FORM",
	 o)

6. Specifying Behaviors

Callback Editor

Call-back functions can be registered by adding Callback objects to Widget objects (Callback objects must be linked as children of the Widget objects they are relative to). These objects provide a way to specify a callback function call, that is to say:

• when the function will be called
• which C function will be called
• which data will be passed to this function (as a "client_data" argument)

Callback conditions can be changed by modifying the Name field in the Edit Bar (see section 2). Callback objects can be freely attached or detached to Widget objects and their source code can interactively be changed (like for other XXL objects) through the Text View (see Section 7: Editing the Text View).

At last, they can also be set by invoking the Resource Editor in the following way:

• Open the Resource Editor
• Select the Callbacks (or Connections) filter
• Open Resource Editor Menu:
  • by pushing on the More button
  • or by pushing Mouse Button 3 (right button) on the Callback Value you want to change in the list

Conditional Evaluation

Conditional Evaluation provides a way to re-evaluate dynamically a sub-tree of XXL objects when a certain condition is satisfied (i.e. when a certain event occurs on a certain widget). Cond objects work in the same way as Callback objects, except that they re-evaluate their child objects (that can be sub-trees of objects) instead of calling a call-back function.

Combined with Set objects (as children) they provide a simple way to change dynamically the resources of other widgets. Moreover, they can also be used to create new widgets or new Interface Instances at run-time.

Cond objects can be handled in a direct manipulation style like other XXL objects. They can also be modified in the same way as callback object through the Resource Editor, the Source Code Editor or by changing their condition value in the Edit Bar.

7. Editing the Text View

The Text View is only displayed upon request. Each source file (C, C++ or XXL Script file) corresponds to a separate Text window. To open the Text View that contains a given object:

• push with Mouse Button 3 (right button) on the icon to open the Icon Menu
• then click on Text.

The Text View is sensitive: clicking on the source code that corresponds to an XXL object will automatically select this object (more precisely, all the text that is actually included in this object will be selected, possibly including child objects).

The Text View also works in an "hyper-textual" fashion: clicking on variable that refers to another object will automatically scroll the text and select this object. Finally, note that clicking with Mouse Button 3 (right button) on the text will open the corresponding a pop-up Menu that is similar to the Icon Menu in the Graph View.

Changing the Source Code

The source code displayed in the Text View can be modified in two different ways:

• by changing the corresponding Graph View
• by changing the Text directly

You can also change the source code textually in the following way:

• Select an object by clicking on its source code in the Text View (or by clicking on the corresponding icon or control-clicking on the corresponding Widget)
• Click on Edit to open the Source Code Editor
• Change the text then click on Apply to apply changes

8. Saving an Interface

• Select the Interface object of the GUI you want to save (the Interface object must be at the top of the hierarchy. If not the case: add an Interface object to the top of your object tree).
• open the pop-up menu that is associated to the Interface object by pushing Mouse Button 3
• click on the Save / Make button.

A newly created Interface (i.e. by using the Visual Builder) can either be saved as an interpretable XXL Script file or as a compilable C/C++ file. In the latter case, the XXL Builder can optionally add an appropriate main function to the C file and generate a standard Makefile. Note that XXL GUI descriptions in the source code are exactly the same in both cases except that additional source code is added when generating a C file.

XXL Interfaces loaded from Script files (see next section) can also either be saved in Script or in C/C++ files. By opposition, XXL Interfaces that come from C programs can only be saved in C files (in other words, it is not possible to convert C files into Script files but the opposite is true). However, Interface subparts can freely be exchanged between separate Interface hierarchies (no matter the kind of source file they are actually located in).

9. Loading an XXL Script or a C/C++ Program

Any C, C++ or XXL Script file that contains XXL Interface descriptions can be edited by using the XXL Visual Builder . There is no restriction on the way this file was initially produced: it may have be written by a programmer, generated by the XXL Builder (or by any another tool) or both. XXL descriptions can always be re-interpreted by the XXL Builder, no matter in which file they were initially located. The only mandatory condition is that XXL textual descriptions follow the XXL specific syntax.

Loading XXL Script Files

It is possible to load as many XXL Script files as needed so that several interfaces can be created and edited simultaneously. There are three possible way to load Script files:

• Open the File Menu then click on Load and then on Load Script,
• Open the Graph View Menu (right button on background) then click on Load Script,
• type Control-L

• The Interface contained in the Script file is correct in which case the Graph View and the Widget View will be properly updated and Visual Edition can be performed,
• There are errors in the Script file that will be shown in a specific dialog box.

• newly created Interfaces are incrementally added to the Interface Menu. This list provides the user with a way to find back all existing Interfaces at a given time.
• Interface subparts can be exchanged at will between object trees and between all (Script or C) files. But the Interface object by itself is the only XXL object that can not be moved from one file to a different one.

Loading C and C++ Programs

By opposition to Script Files, C and C++ programs can not be loaded dynamically once the XXL Builder has been started. Instead, you must:

• compile your C program with the proper library (see Compilation Notes below)
• run this program with option -build:
  For instance, if your program name is "something", enter command:

  	 $  something  -build
  

  on the Unix Shell (you could also run "something" from your favorite debugger tool).

• all the XXL Interfaces included in the C files that composes the application,
• any needed XXL Script file (that you may want to load dynamically)

Interfaces are not implicitly edited (their Graph View and their Text View are not automatically created) in order to avoid unnecessary computation time. To edit a given Interface you must either:

• Open the Interfaces Menu (located in the Menu Bar) then choose the Interface instance you want to open
• Control-click on any of the widgets of this interface.

! Notes :

• This behavior is dynamical: Interfaces can be created and instantiated at any time by the C/C++ program (they do not need to be all created at initialization time). So, the Interfaces Menu is dynamically updated when new interfaces are created by the program (or when loading new Script files)
• In the current version of the system, all C/C++ sources files that must be edited (i.e that contain XXL Interfaces or call-back functions) must be located in the current directory (that is to say in the directory where the program was started). Other files will not be edited. Moreover, these files must not have been changed since compilation (otherwise the connection between the XXL objects and their original source code would be lost)

Compilation Notes

There a two different ways to compile C and C++ programs:

• Programs compiled with label -DNO_BUILDER and with library Xl.a cannot be edited visually,
• Programs compiled without this label and with library Xl.a AND library Xlb.a can be edited by using the Visual Builder

10. Don't Panic Section and Other Tips

If the XXL Builder is blocked ...

• Other X-Window applications are no blocked:

  it is likely that a Modal Dialog Box is opened somewhere (but it may be hidden by another window). Find and close this Dialog Box !

• Other X-Window applications are also blocked:

  The mouse pointer is probably be grabbed in which case pressing on the ESCAPE key should release the grab

Signal Protection

The Builder is protected against most Unix Signals (including SIGINT; usually = Control-C) and X-Window Error Handlers. A Dialog Box should normally pop up to ask the user whether he/she wants to continue or to exit the application. However:

• this protection is released after receiving several (about 10) successive Unix Signals

• Signal SIGQUIT (usually = Control-\) is only protected one time (typing two successive Control-\ will abort the program)