Basic Devguide Operations

This section explains how to use the Devguide Window menu and the controls in the top third of Devguide's base window.

Window Menu

To display the Window menu (shown in Figure 3-1), click MENU on the Devguide window's abbreviated menu button (in the window's upper left corner), or in its header, footer, or side borders.

Figure 3-1

Click SELECT on the Devguide window's abbreviated menu button to activate the default item from the Window menu. This usually closes the Devguide window and reduces it to an icon on the workspace because Close is the default Window menu choice. To reopen the window, double-click SELECT on the Devguide icon.

The items in the menu perform these functions:

• Close - Closes the Devguide window and reduces it to an icon.
• Full Size - This feature is disabled because Devguide's base window is a fixed size. Full Size is a generic Open Look function for manipulating windows.

• Move - Moves the Devguide window in mouseless mode. If you choose this, the corners of the window are highlighted. You can then use the arrow keys to move the window pixel by pixel. Hold down Control and the window moves in bigger jumps. Press return when you are done with the move.
• Resize - This feature is disabled because Devguide's base window is a fixed size. Resize is a generic Open Look function for manipulating windows.
• Properties (usually disabled) - If available, this brings up a window that allows you to set properties for the Devguide base window. (Do not confuse this with the property window discussed in "Customizing Devguide's Properties" on page 52!).
• Back - Moves the Devguide window behind any other windows in its area on the screen.
• Refresh - Redraws the contents of the Devguide window, restoring any parts of the window that are not completely restored after an action that obscures part of the window.
• Quit - Unloads all Devguide windows and quits Devguide. If you choose Quit while you have unsaved work, Devguide displays a Notice stating "You have unsaved edits." If you want to quit without saving your work, choose the Discard Changes button. If you want to go back to Devguide to save your work, choose Cancel. This Notice is shown in Figure 2-1 on page 7.

Working with Files

Click MENU on File to display the File menu shown in Figure 3-2. The File Menu contains items that enable you to create, load, save, rename, and unload files and projects.

Figure 3-2

Many items on the File menu open up a file chooser, or open a window with menu buttons whose items open up a file chooser.

File Chooser

The file chooser is a standard dialog box for file operations. A scrolling list of files and directories in your current directory is displayed when you open the file chooser. Double-clicking SELECT on a directory descends into that directory and displays a list of the files in the directory. Double-clicking on "go up a level" displays the files and subdirectories in the parent directory of your current directory.

An action button is located at the bottom of the file chooser dialog box. It is typically labeled Load or Save. Double-clicking on a file name or typing in a file name and pressing the action button loads or saves the file. If the file's full path name is longer than the line provided, a scrolling button appears and you can continue typing the name on the line.

The file chooser appears when you choose Load... or Save As... from the File menu. It also appears when you choose Save if you haven't named the file yet.

Load...

Load... loads one or more previously saved user interfaces. When you choose Load..., the file chooser (shown in Figure 3-3) appears. The file chooser window contains a list of all .P and .G files and all subdirectories in your current directory. Double-clicking on a directory descends into that directory and lists all its .P and .G files and all its subdirectories.

Devguide appends a .P extension to any project file that you save, and .G to any interface (GIL) file that you save, if you do not include the extension in the file's name.

Figure 3-3

You can load a .G file by double-clicking on the file name if it is visible in the file chooser. If a file name is not visible, you can use the scrollbar to find it or type its full path name into the Name field at the bottom of the file chooser and click Load.

Double-clicking on a .P file opens up the Project Organizer window. This window contains an icon for each .G file contained in the project.These .G files are not initially loaded into Devguide. You can load a .G file by double-clicking on its icon. You can also open the Project Organizer for a .P file by typing its full path name into the Name field at the bottom of the file chooser,

and clicking Load. To load the project, double-click on each .G icon present in the window. The Project Organizer is discussed in "Assembling Interfaces into a Project" on page 87.

When you load a .G file, Devguide opens the interface, displaying its elements on the workspace and its name in the lower right corner of the Devguide window. The file chooser then disappears. You can pin the file chooser to the workspace if you want it to remain open.

New Interface...

To create your first interface (.G file) after starting Devguide, you can

• Drag element glyphs from the palette, or
• Choose New Interface...

You must choose New Interface... to create a new interface after the first one. To begin building each new interface, drag a base window or pop-up window glyph onto the workspace, or create a menu.

New Interface... opens up the Interface Browser window. Each new interface receives a temporary name, such as Untitled1. As you build an interface, a tree representation of your interface appears in the Interface Browser. The Interface Browser is discussed in "Assembling Interfaces into a Project" on page 87.

Save

Save saves one or more user interfaces. It is enabled when you have loaded at least one .G file. Save has a submenu containing all currently loaded .G files as items. The submenu contains a default item labeled "All" when more than one .G file appears in the submenu list. See Figure 3-4.

Figure 3-4

When you choose Save, Devguide saves your interface as a GIL file with the extension .G. It turns the previously saved version of the GIL file into a backup file with the extension .BAK. For example, if you save an interface named face, Devguide saves it in a file named face.G. The file containing the last saved version of the interface is renamed from face.G to face.G.BAK. If you save a revised interface and then decide you don't like your revisions, you can always reload the .G.BAK file to undo your revisions. Files with a .BAK extension do not appear in the file chooser's window. You must enter the name into the Name field to load these files.

If you have not yet saved an interface and no other .G files are currently loaded, choosing Save brings up the Save As... file chooser (discussed below). If more than one interface appears on the workspace, choose the default Save submenu choice All to save all the interfaces. A Notice appears for each interface that hasn't been saved yet.

You can save a project file, such as foo.P, by choosing All from the Save submenu, provided all .G files contained in foo.P are loaded.

Save As...

Save As... saves a new user interface or lets you save a previously saved user interface or project file under a new file name. It is enabled when you have loaded a .P file or at least one .G file. (Only one .P file can be loaded at any time.) Save As... has a submenu containing all currently loaded .G files as items. It looks like the Save submenu shown in Figure 3-4 above, except that it is labeled Save As instead of Save.

When you choose an item in the Save As... submenu, the Save As file chooser appears (shown in Figure 3-5). The window contains a list of all .P and .G files and all subdirectories in your current directory. Double-clicking on a directory descends into the directory and lists all its .P and .G files and all its subdirectories. Type in the new name of your file on the line at the bottom of the file chooser.

Figure 3-5

If you haven't previously set a path name and a file name, Devguide proposes Untitled (with a number appended) as the interface file name and uses the current directory as the file's directory. Note that you must use standard operating system conventions when entering a path name or file name. Note also that when Devguide saves the interface, it appends .G to whatever file name you enter, if you have not already done so. Devguide appends .P to whatever file name you enter when you save a project file, if the file name you provide does not include the .P extension.

If you try to save an interface using a file name that already exists, Devguide displays a Notice window asking if you want to overwrite an existing file. To proceed and overwrite the existing file, choose the Save button. To cancel the save and protect the existing file, choose the Don't Save button. Note that if you do decide to overwrite an existing file, Devguide turns the existing file into a backup file as described in the previous section about the Save command.

Project...

To create a new project (.P file) or modify an existing one, choose Project... from the File menu. When you choose Project..., the Project Organizer window appears. The window contains all currently loaded .G files. You can create a new project if you have not loaded a project already. The Project Organizer is discussed in "Assembling Interfaces into a Project" on page 87.

Code Generator...

To generate and compile GXV or GOLIT code, and to run applications for these code generators, without using the command line, choose Code Generator... from the File menu. When you do this, the Code Generator tool appears. This tool is discussed in "Using the Code Generator Tool" on page 101.

Unload

Unload unloads one or more interfaces that are currently open in Devguide, removing all the interfaces' elements from the workspace. It is enabled when you have loaded at least one .G file. Unload has a submenu containing all currently loaded .G files as items. The submenu contains a default item labeled All when more than one .G file appears in the submenu list. Choose All to unload all currently loaded interfaces. The Unload submenu looks like the Save submenu shown in Figure 3-4 on page 35, except that it is labeled Unload instead of Save.

If you unload a file that has been edited but not saved, Devguide displays a Notice window stating, "You have unsaved edits," similar to that shown in Figure 2-1 on page 7. Click SELECT on the Save button to save your work. If you want to unload an interface without saving your work, choose the Discard Changes button. If you want to abandon the unloading process so you can save your work before you unload the interface, choose Cancel.

If you unload a project that has been edited but not saved, Devguide displays a Notice stating that the project has unsaved edits. An edited project is one in which you have added or deleted .G files.

Devguide displays a third type of Notice if you edited more than one interface when you choose Unload All. Choose Overwrite All to save all edited files. Choose Overwrite selectively to save certain files. A Notice appears for each file that has been modified.

Viewing Layers, Windows, and Interfaces

Click MENU on View to display the View menu shown in Figure 3-6.

Figure 3-6

Next Layer

If you select a pane in a layer of panes, Next Layer brings the next pane to the top of the parent base window. See "Layering Panes" on page 99 for a discussion of layered panes.

Dismissed Windows

Selecting Dismissed Windows returns any pop-up windows to the workspace that you earlier dismissed from the current user interface by choosing Dismiss from their window menu. Note that Dismissed Windows won't open base windows or restore deleted windows.

You can also recover any dismissed window by selecting it in the Pop-up Windows scrolling list.

Interfaces

Choose Interfaces to display a submenu containing a list of all .G files that you have loaded into Devguide (see Figure 3-7). The default choice All appears in the submenu if more than one .G file is listed. When you choose a .G file name, the Interface Browser for that interface appears on the workspace. When you choose All, an Interface Browser for each listed interface appears on the workspace.

Figure 3-7

Editing Interfaces

Click MENU on Edit to display the Edit menu shown in Figure 3-8. This menu contains items that help you move or copy selected elements from a user interface to other interfaces. Note that each of these editing functions is also available in element pop-up menus (Figure 3-20 on page 60).

Figure 3-8

Undo

Undo reverses the last editing action. Use it to retrieve deleted or cut elements, or to remove pasted elements. Note that Undo does not restore the contents of the elements clipboard that were removed by an editing action.

Cut

Cut removes any selected UI elements from the workspace and places them on the element clipboard. Each time you use Cut, you replace the contents of the clipboard with the elements you cut.

Copy

Copy copies any selected UI elements in the workspace and places their copies on the element clipboard. Each time you use Copy, you replace the contents of the clipboard with the elements you copied. Copy does not remove any UI elements from the workspace.

Paste

Paste pastes any UI elements currently on the element clipboard into the currently open user interface.

If you have a window on the clipboard, first deselect it, then choose Paste to put the window on the workspace.

If you have a control area or a pane on the clipboard, you must first select a UI window before you can use Paste. When you use Paste, the control area or pane appears in the selected window.

If you have one or more elements on the clipboard, you must first select a UI control area before you can use Paste. When you paste the controls, they appear in the selected control area.

If you have mixed elements on the clipboard--for example, a window with a control area and controls--Paste follows the rules for pasting the highest-level containing element. For example, you can paste a window with a control area and controls anywhere on the workspace, but you can only paste a control area with controls within a selected window.

Delete

Delete removes any selected UI elements from the workspace without placing them on the elements clipboard. You cannot retrieve deleted elements by pasting them from the clipboard.

Arranging Elements

Click MENU on Arrange to display the Arrange menu shown in Figure 3-9. This menu contains items that help you arrange UI elements in a user interface.

Figure 3-9

Group

Choosing Group combines all currently selected UI control elements into a group. See "Controls" on page 11 for a list of all UI control elements, and "Grouping UI Elements" on page 75 for a full description of groups.

Ungroup

Choosing Ungroup decomposes the currently selected group into its constituent UI elements. See "Grouping UI Elements" on page 75 for a full description of groups.

Align...

Choosing Align... displays the Align pop-up window shown in Figure 3-10. You can align selected sets of controls using the options in the Align window.

If you want to leave selected controls' vertical and horizontal alignments as they appear, do not select any of the vertical or horizontal alignment options. Deselect any selected option that you do not want to include in your alignment scheme.

Figure 3-10

You see four alignment categories in the window:

Horizontal Moves the selected controls to line them up in a single row. You can choose from three horizontal alignment schemes:

Aligns the UI elements with respect to the top of the highest element.

Aligns the UI elements so that their centers fall on a common (invisible) horizontal line, with no shifting to the left or right.

Aligns the UI elements with respect to the bottom of the lowest element.

Vertical Moves the selected controls to line them up in a single column. You can choose from four vertical alignment schemes:

Aligns the UI elements with respect to the right side of the topmost element's label. For example, if the labels of all selected elements end with a colon, the colons line up.

Aligns the UI elements with respect to the left side of the leftmost element.

Aligns the UI elements so that their centers fall on a common (invisible) vertical line, with no shifting up or down.

Aligns the UI elements with respect to the right side of the rightmost element.

Distribute Distributes space evenly between selected UI elements. You can set the space length in pixels using the numeric text fields at the right.

Figure 3-11

• The top option in Figure 3-11 distributes space evenly between UI elements that are arranged horizontally. This will arrange elements horizontally as well as distribute space evenly if you also choose a Horizontal item.
• The bottom option in Figure 3-11 distributes space evenly between UI elements that are arranged vertically. This will arrange elements vertically as well as distribute space evenly if you also choose a Vertical item.

Center Centers the selected UI elements with respect to the sides of the parent control area.

Figure 3-12

• The first option in Figure 3-12 centers the bounding box of the selected elements with respect to the left and right borders of the parent control area.
• The second option in Figure 3-12 centers the bounding box of the selected elements with respect to the top and bottom of the parent control area.

You can get the same alignment effect by selecting a set of UI elements, and choosing the Align or Distribute submenus from an element's pop-up menu.

Grid

To set up a placement grid in a control area, choose a grid setting. Click MENU on the Arrange button and click MENU on the Grid item to display the Grid submenu shown in Figure 3-13. It offers grid settings of 1, 2, 4, 8, 10, 12, 16, 32, 48, and 64 pixels. If you choose a setting of two or more pixels, Devguide creates an invisible grid in the control area with grid squares the size of your grid setting. For example, if you choose a grid setting of four pixels, Devguide creates a grid of four-by-four-pixel squares. If you choose a setting of one pixel, you turn the grid off in the control area.

---

Note - Devguide has a default grid size of eight. That is, every time you start Devguide the grid size is set to eight, unless you customize your Devguide environment. See "Customizing Devguide's Properties" on page 52 for a discussion of how to change this default value.

---

Figure 3-13

Any controls already in place in the control area don't change position when you change the grid setting. However, once you turn the grid on, any new controls you place or move in the control area snap into place, aligned by Devguide so their upper-left corner falls on a grid intersection (as shown in Figure 3-14). The grid is on by default; you can turn it off and on using Grid Snap, described below.

If you choose larger grid settings, the controls will fall into more readily noticeable columns and rows. The Grid size you choose applies to any control area in your interface, during the current session with Devguide.

---

Note - You cannot display the grid. Figure 3-14 is only an illustration of aligning elements using the grid; the grid is always invisible.

---

Figure 3-14

Grid Snap

If a grid size has been chosen, you can use Grid Snap to temporarily turn the grid off and on. The grid is on by default. Click MENU on the Arrange button and click MENU on the Grid Snap item to display the Grid Snap submenu. Two items--On and Off--appear; click SELECT or MENU on your choice:

• On - Turns on the grid.
• Off - Turns off the grid. To reinstate the chosen grid size, choose On.

Editing Features Using Property Windows

Click MENU on Properties to display the Properties menu shown in Figure 3-15. This menu contains items that open windows to customize Devguide's properties and edit the properties of user interface elements.

Figure 3-15

Selection...

Selection... opens the property window for a single UI element that is selected on the workspace. It is the default menu item for the Properties menu.

Devguide...

Devguide... opens the Devguide Properties window. Use this window to choose a default toolkit and set the default grid size for Devguide.

You can learn more about the Devguide Properties window in "Customizing Devguide's Properties" on page 52.

Windows

Windows contains items to open base window and pop-up window property windows:

• Base Windows...
• Pop-up Windows...

When you choose one of these element items from the Windows submenu, the Properties menu closes and a property window for that type of element appears on the workspace. See Chapter 4, "Devguide Reference" for element property window descriptions.

Panes

Panes contains items to open property windows for the UI pane elements:

• Control Areas...
• Canvas Panes...
• Term Panes...
• Text Panes...

When you choose one of these element items from the Panes submenu, the Properties menu closes and a property window for that type of element appears on the workspace. See Chapter 4, "Devguide Reference" for element property window descriptions.

Controls

Controls contains items to open property windows for the UI control elements:

• Buttons...
• Messages...
• Settings...
• Text Fields...
• Sliders...
• Gauges...
• Lists...
• Drop Targets...

When you choose one of these element items from the Controls submenu, the Properties menu closes and a property window for that type of element appears on the workspace. See Chapter 4, "Devguide Reference" for element property window descriptions.

Help...

Help... opens the Help Editor window where you can enter and edit help text for elements of the user interface. You can learn how to use the Help Editor window in "Editing Help Text" on page 61.

Menus...

Menus... opens the Menu Editor Window where you can create and edit menus. For details on making and editing menus, read "Making and Editing Menus" on page 65. For details on attaching menus to buttons, canvas panes, control areas, and scrolling lists, read the description of those elements in the next chapter.

Groups...

Groups... opens the Groups window where you can choose layout, alignment, and anchoring schemes for your group. Read "Grouping UI Elements" on page 75 to learn how to use the Groups window and how to construct groups.

Connections...

Connections... opens the Connections Manager window where you can create and modify connections between UI elements. You can learn about connections and how to use the Connections Manager window by reading "Handling Events Using Connections" on page 81.

Building and Testing

The Interface Setting to the right of the Devguide control menu buttons offers two choices that determine the way UI elements on the workspace behave.

Build

Build is the default choice. When it is set, you can build a user interface, putting together UI elements from the Devguide window and editing them to change their size, position, properties, and other attributes. The UI elements

don't act as they do when running in your final program. For example, when you click SELECT on a button, it doesn't highlight and run a function. Instead, it selects the button so you can edit it.

Test

Test helps you test how your user interface works. When Test is set, UI elements act as if they were part of a finished user interface; that is, buttons and settings highlight, menus display, and so forth. You can pin menus to the workspace that are pinnable. Whatever Help text you have written appears. Initial values and states take effect. Connections supported by the XView toolkit work in Test mode if you use the actions and events provided by Devguide. That is, any predefined When and Action menu items for your toolkit that are also supported by the XView code generator work in Test mode.

You can't edit any interface elements or load and save files when Test is selected, so when you're finished testing you should return the interface setting to Build.

Using the Drag and Drop Target to Load GIL Files

The drag and drop target to the right of the Interface Setting offers you the option of loading a GIL file into Devguide by dropping the file onto the drag and drop target. Devguide provides four ways to drop a GIL file onto the target:

• Select text and drag it onto the target.
• Select one or more files from the File Manager and drag the file icons onto the target.
• Select one or more Mail attachment GIL files and drag the file icons onto the target.
• Select and drag an entire mail message that includes a GIL file onto the target. The mail header is automatically ignored.

When you perform any of these operations, the GIL files are loaded and the interfaces appear on the workspace.

---

Note - You can also load a GIL file into Devguide by dropping its file icon into the Project Organizer window. The corresponding interface appears on the workspace. If you have loaded a project, the new GIL file is added to the project.

---

Understanding the Element Information Area

The area in the Devguide window below the element glyphs is the element information area, shown in Figure 3-16. The information area presents information about elements on the workspace and the pointer's position as you move it over those elements.

Figure 3-16

Element Field

The Element field is the top message field in the information pane below the UI element glyphs. As you move the pointer around the workspace, the Element field displays the name of any UI element under the pointer. If there is more than one UI element under the pointer, the Element field displays the name of the top element. For example, if you move the pointer over a UI window with a control area full of controls, the Element field might display window1 when the pointer is over the UI window's background, then controls1 as the pointer moves over the UI control area, and finally button1 when the pointer comes to rest on top of a UI button in the control area.

For layered panes, the Element field displays the layered panes' name, the relative position of the pane, and the number of panes in the layer. See "Layering Panes" on page 99 for details on layered panes.

Note that the Element field displays only the name of elements created by Devguide.

Position Field

When the pointer is on a UI element, this field gives the position of the element in terms of a pixel address.

• Windows are measured from the upper-left corner of the workspace.
• Panes and control areas are measured from the upper-left corner of the window.
• Controls are measured from the upper-left corner of the control area.

Size Field

When the pointer is on a UI element, this field displays its X (width) and Y (height) size in pixels.

Pointer Field

The Pointer field shows X (horizontal) and Y (vertical) coordinates that give the pointer's current location within the UI window, pane, or control area underneath it. The coordinates are measured in pixels from the upper-left corner of the UI window or pane. For example, as you move a pointer through unoccupied areas of a UI window, the Pointer field displays its coordinates as measured from the upper-left corner of the window. When you move the pointer into a UI pane or control area within the window, the Pointer field displays the coordinates as measured from the upper-left corner of the UI pane or control area instead of from the upper-left corner of the UI window.

Customizing Devguide's Properties

Devguide's Properties window allows you to specify a toolkit and default grid size for Devguide. Choose Devguide... from the Properties menu to display the Devguide Properties window, shown in Figure 3-17.

---

Note - You should configure Devguide to reflect your toolkit and grid size preferences the first time you start Devguide. After that, your selections are used as default values each time you start Devguide. You can change these values at any time by using Devguide's Properties window.

---

Figure 3-17

Specifying the Toolkit

Below the Devguide Properties window's header you find an abbreviated menu button labeled Toolkit. The default choice is the XView toolkit. Devguide also supports the OLIT toolkit. When you choose a toolkit, the Connections Manager window's When and Action menus appropriate for that toolkit are loaded. If you do not set a toolkit choice, Devguide assumes you are building an XView application, and configures the Connections Manager window menus accordingly. For further details on connections and the Connections Manager window, see "Handling Events Using Connections" on page 81.

If you plan to generate application code, you should choose a toolkit right after starting Devguide. Once you choose a toolkit, you can apply this choice to the current and future environment by clicking SELECT on the Apply button. Clicking SELECT on the Reset button returns the Toolkit setting to that in effect when you last chose Apply.

You should maintain a single toolkit choice throughout an application. The code generator you use generates code only for those connections it recognizes. For example, suppose you choose OLIT to design an interface and accidentally choose GXV to generate code. GXV then produces XView code and converts any OLIT-specific connections to generic (empty) callbacks.

Setting the Grid Default

The Grid Default setting, shown in Figure 3-17 on page 53, enables you to change Devguide's default grid size of eight. You can do this by selecting one of the available grid size settings. Once you choose a grid size, you can apply this choice to the current and future environment by clicking SELECT on the Apply button.

Clicking SELECT on the Reset button returns the Grid Default values to that in effect when you last chose Apply.

Producing a .guidedefaults File

If you change either of Devguide's properties at any time, Devguide produces a .guidedefaults file and stores the file in your home directory. This file contains the Toolkit and Grid Default selections set for your environment. .guidedefaults is a resource file similar to .Xdefaults. This file also stores the code generator that is used as the default when the code generator is invoked for the first time in a Devguide session.

Adding Elements to a User Interface

The glyphs in Devguide's palette represent elements you can add to a user interface. This section describes how you use the glyphs to place UI elements on the workspace to build a user interface, and how you edit the UI elements once they're in place.

Placing UI Elements

To place a UI element on the workspace, drag its glyph from the Devguide window. To drag an element glyph, put the pointer on it, press SELECT, then drag it onto the workspace. Release SELECT to drop the glyph--the element it represents then appears on the workspace where you dropped the glyph.

Controls

You can place a control UI element only within a control area. If the control area's grid is turned on, the upper-left corner of the control UI element snaps into place on the nearest grid intersection. See "Arranging Elements" on page 41 for more information about the grid.

---

Note - Devguide provides no glyph for an abbreviated menu button, a nonexclusive setting, or a multiline text field. To place an abbreviated menu button in your application, drag out the button glyph and set the element's Type to Abbreviated Menu. To place a nonexclusive setting in your application, drag out any setting glyph and set the element's Type menu to Nonexclusive. To place a multiline text field in your application, drag out either text field glyph and set the element's Field Type to Multiline.

---

Panes

You can place a pane only within a base window or pop-up window UI element. Any border of the pane you place that is within 32 pixels of an existing window or pane border snaps to the existing border.

You can layer panes on top of each other. If you drag any pane glyph directly onto an existing pane, the new pane is positioned and sized to the one underneath it. See "Layering Panes" on page 99 for details.

Sizing Windows and Panes

Window and pane UI elements can be re-sized once you drop them onto the workspace.

Windows

To change the size of a base or pop-up window, move the pointer onto any one of the window's four resize corners and drag the corner until you stretch the window into the size you want. You can also set the precise size of the window using the Rectangle line in the pane's property window.

Panes

To change the size of a pane, first select it. Once selected, the pane shows a boundary that includes resize corners and handles. To move two adjacent sides of the text pane at once, drag the resize corner touching both sides. To move a single side of the pane, drag the resize handle on that side. You can also set the precise size of the pane using the Rectangle line in the pane's property window.

Moving UI Elements

To move a UI element already in place, simply drag it to the desired position.

Windows

To move a base or pop-up window to a new location, drag it by its header or border.

Panes

After initial placement, panes follow grid snap when you move them. To move a pane UI element to a new location:

• Use the Move Pointer to drag the pane to its new location. The Move pointer, shown in Figure 3-18, appears after you select the pane and move the pointer between resize corners near the pane's border.

Figure 3-18

• Use the resize corners to first stretch one corner into the new location you want, and to then stretch the other corners to fit the pane into the new location.

Note that you can't move a pane to any location outside of a UI base window or pop-up window.

Controls

To move a control UI element to a new location, simply drag it. Controls follow grid snap when you move them. You can also move a control by selecting it and using the keyboard arrow keys. You can align a particular control to other controls by using the Align item in the control's pop-up menu.

Note that you can't move a control to any location outside of a UI control area.

Cutting, Copying, and Pasting UI Elements

To cut or copy and paste UI elements, first select the element and choose cut or copy from its pop-up menu. For panes and control UI elements, select the target element and choose paste from its pop-up menu. The pane or control element (or a copy) appears on the target element. For base windows and pop-up windows, first deselect the window, then choose paste from the window's pop-up menu. The window (or a copy) is pasted on the workspace.

Use the editing commands in the UI element pop-up menu:

• Cut removes the UI element and its contents from the workspace and places it on the clipboard.
• Copy places a copy of the UI element and its contents on the clipboard.
• Paste places a copy of the clipboard contents onto appropriate areas of the workspace. The usual placement restrictions apply; for example, you can only paste a control UI element into a control area. You must first select the parent object into which to paste a UI element.
• Delete removes the UI element from the workspace without placing it on the clipboard.
• Undo reverses the last editing action.

You can cut, copy, and paste groups that you create. For more information about groups, see "Grouping UI Elements" on page 75.

If you cut (or copy) and paste two elements that are linked via a connection, the connection is cut (or copied) and pasted, too. For example, suppose you define a connection from button1 to pop-up1, and you copy the button and pop-up to make button2 and pop-up2, respectively. Then button2 is linked to pop-up2 via a connection with the same When and Action menu choices as the connection for button1 and pop-up1. For more information about connections, see "Handling Events Using Connections" on page 81.

Selecting and Deselecting Elements

You must select a UI element before you can edit it. You can select a single element either by clicking SELECT on the element in the workspace, or by opening a property window for that type of element and clicking SELECT on the element's name in the scrolling list at the top of the window. Once you select an element, its name appears selected in the property-window scrolling list.

You can select a group of elements you have defined by selecting any element in the group. (See "Grouping UI Elements" on page 75 for a discussion of groups.)

To deselect a selected element, click ADJUST on it.

---

Note - If you have a two-button mouse, the ADJUST function is performed by holding down the Shift key and clicking the SELECT (left) button.

---

---

Note - When a window is selected, the word SELECTED appears in its right footer. When a canvas or pane is selected, it appears with resize handles. When other UI elements are selected, they appear with a box drawn around them.

---

Selecting Multiple Elements

If you want to dismiss, cut, copy, paste, delete, or move more than one UI element at a time, you can select several elements at once, using a technique called adjusted selection. You can use either one of two adjusted selection methods.

The first method is to select elements on the workspace by clicking ADJUST on them. Whenever you select an element using ADJUST, all previously selected elements remain selected, allowing you to select many elements at once. To deselect a single selected element (from a collection of selected elements, for example), click ADJUST on it. The element is deselected while all other selected elements remain selected. To deselect all elements but one, click SELECT on a single element. The element is selected while all previously selected elements are deselected. Click SELECT on the workspace to deselect all UI elements.

To use the second adjusted selection method, drag a bounding box across the UI controls you want to select in the control area. To drag the bounding box, move the pointer into a clear area within a control area or the workspace, then hold down SELECT, and drag the pointer directly across the controls you want to select. As you drag, an outline (bounding box) stretches to enclose the controls. When you completely enclose the controls you want, release SELECT and the enclosed controls are selected. See Figure 3-19 below for an example.

Figure 3-19

Once you select a collection of elements, each element indicates that it is selected. You can then press MENU to see a pop-up menu for the elements. If you select Cut, Copy, Paste, or Delete, Devguide performs your editing action on all the elements in the collection. If you use the Align... pop-up, Devguide aligns all of the controls in the collection to the grid in their control area. If you use adjusted selection to select a set of UI elements, you can drag the entire set to a new location by putting the pointer over any one of the elements, holding down SELECT, and dragging the pointer.

Opening UI Element Property Windows

Property windows are where you make changes to customize individual UI elements. You can open a property window in several ways.

• Double-click SELECT on a UI element to open its property window.
• Click SELECT on a UI element to select it, press MENU to display its pop-up menu (shown in Figure 3-20), and choose Properties to open its property window.

Figure 3-20

• Click SELECT on a UI element to select it, and press the Properties menu button in the Devguide main window.
• Pop up the Properties menu (shown in Figure 3-15 on page 47) from the Devguide main window and choose the appropriate property window from the menu.

---

Note - The application area of a window can be entirely covered by a control area, text, term, or canvas pane. If so, you can access the Windows property window by double-clicking on the window's footer. (The window's header is under the control of the window manager. It cannot be used to access the window property window.)

---

Adding Glyphs and Icons to UI Elements

Many UI elements can have glyphs associated with them, such as for the element's label. Base windows have icons associated with them. In either case, the format of the file containing the glyph or icon image depends on the toolkit code generator you use.

Devguide supports two bitmap file formats: Sun Icon and Mono X bitmap (XBM). By toolkit, the file you specify must be:

• GXV - in Sun Icon or XBM file format
• GOLIT - in XBM file format

Editing Help Text

All interface elements except base windows and pop-up windows can include help text. Help text appears when you put the pointer over an element and press the Help (or F1) key.

To add help text to an element or to edit existing help text, use the Help Editor window shown in Figure 3-21.

Open the Help Editor window in either of two ways:

• Choose Help... from the Properties menu in the Devguide window.
• Choose the Help Text... button in an element properties window.

Figure 3-21

When Devguide creates source code, it includes help text attached to each element for which you created help text.

Components

The top of the Help Editor window is the Components scrolling list, which contains the names of all of the elements in the current user interface that can include help text. If you open the Help Editor window from an element's property window, the name of the element is automatically selected. To create or edit help text for any of the other elements, simply select the name of the element from the list.

Help Text

The text pane labeled Help Text in the bottom of the window contains the help text for the element selected in the Components list. It includes a vertical scrollbar you can use to scroll through the text, and also has a standard text pop-up menu. To see the pop-up menu, put the pointer on the text pane and click MENU. The pop-up menu contains five submenus that offer file handling, text views, text editing, text finding features, and extra features. All of these are standard features described in the OpenWindows User's Manual.

Choosing a Color

You can set the colors for each element in an interface. Windows, panes, and control areas each have a foreground color and a background color; controls have simply a color. To set any of these colors in an element, open the property window for the element and look for the Foreground, Background, or Color menu button. These three buttons have the same menu, shown in Figure 3-22.

Figure 3-22

You can choose a color in two ways:

• You can choose a color from a palette of colors displayed from the Palette submenu. Devguide then enters the color name into the text field to the right of the button. (This submenu is disabled if you have a monochrome monitor.)
• You can use the Color Chooser window. You can enter a color name directly into the text field to the right of the button if you know the proper color name. A rectangle of color appears to the left of the line.

The Palette submenu is an accelerator for the Color Chooser. Use the Color Chooser if you want to view each available color with its associated name.

You must click SELECT on the property window's Apply button to set the colors on the screen.

To display the palette of colors, press MENU on the Color, Foreground, or Background menu button and open the Palette submenu. Then click MENU over your color choice. The color's name appears on the line by the menu button, and a rectangle of color appears to the left of the line.

To open the Color Chooser window (shown in Figure 3-23), click MENU on Chooser..., or click SELECT on the Foreground, Background, or Color button in a property window.

Figure 3-23

The scrolling list at the top of the window offers you the full choice of colors. Scroll through the list to find a color you want, then click SELECT on it; the color name appears in the Color text field below the scrolling list, and the

square at the end of the text field turns the shade of the color you selected (unless you have a black and white monitor, in which case it remains black). You can also select a color by entering its name directly in the Color text field.

Once you have a color chosen, you can apply it to the selected UI element by clicking SELECT on the Apply button. The color name is inserted in the appropriate text field in the element's property window, and you see the element change to the color you set. If you decide you don't like your new color, choose the Reset button; the color reverts to the color that was set when you first opened the Color Chooser window.

Making and Editing Menus

A menu displays a set of options to a user so the user can choose one of them. There are two types of menus:

• A pop-up menu, which can appear anywhere on the workspace not covered by a control, and can be attached to different interface elements. A user usually displays a pop-up menu by moving the pointer onto an element and pressing MENU.
• A button menu, which is attached to a menu button. A menu button is a type of button that includes a menu mark to show that a menu is attached. A user displays a button menu by moving the pointer onto the menu button and pressing MENU.

The options displayed within a menu are called items, and can be labeled with text or with an image, as shown in the example in Figure 3-24.

Figure 3-24

When a user chooses an item, the item can do one of two things:

• Initiate an action by calling a procedure from the main body of the program
• Open a submenu with items of its own

Menus can have as many layers of submenus as you wish to add. Any item that opens a submenu is followed by a menu mark to indicate that a submenu is attached.

Menu Editor Window

To create and edit menus, items, and submenus, use the Menu Editor window shown in Figure 3-25. To display the window, choose Menus... from the Properties menu in Devguide's base window. You can also open this window by choosing New... from the Menu button menu on a control area, canvas pane, button, or scrolling list property window.

Figure 3-25

Creating, Editing, and Moving Menus

The top half of the window contains the Menus list, a scrolling list that lists any menus created for the currently open user interface. It should be empty when you first start a new interface. Once you create menus, they appear in the list, where you can select any menu by putting the pointer on its name and clicking SELECT. The text fields and other controls below the Menus scrolling list (called the Menu controls) show and set the properties of the currently selected menu.

To add, delete, and move menus in the Menus list, use the Insert and Edit buttons below the list.

Create Button

Each time you click on the Create button, you create a new menu and add it to the list. It appears in alphabetical order within the other menus in the list. The menu controls below the Menus list display the properties of the new menu.

Edit Button

The Edit button below the Choices scrolling list offers items that cut, copy, paste, and delete menus within the Menus list. Use these items to move menus from one location to another in the list:

• Cut - Removes the selected menu from the scrolling list and places it in the menu clipboard. Cutting a menu removes all of the menu's items as well as the menu.
• Copy - Puts a copy of the selected menu into the menu clipboard. Copying a menu copies all of the menu's items and properties.
• Delete - Removes the selected menu from the scrolling list without putting it in the menu clipboard. The contents of the clipboard remain untouched when you choose this item. Deleting a menu removes all of the menu's items as well as the menu.

Setting Properties of the Selected Menu

Use the top half of the Menu Editor window to set the properties of the currently selected menu in the Menus list.

Object Name

Object Name establishes the name that Devguide gives the menu in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the menu.

Title

Contains the label that appears in the menu.

Type Menu Button

The Type menu button is an abbreviated menu button that offers you a choice of three different types of menus:

• Command - The most common type of menu, where each item initiates a procedure (a command) or calls up a submenu.
• Exclusive - A menu which presents items listing possible settings for a situation. When you choose an item, you turn on that setting and automatically turn off any other possible settings.
• Nonexclusive - A menu which presents items listing possible settings for a situation. When you choose an item, you turn on that setting. You can turn on as many settings in the menu at one time as you wish.

To choose one of the menu types, click MENU on the abbreviated menu button to open its menu. Click SELECT on whichever menu type you want to set. The menu closes, and your choice is displayed to the right of the menu button.

Columns

Columns contains the number of columns used to display items in the menu. The default setting is 1, where all items appear in a single column.

If you change the text field to a value of more than one, the menu's items appear in multiple columns. For example, if you set Columns to 3, the items appear in three columns. When the window system arranges the items in the menu, it uses the order of the items in the Items list, starting at the top of the first column and filling it to the bottom, then starting at the top of the next

column and filling it to the bottom. Figure 3-26 shows a menu with three columns. The numbered items show how the window system arranges the items.

Figure 3-26

Menu Is

Adds a pushpin to or removes a pushpin from a menu.

• Pinnable - Menu appears with a pushpin and menu is pinnable
• Not Pinnable - Menu appears without a pushpin

Connections...

The Connections Manager window appears. You can established connections between the menu and other existing UI elements.

Inserting and Editing Menu Items

The bottom half of the window contains the Items list, a scrolling list that lists any items contained in the currently selected menu in the Menus list. It has a menu button labeled "Items" to its left. It should be empty when you first start a new interface, and should remain empty until you create a menu and add items to that menu. Once you create items, they appear in the list where you can select any single item by putting the pointer on its name and clicking SELECT. The text fields and other controls below the Items scrolling list (called the Item controls) show and set the properties of the currently selected item.

To add, delete, and move items in the Items list, use the Insert and Edit buttons below the Items list.

Insert Button

The Insert button offers items that insert a new menu item at different locations in the scrolling list. Choose one to insert a new item where you want it:

• Before - Inserts a new item before the selected item
• After - Inserts a new item after the selected item
• Top - Inserts a new item at the top of the scrolling list
• Bottom - Inserts a new item at the bottom of the scrolling list

Devguide names each item you insert "Item."

Edit Button

The Edit button offers items that cut, copy, paste, and delete items within the scrolling list. Use these items to move items from one location to another:

• Cut - Removes the selected item from the scrolling list and places it in the item clipboard.
• Copy - Puts a copy of the selected item in the item clipboard.
• Paste - Puts the contents of the clipboard in the scrolling list. The four items in its submenu offer Before, After, Top, and Bottom, which insert the clipboard contents in the same locations as the corresponding items in the Insert button menu.
• Delete - Removes the selected item from the scrolling list without placing it in the item clipboard. It leaves the contents of the item clipboard intact.

Setting Properties of the Selected Menu Item

Use the bottom half of the Menu Editor window to set the properties of the currently selected item in the Items list.

Label

Contains the label (or glyph) that appears as the item's label. The interpretation of the Label text field depends on the value of the Label Is setting.

Label Is

Label Is determines whether the item is labeled with text or with a glyph. See "Adding Glyphs and Icons to UI Elements" on page 61 for information on file formats.

• Text - Inserts the text entered in the Label text field as the item's label.
• Glyph Filename - Inserts the glyph described in the file specified in the Label text field as the item's label.

Item Is

Item Is determines three important properties of menu items that become effective when the menu first appears. A default item appears in the menu enclosed within a lozenge. If the menu is attached to a button and the user clicks SELECT on the button, the user chooses the default item. Select Normal to ensure that an item isn't the default item.

• Active - Makes the item active (able to be selected)
• Inactive - Makes the item inactive
• Normal - Makes the item a normal item
• Default - Makes the item a default item
• Not Selected - Makes the item be not selected
• Selected - Makes the item be selected

Note that only one item in each menu can be a default item.

Color

Press MENU on the Color menu button to display the Chooser... and Palette menu items. Palette has an attached submenu of colors. Press Chooser... to open the Color chooser. Color sets the menu's color.

Submenu

Use Submenu to attach an existing menu to the item selected in the Items scrolling list. Submenu contains two items, New... and Names. Names has an attached submenu that lists existing menu names. Any name you choose from the Names menu is entered on the text field to the right of the Submenu button.

This menu becomes a submenu of the item selected in the Items scrolling list. It is attached so the submenu opens when the user selects the item in the finished interface.

You can enter the name of an existing menu in the Submenu text field, instead of choosing it from Names. If the menu you want to attach to the selected item does not yet exist, you must create it first. You then attach it as a submenu as just described.

New... is disabled because it is not applicable to the Menu Editor window.

Connections...

The Connections Manager window appears. You can establish connections between the menu item and other existing UI elements.

Applying Editing Changes to Menus and Menu Items

To apply the changes you made to a selected menu or menu item, click on the Apply button. Note that if you select a new menu or menu item without clicking on the Apply button, Devguide automatically applies all the editing changes you made to the previously selected menu or menu item.

Leaving the Menu Editor Window

To apply any changes you made in the Menu Editor window, choose the Apply button at the bottom of the window. If you dismiss the Menu Editor window (by clicking SELECT on its pushpin) without using the Apply button to make changes, your changes aren't made to the currently selected menu or item. If you reopen the Menu Editor window, you'll see your changes still in place, but unapplied.

To get rid of unapplied changes, choose the Reset button. It resets Menu and Item controls to their settings at the time you last chose the Apply button or chose a new menu from the Menu list.

Attaching a Menu to a UI Element

Once you create a menu in the Menu Editor window, you can attach it to a UI control area, canvas pane, scrolling list, or button. To do so, display the pane or control element's property window, press the Menu button, and select the menu's name from the Names submenu. Devguide enters the menu name on the line to the right of the Menu button. If you know the name of the menu you want, you can enter that name on the line yourself. When you click Apply on the element's property window, the menu is attached to the element.

Alternatively, you can display the selected element's property window, and click the Connections... button, or choose Connections... from the Properties menu. Choose the element as the Source, the menu as the Target, the When as Menu, and the Action as Show. Click Connect to establish the connection.

Detaching a Menu From a UI Element

To detach a menu from a UI element, either:

• Erase the menu's name from the Menu line in the element's property window and click SELECT on Apply, or
• Open the Connections Manager window, select the connection that attaches the menu to the UI element, and click Disconnect.

Viewing a Menu and Its Contents

If you want to see a menu with its items and submenus as it will appear in your finished user interface, enter Test mode by selecting the Test option in Devguide's window. Move the pointer over the element to which the menu is attached, then click MENU. The menu appears, displaying its items in text or images, as you labeled them. Any items with an attached submenu show a menu mark. To see the submenu, move the pointer over the item and click MENU. The submenu and all of its items appear. You can, of course, open submenus from within submenus, and continue down to as many menu layers as you created in the Menus Properties window.

Grouping UI Elements

A group is a collection of UI elements in your user interface that is treated as one unit. Once the elements within the group are positioned as you wish, you can move the group around, and the relative positioning of the individual objects remains the same.

You can place constraints on the objects in a group such as spacing and alignment. You can also place external constraints on the group, by anchoring it to another object. By supplying this information, code generators and toolkits can use relative layout; that is, one object is positioned in relation to another.

Creating a Group

To create a group, you first select the UI elements to compose a group. (Use a bounding box, or SELECT the first element and include the rest using ADJUST.) Choose Group from either the Arrange menu or from an element's pop-up menu to form the group. Use the Groups property window to give the group a name.

Determining a Group's Bounding Box

A group's bounding box is determined by the layout scheme you choose. For As Is, Vertical, and Horizontal, the bounding box is the smallest box that fits around all the group elements.

A matrix's bounding box is made up of cells. The height of a cell is the height of the tallest group element. The width of a cell is the width of the widest group element. A matrix's bounding box is m cells long and n cells high, where m is the number of elements in the matrix's longest row, and n is the number of elements in the matrix's longest column. Each element in the matrix is placed within a cell.

Ungrouping and Modifying Groups

To ungroup, first select the group by clicking SELECT inside the bounding box which surrounds the group elements. Then choose Ungroup from either the Arrange menu or from an element's pop-up menu.

To add elements to a group, you must first ungroup. The individual elements remain selected. Then extend the selection to the additional elements you wish present in the group. Finally, create a new group as described above.

You can delete elements from a group and still retain them as part of your interface. To do this, you must first ungroup. Then deselect any group element you wish removed from the group. Finally, create a new group as described above.

Editing the Properties of a Group

Click MENU on Groups... from Devguide's Properties menu to display the Groups window, shown in Figure 3-27. You can name a group, and modify the group's layout and alignment using the Groups window.

Figure 3-27

Groups List

A scrolling list appears at the top of the Groups window. This lists any groups created for the currently open user interface. It should be empty when you first start a new interface. Once you create groups, they appear in the list. You can select any single group by putting the pointer on its name and clicking SELECT. The Object Name field and layout information particular to that group appear in the Groups window.

Object Name

Object Name establishes the name that Devguide gives the group in the source code that the postprocessor generates. It is used within Devguide as a unique identifier for the group.

Layout

You can choose from four schemes to set the group's layout: As Is, Row, Column, and Matrix.

As Is As Is preserves the layout of the group as you have positioned elements on the workspace. The position of a group element is fixed with respect to the upper-left corner of the group's bounding box. If you later change fonts, internationalize your application, or if element sizes change for some reason, the group elements may overlap. To avoid this situation, use one of the relative layout schemes discussed below.

Row Row places all group elements in a horizontal line. The elements are evenly spaced across the line. You set the number of pixels between elements using the numeric text field to the right of the Row setting. The default is 10 pixels.

Column Column places all group elements in a vertical line. The elements are evenly spaced down the line. You set the number of pixels between elements using the numeric text field to the right of the Column setting. The default is 10 pixels.

Matrix Matrix places the group elements in a matrix format. You must specify a fixed number of rows or columns for the layout. The minimum number of rows (columns) allowed is 2. The maximum number of rows (columns) allowed is the number of elements in the group.

You set a fixed number of rows or columns by using the Rows/Columns exclusive setting and the numeric text field to the right of the matrix layout. You set the number of pixels between horizontally and vertically placed cells using the numeric text fields to the right of the Horizontal and Vertical settings.

To arrange the group elements into a matrix, Devguide first orders the elements in the group. The matrix is filled using a row-fill-first technique if you specify a fixed number of rows, and a column-fill-first technique if you specify a fixed number of columns. In row-fill-first, the matrix rows are created one by one, starting with the first element in the group ordering. In column-fill-first, the matrix columns are created one by one, starting with the first element in the group ordering.

• Rows - For a fixed number of rows, the number of columns in the group is determined by the number of group elements divided by the number of rows. If this number is an integer, it is used for the number of columns. If not, another column is created. This new column contains as many elements as the remainder indicates.
• Columns - For a fixed number of columns, the number of rows in the group is determined by the number of group elements divided by the number of columns. If this number is an integer, it is used for the number of rows. If not, another row is created. This new row contains as many elements as the remainder indicates.

Horizontal

You can choose from three horizontal alignment schemes. The Horizontal setting is active only when you choose a horizontal or matrix layout for the group. If you choose a matrix layout, the horizontal alignment you choose will be applied row by row. You can adjust the number of pixels between elements using the numeric text field to the right of the setting.

Aligns the UI elements with respect to the top of the highest element in the row.

Aligns the UI elements so that their centers fall on a common (invisible) horizontal line, with no shifting to the left or right.

Aligns with respect to the bottom of the lowest element in the row.

Vertical

You can choose from four vertical alignment schemes. The Vertical setting is active only when you choose a vertical or matrix layout for the group. If you choose a matrix layout, the vertical alignment you choose will be applied column by column. You can adjust the number of pixels between elements using the numeric text field to the right of the setting.

Aligns with respect to the left side of the leftmost element in the column.

Aligns with respect to the label of the leftmost element in the column.

Aligns the UI elements so that their centers fall on a common (invisible) vertical line, with no shifting up or down.

Aligns with respect to the right side of the rightmost element in the column.

Anchors

Devguide defines compass points for the bounding box of any UI element or group. The compass points are: Northwest (NW), North (N), Northeast (NE), West (W), Center (C), East (E), Southwest (SW), South (S), Southeast (SE). You can anchor any compass point on a group's bounding box to any other group or UI element in your interface using anchors. This allows you to define relative layouts between the group and any object in your interface.

• Anchor Group's - An abbreviated menu button is used to choose a compass point on a group. Choose a point on the group that you want to anchor to a point on another object in your interface.

• To - An abbreviated menu button is attached to a setting stack containing compass points for an object's bounding box. Fill in the object's name on the line to the right of the menu button. Use the stack to choose a point on the object's bounding box that you want to use as an anchor for the group.
• Offset - Once you have chosen an object and anchor points for the group and the object, you must choose a relative offset between compass points. You set a Horizontal and Vertical component to the offset using the numeric text fields provided.

As an example, if you want to anchor the North (top) of one group, group1, to the bottom of another group, group2, you would choose:

From: North point

To: South of group2

Offset: Horizontal: 0

Vertical: 10

This will place group1's top edge 10 pixels below the bottom edge of group2.

Devguide's coordinate system puts (0,0) at a window or pane's Northwest compass point. Vertical displacement increases downward; horizontal displacement increases to the right. You can assign a negative number to either Horizontal or Vertical (or both). A negative Horizontal displacement represents a shift to the left relative to a fixed point. A negative Vertical displacement represents an upward shift.

Handling Events Using Connections

To make your interface handle events, you specify connections in Devguide. When one object (called the Source) receives an event, a connection triggers a second object (called the Target) to respond by performing a specified action. For example, you might want to specify that when SELECT is clicked (the event) on a button (the Source), a popup (the Target) appears (the Action).

Use the Connections Manager window (shown in Figure 3-28 on page 83) to define a connection. Your toolkit choice determines the Connections Manager window's configuration. Use Devguide's Properties window (discussed in "Customizing Devguide's Properties" on page 52) to choose a toolkit before you start assembling your interface. The default choice is XView.

The events and actions recognized by the toolkit you choose are described in the toolkit's programming guide. See "Who Should Use This Book" on page xvii for the programming guide titles.

You can find the list of acceptable connection configurations for a given object in the .config file for your toolkit. This file is in the $GUIDEHOME/lib subdirectory included with the Devguide software. See Appendix A, "Files Provided With Devguide" to read about Devguide's included files.

You can open the Connections Manager window in one of three different ways:

• Drag and Link - Use Meta-SELECT to make a connection between two objects. Once you press the Meta key, you can select a Source object and drag a connection line with attached plug to a Target object. (You must keep the tip of the plug inside the desired target's bounding box.) This procedure brings up the Connections Manager window. The source and target objects are selected in the Source and Target scrolling lists (described below). You can use drag and link for any objects except menus and list items.

---

Note - Use the key marked "Alt" if there is no Meta key (usually marked as a diamond) on your keyboard.

---

• Property windows - Each UI element property window has a Connections... button. The Connections Manager window appears when you click this button. The object that is selected in the property window is selected in the Source and Target scrolling lists in the Connections Manager window. Notify is chosen from the When menu, and CallFunction is chosen from the Action menu. Insert a function name to create a notify handler.
• Properties menu - Choose Connections... from Devguide's Properties menu to open the Connections Manager window. The first time you do this, all base windows in the currently loaded interfaces are listed in the Source and Target scrolling lists (described below). When you subsequently choose Connections... from the Properties menu, the Connections Manager window will appear as it did the last time it was pinned to the workspace.

---

Note - You can resize the Connections Manager window to see entire names of items in all scrolling lists.

---

Figure 3-28

Choosing the Source of a Connection

In the upper-left corner of the Connections Manager window you see an abbreviated menu button labeled Source, with a scrolling list underneath. The Source menu contains all UI element types, as well as menu items and setting items. When you choose a Source type, all objects of that type that are in currently open interfaces are listed in the scrolling list below the menu button.

The default choice for the menu is Base Windows. If you open the Connections Manager window using a property window or by using drag and link, you have already specified a source. The appropriate object type will be chosen from the menu, and the source you chose will be selected in the scrolling list. Otherwise, choose the menu item appropriate to the type of connection you wish to make. Then select the item in the scrolling list that you want as the source of the connection.

Choosing the Target of a Connection

In the upper-right corner of the Connections Manager window you see an abbreviated menu button labeled Target, with a scrolling list underneath. The contents of the Target menu depend on the source you choose. The Target menu contains the list of acceptable targets for a given source object. At most it will contain all UI element types, as well as menu items and setting items. This is the case, for example, if you choose a button as the source of a connection. When you choose a menu item, all objects of that type that are in currently open interfaces are listed in the scrolling list below the menu button.

The default choice for the menu is Base Windows. If you open the Connections Manager window using drag and link, you have already specified a target. The appropriate object type will be chosen from the menu, and the target you chose will be selected in the scrolling list. Otherwise, choose the menu item appropriate to the type of connection you wish to make. Then select the item in the scrolling list that you want as the target of the connection.

If you open the Connections Manager window using the Connections... button from a property window, the UI element you selected in the window will appear selected as both source and target for a new connection. The target should be changed if you want to make a direct connection to a different UI element.

Choosing the Event for a Connection

Below the Source scrolling list you find an abbreviated menu button labeled When. The items in the When menu vary depending on the source type you choose for a connection (for example, Buttons). The When menu choices comprise the list of all events that can be recognized by the source object.

Choose the menu item appropriate to the type of connection you wish to make.

Choosing the Action for a Connection

Below the Target scrolling list you find an abbreviated menu button labeled Action. The items in the Action menu vary depending on the target type you choose for a connection (for example, Buttons). The Action menu choices comprise the list of all actions that can be initiated by the target object.

Choose the menu item appropriate to the type of connection you wish to make. Some action types require an argument. If so, the Arg text field is enabled. The text field's label changes to describe the kind of argument required. For example, CallFunction requires a function name, so the label changes to Function.

Defining Callbacks

All action types displayed as Action menu choices are predefined by your toolkit, except CallFunction and ExecuteCode. For CallFunction, specify the callback name that initiates the connection's action. If you choose ExecuteCode, Devguide displays a pop-up window labeled Define Callback. You can enter the code you wish to include as the action response in the Define Callback pop-up window.

Viewing Lists of Connections

The items in the View Menu determine the types of connections that are displayed in the Connections scrolling list.

The default choice for the View Menu is Source Obj. Those connections having the item selected in the Source scrolling list as the source of the connection are displayed.

All connections are displayed if you choose All from the View menu. When you choose a Menu item other than Source Obj or All, all connections with a source of that type are displayed in the scrolling list.

Connections Scrolling List

Below the View Menu you find a scrolling list labeled Connections. The Connections scrolling list displays a connection description in the following format:

sourcename (eventname) --> targetname (actionname)

where sourcename is the full name of the source object, eventname is the name of the event you choose, targetname is the full name of the target object, and actionname is the name of the action you choose. An object's full name includes the interface name and the object name separated by two colons.

Establishing a Connection

To establish a connection, you must select a source object from the Source scrolling list, a target object from the Target scrolling list, an event from the When menu, and an action from the Action menu. Once you have done that, you click Connect. The newly made connection appears in the Connections scrolling list.

Modifying a Connection

Select the connection you wish to change in the Connections scrolling list. Alter the connection, by changing its source, target, event, and/or action. Then click Change. The connection is now modified in the Connections scrolling list.

Deleting a Connection

You can eliminate an established connection by selecting it in the Connections scrolling list and clicking Disconnect.

Tying a Pop-Up Window to a Button

Many interfaces include a pop-up window tied to a button. Use Devguide to create both the pop-up window and the button to which it's tied. Choose the button as the Source of the connection and the pop-up as the Target. Then choose Notify from the When menu and Show from the Action menu. Click the Connect button to establish the connection.

Attaching a Notify Handler to an Object

To attach an XView Notify Handler to an object, establish a connection with that object as both the Source and Target. Choose Notify from the When menu and CallFunction from the Action menu. Insert the Notify Handler's name on the Arg line.

Connecting Objects in Different Interface Files

You can establish a connection between any object in any interface file, within the constraints defined by your toolkit. You must create a project if you connect an object in one interface file to an object in a different interface file. The project file contains the information necessary to implement the connection. When you establish this kind of connection, save your project file. Read "Assembling Interfaces into a Project" below to learn how to make a project.

Attaching a Menu to a UI Element

You can attach a menu to a control area, canvas pane, button, or scrolling list using connections. Use Devguide to create both the menu and the UI element to which it's attached. Choose the UI element as the Source of the connection and the menu as the Target. Then choose Menu from the When menu, and Show from the Action menu. Click the Connect button to establish the connection. You can also attach a menu to an element by using the Menu button on the UI element's property window.

Assembling Interfaces into a Project

Devguide allows you to group multiple .G (GIL) files for your application into a project. The term interface applies to the portion of your application created by a single .G file (and to your entire application). As you create and save interfaces using Devguide, a project serves as a convenient organizational tool. You can create a more modular application using projects.

The easiest way to construct a project is if you decide in advance how to organize your .G files. The first interface can be built by dragging elements onto the workspace, and then saving your work into a .G file. Each subsequent interface must be initiated by choosing New Interface... from Devguide's File menu. Once you do that, you can drag elements onto the workspace. Notice that the lower right corner of Devguide's base window tells you the name of

the currently edited interface. All elements you drag onto the workspace go into that interface. Once you finish with an interface, save it and repeat the process until your application is complete. Choose New Interface... from Devguide's File menu, build an interface, and save it to a .G file.

Devguide manages a project by creating a .P file. This file contains a list of all the .G files of the interfaces that comprise the project. It also contains any connections that you make between interfaces (the connection's source and target are in different interfaces).

This section discusses the operations you perform to create, modify, load, and save interfaces and projects.

Creating and Modifying Projects

If you use Devguide to create an interface with more than one window, it is generally a good idea to create each window as a separate interface and save the window in its own GIL file. You'll find that separating a large interface into one window per GIL file keeps the file sizes manageable during the compile. You can then create a project containing all the GIL (.G) files necessary for your interface. You can either compile them separately, or all at once. Devguide produces the correct makefile for your project.

To help keep your files straight during interface editing and compiling, you should create a single directory to store all the source code files for a single program: the GIL files for the interface, the toolkit-generated source code files for the interface, your own custom source code files for the software underlying the interface, and the Makefile that ties the files together during the compilation.

Using the Project Organizer

To make a project from your .G files, choose Project... from Devguide's File menu, or choose Load... and provide the name of a currently existing project. (See "Working with Files" on page 31 for further details on the File menu.). The Project Organizer window appears, containing an icon for each interface that is currently loaded. You must choose New from the Project Organizer's Project menu to create a new project. (Recall that only one project at a time can be open.) You can save this new project by choosing Save or Save As from the

Project menu. You can add existing .G files to the project by choosing Add from the Project Organizer's Interface menu. You can delete .G files appearing in the window by choosing Remove from the Interface menu.

The Project Organizer Window presents a visual representation of a project's contents. If you have loaded a project, the Project Organizer window contains an icon for each .G file contained in the project. Any other currently loaded interface is also considered part of an open project. The upper-right corner of the file appearing in an icon is folded over if the corresponding .G file is loaded. Figure 3-29 shows a project with two interfaces.

Figure 3-29

The name of the currently loaded project is displayed in the Project Organizer's header. The header displays "None" if you haven't yet loaded a project. It displays "Untitled" if you have chosen New from the Project menu. The window's footer displays either the current directory or the directory of the project which is currently open.

The Project Organizer window contains a Project menu button and an Interface menu button. The items in these menus are described below.

Working with Projects

Click MENU on Project to display the Project menu shown in Figure 3-30.

Figure 3-30

The Project menu contains items that allow you to create a new project, or load, save, or unload an existing project.

Load... Load... loads an existing project. It is disabled if a project is currently open. When you choose Load..., the Load file chooser appears. Double-click SELECT on a project file name, or enter the full path name of a project file and click Load.

New New creates a new project. It is disabled if a project is currently open. When you choose New, the Project Organizer's header changes from "None" to "Untitled." An icon for every .G file you have already loaded appears in the Project Organizer window. These files are all considered as part of your new project.

Save Save saves the current project file, as well as all .G files contained in the project. It is disabled if you have not yet created or loaded a project.

Save As... Save As... saves a new project or renames an existing project. It is disabled if you have not yet created or loaded a project. When you choose Save As..., the Save Project As file chooser appears. Enter the project's new name (including proper directory if necessary). When you save a project, its name appears in the Project Organizer's window header.

Unload Unload unloads the project whose name appears in the window header. It is disabled if you have not yet created or loaded a project.

Saving Projects Devguide generates two files when you save a project named projname:

• projname.P - contains a list of all .G files and all connections between interfaces in your project.
• projname.make - contains a list of all the .G files that constitute your project. It is written in the Makefile format and is included in the Makefile generated when you run a toolkit code generator on your project file.

Devguide generates new .P and .make files every time you save your project.

Working with Interfaces

Click MENU on Interface to display the Interface menu, shown in Figure 3-31.

Figure 3-31

The Interface menu contains items that allow you to add and remove .G files from the current project, and to perform operations pertaining to a .G file whose icon is selected in the Project Organizer window. You can select an icon by putting the pointer over it and clicking SELECT.

Show Show loads the .G file whose icon is selected in the Project Organizer window. It is disabled if you have not selected an icon. You can also load a .G file by double-clicking on the file's icon.

Hide Hide unloads the .G file whose icon is selected in the Project Organizer window. It is disabled if you have not selected an icon or if the selected icon's .G file is not loaded.

Browse... Browse opens the Interface Browser for the interface whose icon is selected in the Project Organizer window. It is disabled if you have not selected an icon.

Add... Add allows you to add .G files to the current project. It is never disabled. When you choose Add..., the Add Interface file chooser appears. The file chooser window contains a list of all .G files and subdirectories in your current directory. Double-clicking on a directory descends into the directory and lists

all its .G files and subdirectories. You can add a .G file to your project by double-clicking on the filename, or by entering its full path name on the line provided and clicking Add. If you add a .G file to your project, the Project Organizer window's header informs you that the project was modified.

---

Note - Add... does not load a .G file; it just adds the file to your project.

---

Remove Remove removes a .G file whose icon is selected in the Project Organizer window from the current project. It also unloads the file if it is loaded. The file's icon is removed from the window. If you remove a .G file from your project, the Project Organizer window's header informs you that the project was modified.

Project Organizer Window Pop-up Menu

The Project Organizer window has a pop-up menu. It has the same items contained in the Interface menu. The pop-up menu is included for your convenience. It is sometimes quicker and easier to perform operations on .G files using the pop-up menu than to use the Interface menu.

Dropping a File into the Project Organizer Window

You can load a GIL file into Devguide by dropping its file icon into the Project Organizer window. The corresponding interface appears on the workspace. If you have loaded a project, the new GIL file is added to the project.

Creating and Modifying Interfaces

If you are unsure about the structure of your application, you can build several windows and/or menus, and divide them into separate files later on. This is easy to do using Interface Browsers (one is shown in Figure 3-32 on page 95). If your entire application is in one interface, first open the Interface Browser for that interface. Then choose New Interface... from Devguide's File menu. Now you can drag whatever windows or menus you want from the application's Interface Browser into the Browser for your new interface. Continue to divide off pieces of your interface in this manner, saving as you go along.

If you decide that one interface is too large, you can move part of it to another interface in the same way. Open the Interface Browser for the interface you want to edit. Then choose New Interface... and drag objects into the empty Interface Browser window.

Using the Interface Browser

The Interface Browser window displays a tree or icon representation of the interface whose file name appears in the window's header.

Open an Interface Browser by choosing one of:

• New Interface... from Devguide's File menu (for a new interface).
• Browse... from the Project Organizer's Interface menu. You must first select an interface icon in the Project Organizer's window.

The default view of the tree representation puts the root (a base window, pop-up window, or menu) at the window's left side, and the tree expands horizontally to the right. Each node in the tree is displayed as a UI element glyph, with the name of the element appearing below the glyph. A tree appears for each base window, pop-up window, and menu that is a part of the interface being represented.

Figure 3-32

The Interface Browser window contains an Interface menu button, a View menu button, and an Edit menu button. The items in these menus are described below. The Tree/Icon exclusive setting allows you to view an interface as a tree structure as a whole (Tree), or as separate icons in one level of the tree at a time (Icon).

Saving and Unloading Interface Files

Click MENU on Interface to display the Interface menu, shown in Figure 3-33.

Figure 3-33

The Interface menu contains items that allow you to save, rename, or unload a .G file.

Save Save saves the current interface. If the interface hasn't been saved yet, choosing Save opens up the Save As file chooser.

Save As... Save As... allows you to name your interface for the first time, or rename it if it has already been saved. When you choose Save As..., the Save As file chooser appears.

Unload Unload unloads the current interface.

Viewing Portions of the Interface Hierarchy

Click MENU on View to display the View menu, shown in Figure 3-34.

Figure 3-34

First select an object in the Interface Browser window by clicking SELECT. When you do this, the object is also selected in the actual interface. The View menu items apply to the object that you select. Use the first two items to shift up and down an interface tree in either Tree or Icon mode.

Parent Parent shifts the view of the tree if necessary, so that the selected object's parent becomes visible. (The view remains fixed if the selected object's parent is already visible.) It is disabled if no object is selected, or if you select the root of a tree. In Icon mode, Parent displays the icons of all elements on the same level as the parent of the selected object.

Children Children shifts the view of the tree, so that the selected object and its children are visible. It is disabled if no object is selected, or if you select a leaf of a tree. In Icon mode, only the children of the selected object are visible.

Vertical Vertical displays all trees in the Interface Browser window vertically. The roots are at the top of the window and the trees expand downward. When you choose Vertical, the Vertical view menu item toggles to Horizontal (the default representation). Vertical is disabled in Icon mode.

Editing Using Interface Browsers

Click MENU on Edit to display the Edit menu, shown in Figure 3-35. This menu contains items that help you copy or remove elements from a user interface, and move them to other interfaces. When you make changes to an interface, the Interface Browser window header informs you that the interface was modified. Performing editing operations on icons in Interface Browsers causes the corresponding interfaces to be updated accordingly.

Note that each of these editing items is also available in UI element pop-up menus and Devguide's Edit menu button.

Figure 3-35

Undo Undo reverses the last editing action. Use it to retrieve deleted or cut elements, or to remove pasted elements. Note that Undo does not restore the contents of the elements clipboard that were removed by an editing action.

Cut Cut removes any selected UI elements from the workspace and places them on the element clipboard. Each time you use Cut, you replace the contents of the clipboard with the elements you cut.

Copy Copy copies any selected UI elements in the workspace and places the copies on the element clipboard. Each time you use Copy, you replace the contents of the clipboard with the elements you copied.

Paste Paste pastes any UI elements currently on the element clipboard into the currently open user interface. If you have a window on the clipboard, you must first deselect the window. Then choose Paste from the Edit menu of the Interface Browser into which you want to paste.

If you have a control area or a panel on the clipboard, you must first select a UI window icon before you can use Paste. When you use Paste, the control area or panel appears in the selected window, and the Interface Browser is updated accordingly.

If you have one or more control elements on the clipboard, you must first select a UI control area icon before you can use Paste. When you paste the controls, they appear in the selected control area, and the Interface Browser is updated accordingly.

If you have mixed elements on the clipboard--for example, a window with a control area and controls--Paste follows the rules for pasting the highest-level containing element. For example, you can paste a window with a control area and controls anywhere on the workspace, but you can only paste a control area with controls within a selected window.

Interface Browser Window Pop-up Menu

The Interface Browser window has a pop-up menu. It has the same items contained in the Edit menu. The pop-up menu is included for your convenience. It is sometimes quicker and easier to perform edits using the pop-up menu than to use the Edit menu.

Dragging Objects Between Interface Browser Windows

If you create more than one interface on the workspace, you can edit any of them by selecting the appropriate window or menu in the interface. You can add or remove any objects from an interface by dragging or deleting. You can cut, copy, and paste any object from one interface to another. You can also use the Interface Browser to cut, copy, and paste objects, as described in "Editing Using Interface Browsers" on page 97. You can drag and drop windows and menus from one Interface Browser to another. This facilitates moving top level objects between interfaces. When you edit an interface, its Interface Browser window is updated accordingly. If you decide you do not want an interface as part of your project, you can delete it from the project by choosing Remove from the Project Organizer's Interface menu.

Layering Panes

You can place multiple panes in the same area of the workspace. You can layer all four types of panes (text, term, canvas, and control area), using any combination. You can layer panes by placing a pane's glyph anywhere on top of an existing pane. This configuration is sometimes referred to as layered panes or a layer of panes.

If you want to add a new pane to a layer of panes, you must drag its glyph directly onto the top of the layer. A pane is not included in a layer of panes if you first drag its glyph onto a different portion of the workspace, and later place the pane on top of the layer.

Sizing Layered Panes

Any pane you place on top of a pane or an existing configuration of layered panes is sized to the existing pane(s). If you want the layered panes to be different sizes, you can resize them by changing the W and H values of the Rectangle property in the appropriate property window(s). If you resize one pane using its resize handles, all layered panes assume that same size.

You can have layered panes in which multiple adjacent panes comprise the layers. For example, one layer can have two adjacent panes that fill a window, another layer can be one pane the size of the window. One way to do this is to first create the layer consisting of the two adjacent panes. Next, drop a pane glyph onto one of the existing panes, and resize it to fill the window by setting W and H values in the pane's property window.

Moving Layered Panes

If you drag the top pane in a layer of panes to change its location on the workspace, the entire layer of panes is dragged with the pane. You can move an individual pane by changing the X and Y values of the Rectangle property in its property window. Once you create a layer of panes, move it as a whole.

Scrolling through Layered Panes

You can scroll through layered panes by selecting the top pane and choosing Next Layer from Devguide's View Menu. Next Layer is the default item on the View menu. It also appears in a UI element's pop-up menu.

Devguide's Element field displays the name of the top pane when you move the pointer on top of the pane. In addition, the Element field provides a parenthetical message identifying the layered pane's name, the pane's relative position, and the total number of layered panes.

An example of this notation is:

Element: controls1 (layered_pane1, layer2 of 3)

In this case the pointer is over the control area named controls1, which is the second in three layered panes. The layer of panes is named layered_pane1.

Using the Code Generator Tool

Use Devguide's code generator tool to generate and compile code, and to run applications for these code generators, without having to type commands at the command line. The code generator tool's main window is resizeable.The inner pane is a command tool.

Figure 3-36

Click SELECT on the File... button to display a file chooser pop-up window. Use this to select a GIL or project file. Click SELECT on the Properties... button to display a pop-up window to set make and run-time arguments, and code generator properties. Click SELECT on the Generate Code button to generate

code from your GIL or project file. Click SELECT on the Make button to compile source code and link object code. Click SELECT on the Run button to run the executable program.

Using the File... Button

When you click SELECT on the File... button, a file chooser pop-up window appears. When you select a file, the main window's Directory and File fields are filled in. The file name also appears after the code generator name in the Code Generator field.

See "File Chooser" on page 32 for more information about the file chooser.

Using the Properties... Button

When you click SELECT on the Properties... button, the Code Generator Properties pop-up window appears. The GXV Properties pop-up window is shown in Figure 3-37 on page 104.

---

Note - The code generator window can remain open regardless of whether the Devguide window is open.

---

Use the Code Generator abbreviated menu button to select the GXV, GXV++, or GOLIT code generator.

---

Note - If an application has already used a particular code generator to generate code from a GIL file, use the same code generator for that application. For example, if you used GXV, continue to use GXV. If you use a different code generator, you will obtain unusable hybrid results.

---

The options for your chosen code generator appear below the RunTime Arguments text field. The -scale large argument is one example of a run-time argument. The clear argument is one example of a make argument. See the appropriate code generator Programmer's Guide for further information on these options.

---

Note - The makefile contains all the property options that you used the last time you generated code. If you load-in an application with a makefile, all of the code generator options contained in the makefile are loaded into the tool. When you press the Apply button on the property sheet, the makefile is updated.

---

Check Use Maketool if you want to use the SPARCworks^(TM) or ProWorks^(TM) Maketool. Type in make or runtime arguments in the appropriate text fields.

---

Note - The Maketool option works only if you have installed the SPARCworks or ProWorks software and updated your path accordingly.

---

Click SELECT on the Apply button to effect the changes. Click SELECT on the Reset button to clear the propery sheet. (You must select Apply for the clearing to take effect.

Figure 3-37

Printing Windows

If you want to capture a window and send its image to a printer, use Snapshot. See Solaris 2.4 Introduction for more information on Snapshot.