Constant Manager

You can work with your constants by using the Constant Manager (select Constants from the Browser Managers menu). Refer to Constant Manager for more information.

Identifier Editor

Identifiers are not necessarily simple variables. You can define an identifier that is a call to a function or a method, with the appropriate return type. You can work with your identifiers by using the Identifier Manager (select Identifiers from the Browser Managers menu). See Identifier Manager for more information.

Example

The following example demonstrates a simple use of BxSetValuesCB:

1. Create a BulletinBoard with two PushButton children.

2. Set the activateCallback resource of pushButton to BxSetValuesCB("bulletinBoard.background=red").

3. Set the activateCallback resource of pushButton1 to BxSetValuesCB("bulletinBoard.background=white").

4. Enter Play Mode(Browser:View).

5. To test the interface, click the PushButtons.

The BulletinBoard toggles between red and white as each call to BxSetValuesCB resets the background resource.

Note: Use unique instance names for objects that are referenced by callbacks. Predefined callbacks rely on the instance name remaining the same each time the widget is created, and the default instance names assigned by Builder Xcessory may change when you edit the instance hierarchy.

Accessing Objects at Run Time

To manipulate an object at run time, you must have access to it. How you choose to access the object depends on the language in which you plan to generate code.

In C++, ViewKit, and Java, objects are declared by default as protected class members and are easy to access from within a class. To access an object from outside the class, you must define a public method, though you most likely want your method to perform any manipulation, rather than passing a widget ID out. Follow good object oriented programming practices.

In C, you can use one of the following methods:

· Set the storage location

· Set createCallback

· Use the class record

· Call Xt functions

If you are generating UIL, you can specify the widget ID with the widget name using MrmFetchWidget.

Declaring storage location in code

If you have declared the storage location in the code, follow these steps:

1. Select Storage Location from the Resource Editor Component menu to display the Storage Location dialog:

MrmFetchWidget

If you are generating UIL, you can obtain the widget ID by calling MrmFetchWidget on the widget name.

Managing and Unmanaging Objects

Frequently, some objects are displayed only for short periods during the application's execution. For example, when a dialog is displayed for a particular user action and then immediately dismissed. In these cases you might want to start your application with these objects initially unmanaged, so that the application manages them only as necessary.

Setting dialogs as initially unmanaged

To set dialogs as initially unmanaged, follow these steps:

1. Select Code Generation Preferences from the Browser Options menu to display the Code Generation Preferences dialog (Application Panel on the C Generation Preferences Dialog ).

2. Click on the Application tab ( Application Panel on the C Generation Preferences Dialog ).

3. Set (Parented) Dialog Shells Initially Unmanaged.

Parented dialogs are now unmanaged by default.

---

Note: This affects code generation only. The dialogs remain managed during your Build sessions.

---

---

Note: To unmanage objects on a case-by-case basis, select Hide on any object in the Resource Editor (Resource Editor:Component).

---

Application Panel on the C Generation Preferences Dialog

Callback Procedures and Event Methods

To connect your interface to the rest of your application, you must add callback procedures (for Motif) or event methods (for Java). These callbacks and event methods respond to various actions, or events, on the interface, such as a key press or window exposure.

Adding callbacks and methods

You add a callback procedure or an event method by assigning its name to one of an object's callback or event resources. You can then edit the resource using the Resource Editor as you edit any other resource.

To add a callback as the activateCallback of a push button, follow these steps:

1. Update the Resource Editor for the push button.

2. Click the (...) button to the right of the activateCallback text field to display the Callback Editor:

Callback Editor

3. Enter the Procedure Name, select a Parameter Type, and enter the Parameter Name in the appropriate fields, hitting enter to apply the value to the callbacks list. After adding whatever other callbacks you wish to associated with the activateCallback, press Apply.

4. To add code to the callback, select it in the Callback List and press Edit. Builder Xcessory generates code and brings up your favorite editor with the correct file loaded and positioned at your new callback.

---

Note: You can edit only procedures that have been applied.

---

Adding an event method

To add an event method for the ActionEvent of a Java push button, follow these steps:

1. Update the Resource Editor for the push button.

2. Bring up the extended editor for the ActionEvent resource ( ActionEvent Editor ).

ActionEvent Editor

3. Enter the procedure name in the ActionEvent Editor's text field, and apply the value to the resource (Apply).

4. To edit the code for the method, be sure that the method name has been applied, then press the Edit button to the right of the text field. Builder Xcessory generates Java code and brings up your favorite editor with the correct file loaded and positioned at your new method.

Predefined Callbacks

Click on the arrow button to the right of the Procedure Name field to display the list of predefined callbacks. Predefined callbacks are provided for common operations such as setting values, managing and unmanaging windows, etc. These predefined callbacks also behave correctly when Builder Xcessory is in Play Mode, allowing you to test the look of the interface without building the application. For more detailed information on these callbacks, refer to the Builder Xcessory Reference Manual .

Using Classes predefined callbacks

To set a callback resource to a predefined callback, follow these steps:

1. Display the Callback Editor for the appropriate resource.

2. Click on the arrow button to display the list of predefined callbacks.

3. Click on a predefined callback on the list.

4. Apply the contents of the Callback Editor to the resource.

Predefined callbacks are especially useful for rapidly prototyping your application. They allow you to preview many common actions that are performed in your interface, during the development process when the efficient execution of the application is not as important.

Using Callbacks in C++ Classes

For a general introduction to classes, refer to Classes . For more detailed information about using exposed resources and methods, refer to Exposing Resources and Exposing Callbacks and Event Methods .

Adding callbacks to classes

Whenever you add a callback to an object within a class, Builder Xcessory generates two methods:

· A private static method assigned to the widget using XtAddCallback() . This is static because Xt is a C library, and thus cannot use a non-static method. This method is automatically named your_callback_name Callback(Widget, XtPointer, XtPointer) .

· A protected virtual method containing the actual code for your callback. This method is given the name you specified for the callback, your_callback_name (Widget, XtPointer, XtPointer) .

The static method is passed a structure pointer that contains a pointer to the instance of the class that initiated the callback and a pointer to any client data that you specified for the callback. The static method then calls the actual class method (the real callback) and passes all of the standard Xt callback parameters ( w , client_data , call_data ).

Exposing callbacks

When you expose a callback in a class, Builder Xcessory generates the two methods described previously, and a public method that adds additional callback functions to the widget. This method's name incorporates the widget's instance name and callback resource name. It uses XtAddCallback() to optionally append to, or replace, the existing callback list. Appending or replacing is controlled with the Remove Overridden Exposed Callbacks toggle on the Code Generation tab (Browser:Options:Language Settings).

Builder Xcessory also allows you to set callbacks defined by the various ViewKit components (ViewKit Callbacks). In the Resource Editor, these callbacks appear identical to Xt callbacks. However, during code generation, these ViewKit callbacks are generated only as methods of the ViewKit component and are added using VkAddCallbackMethod().

Using Event Methods in Java Classes

For a general introduction to classes, refer to Classes . For a detailed discussion of using exposed resources and methods, refer to Exposing Resources and Exposing Callbacks and Event Methods .

Adding event methods to classes

When you add an event method to an object within a class, Builder Xcessory adds your routine as a public method.

Exposing event methods

When you expose an event method in a class, you can then specify an additional method (on a per instance basis) to be called in response to the event.

---

Note: Exposing methods in Java is meaningful only if the original event method, specified in the class definition, allows the event to propagate up the instance chain to the parent (original event method returns "false"). Refer to you Java documentation for more information on AWT event processing.

Using Timers, Event Handlers, and Translations

You can register and use timer procedures, work procedures, event handlers, and translations using special editors provided by Builder Xcessory. These elements are managed similarly within Builder Xcessory.

Timer Procedures

A timer procedure is a procedure invoked when a specified interval of time elapses. When a timeout event occurs, the timer callback procedure is invoked, and the callback is removed. Consequently, timeout events are invoked only once.

In ViewKit code generation, specifying a timer procedure causes Builder Xcessory to create an instance of the VkPeriodic class. This class calls the timer procedure repeatedly until your application stops it. For more information on this class, refer to the VkPeriodic manpage.

Using timer procedures

Use a timer procedure for an event that you want to happen after a specific time interval. When the timer procedure is registered, Xt first waits for at least the interval you specified, and then calls the timer procedure. Builder Xcessory generates code to register the timeout in the main program.

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes 4 and 5 for a full description of timer procedures and the XtAppAddTimeOut call.

Adding timer procedures

To add a timer procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Click on the (...) button next to the Timer Procedures input field in the Application Manager to display the Application Timer Procedures Editor:

Application Timer Procedures Editor

3. Click on New.

4. Enter the name of the timer procedure to be called after the interval expires, along with the interval, the parameter type, and the parameter (data) in their associated fields.

Interval specifies the number of milliseconds that should elapse before this function is invoked. After this period elapses, the procedure's callback is invoked by the Xt Intrinsics. The Parameter field specifies client data to pass to the procedure XtAppAddTimeOut.

5. Click on Apply to register the timer procedure.

All current timer procedures are displayed in the window above these fields.

Removing timer procedures

To remove a timer procedure, follow these steps:

1. Select the procedure from the list displayed in the Application Timer Procedures Editor

2. Click Delete.

The procedure is removed from the list and from your application.

Work Procedures

A work procedure is a callback that provides a limited form of background processing. The Xt Intrinsics invoke a work procedure whenever there are no events pending. Thus whenever the application is not drawing to the display or responding to user actions, the work procedure is called.

---

Note: Although you can define multiple work procedures, only the most recently registered is called.

---

Using work procedures

Use a work procedure to specify a function to call when no other events are pending. Once a work procedure is called, the program cannot process any events until the procedure returns. Therefore, any work procedure should be a function that executes quickly.

Example

To perform a long calculation with work procedures, set the calculation as an iterative process so that a small portion of the calculation can be done each time the work procedure is called. This approach avoids freezing the interface.

When you specify work procedures and generate code for ViewKit, Builder Xcessory creates a subclass of the VkBackground component for each work procedure you have specified. Each work procedure class is instantiated and started in the main() routine, before the call to VkApp::run().

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes Four and Five for a full description of work procedures and the XtAppAddWorkProc call.

Adding work procedures

To add a work procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Click on the (...) button next to the Work Procedures input field in the Application Manager to display the Application Work Procedures Editor:

:

Application Work Procedures Editor

3. Click on New.

4. Enter the name of the WorkProcedure, the Parameter Type, and the Parameter Value in their associated fields.

5. Click on Apply to register the work procedure.

All current work procedures are displayed in the scrolled window above these fields.

Registering a work procedure causes a call to XtAppAddWorkProc to be inserted in the main program.

For ViewKit code generation, a VkBackground subclass is instantiated.

Removing work procedures

To remove a work procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Select the work procedure from the list displayed in the Application Work Procedures Editor.

3. Click on Delete.

The work procedure is removed from the list and from your application.

Event Handlers

An event handler specifies functions called when an X/Motif event is received by the window associated with the object for which the event handler is set.

Example

Sometimes an object does not provide a callback for an X event that you want to respond to in your application. For example, the XmDrawingArea widget does not have a callback for when the user moves the mouse with a mouse button held down. You must add an event handler to the eventHandler resource on the XmDrawingArea object.

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes Four and Five for a full description of event handlers and the XtAddEventHandler call.

Adding event handlers

To add an event handler, follow these steps:

1. Click on the (...) button next to the eventHandler resource on the Resource Editor to display the Event Handler Editor:

Event Handler Editor

2. Click on New.

3. Enter the Handler Name, the Event Mask, the value of Non-Maskable, and the Parameter Type and Value in their associated fields. The Event Mask specifies the events that trigger the event handler. Non-Maskable is True if the handler is to be triggered on non-maskable events (that is, events that cannot be specified by the Event Mask, for example, GraphicsExpose, SelectionNotify, or ClientMessage), and is otherwise False. The Parameter specifies client data to pass to the procedure XtAppAddTimeOut.

4. Click on Apply to register the event handler.

Builder Xcessory inserts a call to XtAddEventHandler in the file in which the widget is created. All current event handlers are displayed in the scrolled window above these fields.

Removing event handlers

To remove an event handler, follow these steps:

1. Select the event handler from the list displayed in the Event Handler Editor.

2. Click Delete.

The event handler is removed from the list and from your application.

Translations

A translation links a sequence of one or more events to an action, the function called when these events are received. You can add translations that include actions already registered for the object, or you can add a translation based on additional actions that you must register in your code before creating any object that references them.

Using translations

Most objects provide a large number of actions that are triggered by key presses, mouse actions, and so forth. In most cases, you only add translations to an object to augment its behavior.

Example

Support for Motif drag and drop is added to objects with an action. You must modify a new object's translation table to add drag and drop support.

Adding translations

To add a translation to an object, use one of the following methods:

· Enter the translation in the translations resource text field on the Resource Editor.

· Click the (...) button to the right of the translations resource's text field to display the Translation Table Editor (Translation Table Editor), and enter the translation.

Translation Table Editor

When you apply the contents of the Translation Table Editor to an object's translations resource, Builder Xcessory replaces the object's Translation Table with the translations you have provided.

---

Note: Builder Xcessory displays a warning if you modify an object's Translation Table and reference an action that you plan to add. However, the action works correctly in your code, provided that the action is registered before you create the object whose translation table references it.

Startup Panel

While loading, Builder Xcessory displays the following Startup Panel:

ICS Builder Xcessory Startup Panel

Startup Panel

The Startup Panel appears each time you start a Builder Xcessory session. As Builder Xcessory initializes, status messages are displayed at the bottom of the window, and a random tip is displayed in the "Did You Know?" field. The "Next Tip" button is active only when Builder Xcessory finishes loading ("System Ready" is displayed at the bottom of the window).

Language Dialog

In your first Builder Xcessory session, the following Language Dialog window also appears in the foreground:

Exit button

The Exit button exits Builder Xcessory without saving a default language with your .bxrc file. The Language Dialog will appear the next time you start Builder Xcessory.

---

Note: The Language Dialog appears during your first Builder Xcessory session only. Subsequent Builder Xcessory sessions use the default language, as specified in your .bxrc file.

---

---

Note: When you select UIL as your default language, Builder Xcessory generates UIL to implement the interface and C code to implement the application.

Builder Xcessory Main Windows

Once you select a language at the beginning of your session, Builder Xcessory's three main windows are displayed:

Builder Xcessory Main Windows

Using Builder Xcessory windows

The way you use these windows is described in the following sections. Typically, you will use them in the following sequence:

1. Select an object from the Palette and drag it to the desktop.

2. Modify the object with the Resource Editor.

3. Use the Browser window to test the modified object in Play Mode and generate code in your chosen default language.

Browser

Overview

The Browser ( Builder Xcessory Browser ) is your primary control window while you are building your interface. With the Browser menus you open and save interface files, customize your views of Builder Xcessory and your interface, interact with other tools in your development environment, control your code generation, access special Builder Xcessory managers, and access on-line help.

Builder Xcessory Browser

The Browser displays the logical structure of your interface. This parent-child hierarchy of UI objects is displayed as a tree showing parents on the left and children on the right. You have the choice of viewing the Instance hierarchy of your interface, or you can view the Class hierarchy, the structure of all the high-level UI objects that you've created or imported for your interface.

A Simple UI and Corresponding Browser Display Area shows a simple UI and the corresponding Browser display area:

A Simple UI and Corresponding Browser Display Area

In addition to viewing your UI elements, you can manipulate these abstract representations directly with the mouse, using the Browser as a construction area.

Refer to Browser for more detailed information about the Browser.

Browser Menus

File menu

Allows you to control your files by performing the following operations:

· Create new user interface files

· Open and save user interface files

· Read one user interface file into another

· Load and save high-level UI classes

· Generate source code for your interface

· Print your interface object hierarchy

From the File menu, you can also exit Builder Xcessory.

Edit menu

Allows you to manipulate the objects in your interface by performing the following operations:

· Cut, copy, paste, or delete an object

· Copy an object to the Palette

· Revert UI to previous saved state

· Raise and lower objects, both in terms of visibility on the screen, and in terms of position in your instance hierarchy

· Control the size and position of the UI objects, in particular alignment

· Create high-level classes from groups of your UI objects

· Designate a member of a class as the receptor for the class

View menu

Allows you to modify the appearance of the Browser by performing the following operations:

· Control the view of some complex UI objects (such as compound Motif widgets and menu structures)

· Select the parent of the currently selected widget

· Force any widget created later to become a child of the currently selected widget

· Force each selected widget to align itself with the underlying placement grid if it is moved or resized

· View or hide the message area, the search area, the Toolbar, and your high-level Class hierarchy

Project menu

Allows you to interact with the other tools in your development environment by performing the following operations:

· Put your interface in Play Mode to test its dynamic behavior

· Debug your interface code

· Build the application for which you are creating an interface

· Check a file in or out of your source control system

· Edit a file

Options menu

Allows you to customize the Builder Xcessory environment and behavior by performing the following operations:

· Choose a default programming language

· Set code generation behavior

· Control the Builder Xcessory user interface

· Control interaction with other development tools

· Customize GIL import options

Managers menu

Provides access to the Builder Xcessory managers, which help you organize and effectively use different elements of your project. You can access the following managers:

Manager	Description
Application	Create timer or work procedures for your application.
Styles	View and edit the hierarchy of styles in your project and apply styles to objects.
Constants	Define or modify constants.
Procedures	Create, edit, and delete elements of callback and creation routines.
Identifiers	Define, view, and manipulate identifiers available in your project.
Types	Define, view, and manipulate parameter types available in your project.
UIL files	View and manipulate UIL output files for your project.

Windows menu

Helps you manage your entire work area by performing the following operations:

· Iconify or deiconify all windows (Builder Xcessory and your UI)

· Raise any of the Builder Xcessory windows to the top of your desktop

Help menu

Provides access to the online, hypertext help system, as well as version and copyright information.

MB3 Quick Access menu

Invoked by pressing MB3 while the mouse pointer is over a UI object, or its representation in the Browser window. This menu contains actions appropriate to the item under the mouse. You can apply all the items from the Browser Edit menu and also perform the following actions:

· Add an object from the Palette

· Select the parent of the current widget

Toolbar

The Toolbar, optionally shown with the Browser View menu, allows you to place frequently used menu items within easy reach.

Adding an item to the Toolbar

To place an item on the Toolbar, hold the Shift key down while selecting the desired menu item.

Removing an item from the Toolbar

To remove an item from the Toolbar, hold the Shift key down while selecting the desired Toolbar item.

Message Area

The Message Area, optionally shown with the Browser View menu, displays status and error messages from Builder Xcessory. The types of messages you can expect include confirmation of file generation and reports of attempted illegal user operations.

Interface Hierarchy

Display area and Instances/ Classes view combination box

The display area in the Builder Xcessory Browser allows you to view your interface hierarchy and to manipulate that hierarchy. Depending on the view selected with the Instances/Classes view combination box on the left of the Browser, you can view and manipulate the instance or class hierarchy of your interface.

Panner

Navigate through the display area with the Panner, located in the upper left- hand corner of the Browser. The Panner functions as a two-dimensional scrollbar.

Top-Level Object List

The Top-Level Object List at the left of the Browser permits you to view or hide both an interface window and its Browser representation by clicking on the object name with MB1 to select or deselect it.

Collapsing/ expanding sections of display area

To collapse or expand a section of your instance or class tree in the display area, with the corresponding interface window visible and available for work, click on the folder icon at the desired node of the tree.

Instances view

When the Browser is in Instances view (default), the display area shows the instance hierarchy of your interface, that is, the parent-child relationships of all the UI objects in your interface. You can work directly with the UI objects in their respective windows, or you can work with their representations in the display area by performing the following operations:

· Drag objects from the Palette and drop them directly onto the display representations

· Drag a display representation from one position to another, reparenting that object

· Drag objects between their respective windows and the display area

· Edit objects using the Browser Edit menu or the MB3 Quick Access menu

Classes view

When the Browser is in Classes view, the display area shows the contents of each of the high-level objects, or classes, that you have built or imported and are using. Only in this view can you edit a class after it has been initially built. In Classes view you have the same drag and drop capabilities as you have in Instance view.

For more information on classes, see Classes and Methods .

Selecting and Deselecting Objects

When working with UI objects, Builder Xcessory maintains the notion of selected objects. In your interface window, the border of the selected object is darkened and divided into corners and edges, making resize operations easier. In the display area, the pushbutton representation of the object appears to be depressed.

Selecting objects

Use one of the following methods to select an object, or objects:

· Click directly on the object or its display area representation.

· In the Browser Search/Select area, select Instance or Class from the option menu, then enter an instance or class name. Press the return key when you finish typing. You can type in a partial instance or class name to match multiple objects, or just to save time. All objects matching your entry are selected. To select one object, scroll through the possible matches by using the arrow buttons until the appropriate object is selected.

---

Hint: You can type any portion of the instance or class name into the Search/Select area. (The search is not case sensitive.) For example, typing "iew" would match all objects with "View" in their name. This is very helpful when you are not sure of a precise object name, or when you are selecting multiple objects with similar names.

---

· Hold down Ctrl and click on each interface object or representation. With Ctrl held down, each object you click on is added to the set of selected objects. This works in your interface windows and in the display area.

· Hold down Shift and MB1 and drag the cursor to draw a square around the objects (or their representations). Release MB1 and Shift. All objects entirely within the square are selected. This technique is referred to as " rubber-banding". This works in your interface windows and in the display area.

· Hold down Shift and click on a display area representation. This selects the object and all of its descendants in the instance hierarchy. This works only in the display area.

---

Note: Choose Select Parent from the Browser View menu or the MB3 Quick Access menu to select the parent of the currently selected object. This capability can be useful when the parent is not visible.

---

Deselecting multiple objects

To deselect multiple objects, use one of the following methods:

· Click anywhere on any unselected object or representation. All other objects are deselected.

· Hold down Shift and click on a selected display area representation. The object and all objects descending from it are deselected. This works only in the display area.

Deselecting one object within a group

To deselect one object within a group of selected objects, hold down Ctrl and click on that object. The other selected objects remain selected.

Palette

Palette object icons

The Palette displays labeled, iconic representations of the UI objects with which you build your interface. Depending upon the currently selected language and the platform on which you are running Builder Xcessory, the Palette icons correspond to the following objects:

· Motif Xm widgets

· ViewKit ObjectPak Vk objects

· EnhancementPak Xi widgets

· Java AWT objects

· DEC Dxm widgets (available only on DEC UNIX platforms)

· SGI Sgm widgets (available only on SGI platforms)

· Common Desktop Environment (CDE) Dt widgets (available only on platforms with CDE and BX CDE support)

The Palette also includes collections of objects and classes that you build, as well as any third-party or platform-specific widgets or classes you add to Builder Xcessory.

For more information about the Palette, refer to Palette . For more detailed information about the Palette objects, refer to Palette Objects .

EPak widgets

To include EnhancementPak widgets on the Palette, use the Start with EPak Widgets toggle button on the User Preferences dialog of the Browser Options menu. For more detailed information, see Behavior toggle options .

---

Note: To compile an interface that uses EPak widgets, you must have the EnhancementPak library installed on your system. The EnhancementPak library is included with BX PRO.

---

ViewKit objects

The ViewKit ObjectPak objects are automatically included on the Palette when you select ViewKit as your default language. For more detailed information, see Choose A Language .

---

Note: TTo compile an interface that uses ViewKit objects, you must have ViewKit installed on your system. ViewKit is included with BX PRO.

---

Palette views

The Palette can be viewed in outline or tabbed form (Figures Builder Xcessory Palette (Outline View) and Builder Xcessory Palette (Tabbed View) ):

Builder Xcessory Palette (Outline View)

Builder Xcessory Palette (Tabbed View)

Palette Groups

On the Palette, UI objects are divided into groups. The groups and their contents vary depending upon the selected language. For a description of the standard Palette groups, see Palette Groups . For more detailed descriptions of each object on the Palette, refer toPalette Objects

Nesting groups

You can nest groups by creating a new group as part of another group. For example, create a "ViewKit' group and move all ViewKit-related groups into the "ViewKit" group. You can then hide all the ViewKit items by closing just the single group.

Hiding/
displaying groups

To hide a group, click on the folder icon to the left of the group name. Click again on the icon to restore the view of the group.

Creating a top-level group

To create a new top-level group, select New Group from the Palette Edit menu.

Creating subordinate groups

To create a new group subordinate to an existing group, select New Group from the Palette MB3 Quick Access menu.

Groups common to all Palettes

In addition to the platform- and language-dependent groups, the Palette displays the following groups:

· Project Classes

High-level UI objects you create or for a project when you open a project save file.

· Private Classes

High-level UI objects that are stored in the following directory:

${HOME}/.builderXcessory/classes directory

These objects appear each time you use Builder Xcessory.

· Public Classes

High-level objects that are stored in the following directory:

{BX}/XCESSORY /classes directory.

These objects appear on every Builder Xcessory user's Palette.

Palette Menus

Palette menu

Allows you to control the Palette's appearance by performing the following operations:

· Create a new Palette

· Show the Palette in full or reduced (tabbed) view

· Display the Palette icons with only pixmaps, only labels, or both

Catalog menu

Allows you to manipulate the Palette by performing the following operations:

· Create a new catalog

· Load an existing catalog

· Merge a catalog with the current catalog

· Save the current Palette catalog

· Save the Palette catalog to a different file

· Change the display name for the Palette

Edit menu

Allows you to rearrange the Palette by performing the following operations:

· Move objects from one group to another

· Change the order of the objects within a group

· Create a new group

MB3 Quick Access menu

Invoked by pressing MB3 while the mouse pointer is positioned over a Palette icon or a Palette group name. This menu provides many of the Edit menu functions. From the Quick Access menu you can perform the following operations:

· Move or delete the selected object(s)

· Create a new group

· Modify the properties of an object icon

Using the Palette

Builder Xcessory allows you to create, manipulate, and reuse different types of UI objects, including the following:

· Motif widgets and widget collections

· C++ Motif classes and subclasses

· ViewKit classes and subclasses

· Java AWT classes and subclasses

Creating Objects

Creating UI objects is the same for all object types. The following sections describe two methods for selecting an object from the Palette and placing the object in your interface.

Using MB1

1. With MB1, click on the desired object.

A rectangular outline of the object appears, indicating the size that the object will be when created.

2. Position the upper left-hand corner of the object where you want to place it, and click again with MB1.

---

Note: Instead of clicking, you can press MB1 and drag the lower right-hand corner of the rectangular outline to any size desired. Release MB1 and your object is created. Additionally, the Palette remembers the last size you choose, and uses that as the default size for that object for the remainder of your Builder Xcessory session. You can change the default size by repeating this procedure.

---

Using MB2

1. With MB2, drag the desired object out of the Palette.

2. Drop it at the location where you would like it to be created.

The object is created with the current default size (that you can reset, as described in Using MB1 ).

Canceling a create operation

To cancel a create operation, press the Escape (Esc) key.

Parents and Children

Creating child objects

As you build your interface, usually you create UI objects as children of other objects. To create objects as children of other objects, drag the child object over the object that is to become the parent. You can do this either on the actual object or in the Browser display area.

If the potential parent is not a legal parent, Builder Xcessory searches up the object hierarchy until a legal parent is found.

If there is no legal parent, or if you do not create the new object directly over an existing object, Builder Xcessory automatically creates the appropriate top-level object for you. This can be a Motif top-level shell, a dialog shell, etc.

Creating multiple children of a single parent

You can create more than one child for a single parent object by selecting the Keep Parent item on the Browser View menu. You can then create a series of child objects by double-clicking on the objects on the Palette. For more information on Keep Parent, see Using Keep Parent or "Keep Parent" on page 63 of the Builder Xcessory Reference Manual.

---

Note: When creating objects, you frequently place them as children of container, or geometry manager objects. These parents often control the size and position of their children. In many cases, notably with the Java containers, you cannot directly control the position or size of the new objects with the mouse. Instead you must edit attributes, or resources, of the objects involved, using the Resource Editor (see Resource Editor ).

Resource Editor

Overview

From the Resource Editor ( Builder Xcessory Resource Editor ), you view and edit the resources and attributes of currently selected UI object to control both the appearance and behavior of your application and its interface. You can edit attributes such as color, font, layout policy and object position, resize behavior, and application actions (callbacks, class methods, or both, depending on your choice of language). Changes made to your object attributes are immediately visible. Refer to Resource Editor for a complete description of the Resource Editor.

---

Note: In this manual, the term "resource" includes Java attributes.

---

Builder Xcessory Resource Editor

Resource Editor Menus

Component

Allows you to modify several basic characteristics of the selected object by performing the following operations:

· Set the default state of the selected objects to be visible or hidden

· With Motif, specify whether the selected object(s) should be created as a widget or as a gadget

· With C, specify a creation routine for the selected object and control the scope of the widget ID (local, global, or other).

View

Allows you to control the appearance of the Resource Editor by performing the following operations:

· Update the Edit/Display Area to show the resources for the currently selected object

· Show/hide the different areas of the Resource Editor

· Select the set of resources displayed by the Resource Editor

Options

The Options Menu allows you to perform the following operations:

· Control whether the Resource Editor automatically updates itself when a new object is selected, or waits for you to manually update it from the View menu or from a Toolbar button. Disabling automatic updates can save time on a slower computer system.

---

Hint: Double-clicking on an object or its Browser representation updates the Resource Editor.

---

· Arrange the resources in alphabetical order or according to type.

· With Motif, set the default resource placement (see Resource placement ) on a per resource-type basis. This allows you to automatically place all Color resources, for example, in an app-defaults file.

Toolbar

The Toolbar, optionally shown with the Resource Editor View menu, allows you to place frequently used menu items within easy reach.

Adding an item to the Toolbar

To place an item on the Toolbar, hold the Shift key down while selecting the desired menu item.

Removing an item from the Toolbar

To remove an item from the Toolbar, hold the Shift key down while selecting the desired Toolbar item.

Header Data

Instance Name

The Instance Name text field displays the instance name of the currently selected object. Type directly into the field to change the name. Builder Xcessory automatically assigns a default name to every object instance as it is created, typically a lower-case version of the class name appended with a number.

---

Note: You should assign your own instance name to every object in your interface. Not only does this simplify development documentation and application maintenance, but it guarantees that Builder Xcessory will not reassign and change the instance name during subsequent work sessions.

---

Class Name

The Class Name text field displays the class name of the currently selected object. You can edit this field to change the type of UI object. Builder Xcessory automatically checks to ensure that the new class exists and is allowed. For example, it does not allow you to change a container with children into an object that does not allow children.

Style

The Style text field displays the name of the style, if any, currently applied to the selected object(s). You can enter a style name into this field, applying the style to the currently selected UI object(s). A style is a collection of resource:value pairs that you create. Styles allow you to set resources on arbitrary groups of objects, and change all objects simultaneously by editing the style definition. Styles are created in parent-child relationships giving you considerable power and flexibility. The style manager is accessed with the Browser Managers menu. For more on styles, see Styles .

Interface File Menu

Builder Xcessory allows you to place UI objects, constants, resources, procedures and styles in different files. This feature is very useful when working with large projects, simplifying development and maintenance.

The Interface File menu in the upper right-hand corner of the Resource Editor allows you to select the file in which to save the object information. Select the proper file from the menu. Use the File Manager (Browser:Managers:UIL Files) to create new files and view and manipulate your existing file system. For more information, see UIL File Manager .

Edit/Display Area

Resources

This area displays the values of resources, which can be edited. The Resource Editor displays resource values for a single object, or for a group of objects. Next to the resource name is one of the following:

· Text field

· Pulldown menu

· Toggle buttons

To edit the resource value, type into the field, or select a value as appropriate. You can also set a resource value with a Builder Xcessory extended editor (see the section Extended editors ).

---

Note: When displaying values for a group of objects, Builder Xcessory adds a " !=" (not equal) symbol to every resource that differs among the objects in the selected group. Click on this symbol for a list of all the differing values for that resource.

---

Search area

To rapidly locate a particular resource, type a portion of the resource name into the search area at the base of the Resource Editor window. Pressing the Return key cycles through all of the resources that match your entry. You can also cycle through them by clicking on the arrow keys at the right-hand side of the search area.

---

Hint: Type any portion of the resource name into the search area. For example, typing " man" matches resources such asAutoUnmanage . This is very helpful when you are not sure of the precise resource name.

---

Extended editors

In addition to directly entering a resource value, Builder Xcessory has extended editors that provide additional ways of selecting a value. The editors are accessed by clicking the pushbutton labeled with an ellipsis (...), located to the right of the resource value. As long as an extended editor remains open, you can use it to change that resource on multiple objects without updating the Resource Editor. This makes it easy to set, for example, the label string on a number of different objects, even if they are of differing class types.

Refer to Extended Editors for more detailed information about the extended editors.

Resource placement

This option menu is located on the right side of the Edit/Display area. It allows you to use a constant, identifier, or expression as the resource value. It also allows you to reset the value to the object's default ( None ), to the Class default ( Class ), or to the Style default ( Style ). When creating or editing classes, this menu also allows you to specify a resource as eligible for modification on a per instance basis ( Expose ).

With Motif, this menu allows you to specify, on a per resource basis, whether to write the value to an X Resource file ( App ), or hardcode the value into your application ( Code ). You can also set the default placement on a per resource-type basis with the Resource Editor Options menu.

Using the Resource Editor

Customizing objects

When building a user interface with Builder Xcessory, you spend much of your time using the Resource Editor to customize your UI objects.

Changing default resource values

To change the default resource values for a Palette object:

1. Create an instance of the object.

2. Set the resource values to your desired defaults.

3. Drag the object instance, with MB2, back onto the Palette.

This object remains on the Palette for you to use in all of your Builder Xcessory sessions.

The three primary methods of setting resources are to set resources with the display area, the extended editors, and styles. Each has its own strengths for different situations.

Using the Resource Editor Edit/ Display area

Use the Resource Editor Edit/Display area under the following conditions:

· To quickly set simple resources on one or more selected objects.

· To set a value for a group of selected objects that currently have different values for a resource.

· When working with a group of resources, perhaps a customized list, accessed through the Resource Editor View menu.

Using the extended editors

Use the extended editors under the following conditions:

· When choosing a complex resource value such as an X11 font name,
or pixmap.

· When choosing from a known set of values such as predefined routines or object siblings.

· When setting differing values of a single resource on many objects.

Using styles

Use styles under the following conditions:

· When working with a style guide, or corporate "look and feel".

· When setting identical values of a resource on many objects.

· When working with a group of objects that should appear or behave similarly to each other.

Example: A Simple Color Selector

The following sections present two examples of a simple color selector. The first example uses Builder Xcessory to build a Motif application. The second uses Builder Xcessory to build a Java application ( Java Example ). The sequential steps are divided into labeled sections for your convenience. You can perform the steps in the order provided, or browse through the sections.

Motif Example

In this example, we'll construct a very simple color selector. The finished application will allow the user to choose a color and see it displayed. Additionally, we will include a simple dialog. A Simple Motif Color Selector shows the finished color selector:

A Simple Motif Color Selector

Project language

For this example, you can work with UIL, C, C++, or ViewKit as your project language.

---

Note: A Java example follows later in this chapter ( Java Example ).

---

Preparing for a Work Session

Starting Builder Xcessory

1. Start Builder Xcessory.

If you have been using Builder Xcessory, select New from the Browser File menu to begin a fresh session.

2. Select either UIL, C, C++, or ViewKit as your language from the Choose a Language dialog of the Browser Options menu.

The following discussion assumes that you have chosen standard (ANSI) C as your programming language. Significant differences for other languages are noted as appropriate.

---

Note: Complete code files for this example are available in the directory {BX}/xcessory/examples/UsersGuide/Chap1 on the BX PRO CD-ROM or from the ICS Website (http:://www.ics.com) for the following languages: C, C++, UIL, or ViewKit.

---

Creating Widgets

To create widgets, use the following procedure:

Creating a MainWindow

1. Create a MainWindow about three inches wide and two inches high.

Click on the MainWindow Palette icon with MB1. A widget outline appears. Move this to a convenient screen location and with MB1, drag the rectangle out to the desired size. (Refer to Using the Palette for review.)

If you are using ViewKit, create a VkWindow rather than a MainWindow. When prompted for a class name, enter "MainWindow". After creating the object, change to Classes view by clicking on the arrow button of the Instances/Classes view combination box and selecting Classes from the drop-down list.

Creating a MenuBar

2. Create a MenuBar and place it as a child of the MainWindow, using one of the following methods:

· Click on the MenuBar Palette icon and click again on top of the MainWindow.

· Drag the MenuBar Palette icon from the Palette and drop it on the MainWindow.

· Drag the MenuBar Palette icon from the Palette and drop it on the MainWindow instance representation in the Browser Display Area. (Refer to Display area and Instances/ Classes view combination box for review.)

---

Note: The MainWindow recognizes the MenuBar widget and automatically moves the MenuBar to the top of the window and resizes it to span the entire width of the MainWindow. Most widgets must be resized manually to fit the MainWindow.

---

Builder Xcessory automatically creates a MenuBar with many common menu entries when you create a VkWindow subclass. To keep the C and ViewKit interfaces parallel in this example, delete all of these items except the Help menu (helpPane). For the helpPane menu, delete all of its children except helpVersionMenuItem, which we will use later.

Creating a BulletinBoard

3. Create a BulletinBoard and place it as a child of the MainWindow, using one of the methods in the previous step. Resize the BulletinBoard as you place it, using one of the methods described in Creating Objects . The MainWindow automatically resizes itself to encompass the BulletinBoard.

---

Hint: The first time you create and place an object, it's usually best to resize it as you place it. Otherwise you are likely to end up with a widget that is too small to easily deal with. If this happens, select Enlarge from the Browser Edit menu, or from the MB3 Quick Access menu.

---

Creating a Scale

4. Create a Scale and place it as a child of the BulletinBoard.

Copying Widgets

1. Copy the Scale and paste two copies as Bulletin Board children, for a total of three scales. Use one of the following methods (check that Scale is currently selected, or select it by clicking on the Scale or its Browser representation):

· Select Copy from the Browser Edit menu. Then select Paste from the same menu. You are presented with an outline of the Scale. Place it into the BulletinBoard. Select Paste a second time and place the next scale into the BulletinBoard.

· Select Copy from the MB3 Quick Access menu by pressing MB3 while the cursor is over the Scale or its Browser representation. Then select Paste from the same menu. You are presented with an outline of the Scale. Place it into the BulletinBoard. Select Paste a second time and place the next Scale into the BulletinBoard.

Shortcut

· While holding down the Control key (Ctrl), drag the Scale with MB2 to another location in the BulletinBoard and drop it. Repeat to create the third Scale. You can also perform this Ctrl-MB2 drag operation with the Browser representations.

---

Hint: Be careful not to drop a new scale onto another scale. That creates the new scale as a child of the existing scale. If this happens, use MB2 (without Ctrl) to drag the new scale out and onto the BulletinBoard.

---

Creating a Drawing Area

2. Create a DrawingArea and place it as a child of the BulletinBoard.

This is the area in which the user will view the selected color. It should be about 1" wide and 1.5" high.

Your Interface in Progress shows the result of the preceding steps:

Your Interface in Progress

Setting Instance Names

Using your own instance names when working with Builder Xcessory is good practice. There's no guarantee that the default names will be maintained from session to session. (Besides, imagine sitting down to maintain your application months later and trying to figure out what pushButton73 is supposed to do...)

1. Assign instance names to the existing widgets.

To save time, we'll only assign names to widgets that will be directly referenced in our code.

2. Select each widget and enter the new name in the Instance Name field at the top of the Resource Editor. Use the following names:

scale -> redScale

scale1 -> greenScale

scale2 -> blueScale

drawingArea -> colorArea

---

Note: When generating C++ or ViewKit code, Builder Xcessory automatically prepends an underscore character to all instance names to construct the class data member used to store the object ID (following accepted convention). So the object named redScale is referenced as _redScale in all generated code.

---

Working with Multiple Widgets

Now that we have created the basic widgets, we'll begin customizing the widgets and designing the layout.

Setting Scale resources

First, we'll set a number of resources on the Scale widgets:

1. Select all of the scales, using one of the following methods:

· Select the first widget to ensure that no other widgets are accidentally included. Select the other widgets, each in turn, with Ctrl-MB1. You can perform this operation directly on your interface, or in the Browser by clicking on the instance representations.

· Using Shift-MB1, drag out a rectangle, enclosing all of the desired widgets. Any widget entirely within the rectangle is selected. You can circle the widgets directly, or you can circle their Browser representations.

2. Update the Resource Editor by selecting Update from the Resource Editor View menu, or from the Update toolbar icon.

3. Set the following resources (check that All Resources is selected from the Resource Editor View menu):

orientation: XmVERTICAL
We'll be using vertical scales.

maximum: 255

minimum: 0

value: 255
We'll start off at white.

showValue: True
This forces the scale to display its current value as a label
next to its scroll thumb.

---

Hint: Use the search area of the Resource Editor to quickly locate each of the resources. (See Search area for review.)

---

4. Set the following resource on the DrawingArea widget:

background: white
We want to ensure that all settings start out in synch,
so make the color display match the scale values.

Moving and Resizing Widgets

Now that we have the Scale widgets oriented properly, we'll work on the layout.

1. Move each of the Scale widgets and the DrawingArea to their intended positions (don't worry about exact positions, we'll use the Alignment Editor to fine-tune the layout).

To move one or more widgets, select the widget(s) and using MB1, position the cursor inside the border of the widget(s) and drag to the new position. During the drag operation, you are presented with a rectangular outline of the widget(s).

---

Hint: To move a manager and all of its children, select the container and its children, and drag with MB1.

---

2. Resize each of the Scales so they are the same width, and resize the Scales and the DrawingArea so that they are the same height.

First, select all of the Scales and set their widths. Next, add the DrawingArea to the group of selected widgets by clicking on it with Ctrl-MB1 and set the heights. You have a choice as to how to resize the widgets:

· Selected widgets have grey borders separated into sides and corners. Grab a section of the border with MB1 and drag to the desired size.

---

Hint: Increasing the size of the layout grid makes it easier to resize and align objects with the mouse. The default value is a 10-pixel resolution. (See Placing Objects with the Layout Grid for more information.)

---

· With all of the widgets selected, use the Resource Editor to set the width and height resources on the selected widgets. If you have one widget width or height already correct, you can click on the "!=" symbol to the left of the resource to display a list of values for the selected widgets. You can then select a value from the list and apply it to the entire group of widgets.

Using the Alignment Editor

3. Use the Alignment Editor to align and distribute the widgets.

Bring up the Alignment Editor (Browser:Edit:Align:Alignment Editor) and set the following values:

Align: Left/Right: As Is

Align: Top/Bottom: Top

Distribute: Horizontal: Edge Gap: 10 pixels

Distribute: Vertical: As Is

With all the widgets still selected, you can now move them as a group into an attractive position, resizing the top-level shell as necessary by using your normal window manager controls.

Your Interface in Progress shows the result of the preceding steps:

Your Interface in Progress

Adding Action to Your Interface

In this section, we add callbacks to various widgets so that when the user adjusts the scales, something actually happens. We will deal with X color capabilities. If you are not familiar with color manipulation in X, consult your Xlib or Motif programming manuals.

Looking ahead, we will need to access the widget IDs for the Scales and the DrawingArea. We'll do this using one method for UIL and C, and using a different method for C++.

Making object IDs accessible

You can make the necessary object IDs accessible using one of the following methods:

---

Note: The example code for this example uses the third method below, so you should not take any action at this time.

---

· Global Storage

Select the widgets, then select the Storage Location option from the Resource Editor Code menu. Choose Global from the dialog that appears, and apply and dismiss the dialog by selecting the OK button.

---

Note: This method is not recommended. As a general rule, avoid global variables in your code.

---

· Other Storage

With most applications, instead of declaring a large number of widgets globally, you typically create your own structure with which to keep track of global data. In these cases, you would select Other as a storage location. See Storage Location for more information.

· Local Storage

In many cases, you can retrieve widget IDs dynamically by using the intrinsics function XtNameToWidget. The C code for this example uses this method rather than creating global variables.

With C++, we can get to the widget instances very easily. In C++, all widget instances are automatically declared as protected members of the class and are thus accessible from class instances.

Creating an application as a single class

For simplicity's sake, we will create our example application as a single class, as follows:

1. Select the MainWindow widget.

2. Using either the MB3 Quick Access menu or the Browser Edit menu, choose Make Class.

3. When prompted for the class name, enter "MainWindow".

4. Once you have created your class, change to Classes view by selecting Classes from the Instances/Classes view combination box on the left side of the Browser.

We need to keep track of two pieces of data, the colormap and the colormap entry index. We use a variable of type Pixel that we call _ pixelVal and a variable of type Colormap called _cmap , and declare them as private member variables in our class. We can declare this with Builder Xcessory, using the Resource Editor, or by adding it directly to the right header file. Because discussion of class creation and manipulation is covered later in this manual ( Classes and Methods ), we will add this directly to the .h file later in the example.

---

Note: To access widget instances from outside a class, add a public method to the class definition. See Adding Methods and Data Members for more information.

---

Working with Callbacks

Now we'll set up a number of callbacks and use some Builder Xcessory editors to complete them.

1. Set the following resources on all of the Scale widgets.

dragCallback: setColorCallback()

valueChangedCallback: setColorCallback()
Any time the scale widgets' values have changed, 
we want to set the color on the Drawing Area.

When you set the valueChangedCallback, rather than typing the procedure name directly into the Resource Editor, use the extended editor (click with MB1 on the button labeled ". . ." to the right of the resource input field). Enter setColorCallback into the Procedure Name field of the extended editor. The procedure appears in the Callback List at the top of the Callback Editor. Use the Apply button to apply this to the Scale widgets.

2. Add the code for the setColorCallback procedure using one of the following methods:

---

Note: The example file callbacks-c.c contains all the code for setColorCallback.

---

---

Note: In order to add code to a file, the file must exist. Builder Xcessory automatically generates code when you edit a callback from the Callback Editor. It's a good habit to be sure that you are in the correct working directory so that your files will be in the right place. Use the Filenames tab in the Code Generation Preferences dialog (Browser:Options: Code Generation Preferences) to set your working directory. Performing a Save, Save As, or Open operation (Browser:File) also sets your working directory.

---

Callback Editor

· Write the setColorCallback code using the Builder Xcessory Callback Editor. Bring this up by clicking on the Edit button to the right of the Callback List in the extended editor. This starts the configured editor with the correct file loaded in at the appropriate User Code Block.

If this is your first time using the Callback Edit feature, you must specify an editor to use, such as emacs or vi. You can do this without dismissing the Callback Editor. Choose an editor from the Options menu (Browser:Options:Tools Preferences:Editor). SeeUsing emacsclient for more information on Emacs.

Generating code

· Add your callback code by generating code (Browser:File:Generate) and editing the appropriate file from outside the scope of Builder Xcessory.

User Code Blocks

In either case, you insert code into a User Code Block. User Code Blocks are present in many different locations in all Builder Xcessory-generated files. Any code that you insert into a User Code Block is preserved by Builder Xcessory whenever source code is generated.

---

Note: If you add code to any of the files outside of these User Code Blocks, it will be lost when you generate new versions of these files with Builder Xcessory.

---

---

Note: When generating C code, the file callbacks-c.c is not generated with User Code Blocks. Instead, this file is scanned each time code is generated and any new functions are appended to it. For this reason, you can make any changes you want to the file without losing them at the next code generation.

---

The function setColorCallback performs the following operations:

· Accesses the widget to determine current settings

· Allocates a color cell the first time it is called (we will keep this color cell and reuse it later)

· Gets/sets values from the Scale widgets

The first two operations vary slightly from language to language, but the final operation is the same for all languages.

Here is the code for the final step of the setColorCallback procedure:

XtVaGetValues(redScale, XmNvalue, &redVal, NULL);

XtVaGetValues(greenScale, XmNvalue, &greenVal, NULL);

XtVaGetValues(blueScale, XmNvalue, &blueVal, NULL);

col.red = redVal << 8;

col.blue = blueVal << 8;

col.green = greenVal << 8;

col.pixel = pixelVal;

col.flags = DoRed | DoGreen | DoBlue;

XStoreColor(XtDisplay(w), cmap, &col);

XtVaSetValues(colorArea, XmNbackground, pixelVal, NULL);

For C++ code, you must edit the file <classname>.C . In our example, this is MainWindow.C .

We mentioned earlier that we would be using variables of type Colormap and Pixel to store the currently selected color. Place the following code in the private User Code Block in the MainWindow.h file.

// Begin user code block <private>

Pixel _pixelVal;

Colormap _cmap;

// End user code block <private>

---

Note: Builder Xcessory makes it easy to specify public/protected/private member data using the Resource Editor, rather than directly editing the header files. See Adding Methods and Data Members for more information.

---

In addition to modifying the callback code, we'll need to initialize the colormap and color cell:

In C++, we'll use the User Code Block at the end of the create routine.

In C, we'll do the initialization in the callback, but protected such that the code is only executed once.

In all cases, the code to initialize the colormap and color cell looks like the following:

XtVaGetValues(_colorArea, XmNcolormap, &_cmap, NULL);

XAllocColorCells(XtDisplay(_colorArea), _cmap, False,
NULL, 0, &_pixelVal, 1);

Working with Menus

Now that we have taken care of the basics of our application, we'll fill in the gaps by adding menus and a simple dialog window.

1. Create a File menu.

Drag a PulldownMenu onto the MenuBar in your MainWindow. Builder Xcessory automatically creates a CascadeButton, aPulldownMenu, and n PushButton (a single menu item).

Use a VkSubMenu if you are generating ViewKit code.

2. Set the following resources on the CascadeButton (VkSubMenu):

instance name: fileCascade

labelString: File

mnemonic: F

3. Set the following resources on the PushButton (VkMenuAction) menu item:

instance name: exitButton

labelString: Exit

---

Note: When you select the CascadeButton, all menu items are displayed in your interface. You can control this display by turning Show Menu Children (Browser:View) on or off while the CascadeButton is selected. With the menu items posted, you can select any number of them in the usual manner.

---

For the next resource, use the extended editor to bring up the Callback Editor.

activateCallback: BxExitCB(0)

In the extended editor, click on the combination box arrow for the Procedure Name. This drops down a list of predefined callbacks and procedures. From this list, select BxExitCB(). In the Parameter Name field, enter 0. For a description of all the Builder Xcessory predefined callbacks, see Predefined Callbacks . You can also add your own procedures to this list. For more information on this process, see See Adding Predefined Callbacks .

Apply this callback with the Apply button.

4. Create a Help menu and apply the following resources to the Cascade:

instance name: helpCascade

labelString: Help

mnemonic: H

To move the Help menu to the right, set the following resource on the MenuBar:

menuHelpWidget: helpCascade

This step is unnecessary with ViewKit. The Help menu is automatically created and placed by the VkWindow class.

5. Set the following resources on the PushButton (VkMenuAction) menu item:

instance name: aboutButton

labelString: About...

activateCallback: BxManageCB("aboutBulletin")
Another one of the built-in callbacks. This one "takes"
a string (a widget instance name), and generates a 
function that manages the widget. Notice that the
generated function actually uses a widget ID, not a string.

We'll create the aboutBulletin widget later.

Do not add the callback or change the instance name in ViewKit; change only the labelString.

Working with Dialogs

1. Create a BulletinBoard as a child of a DialogShell, in turn a child of your MainWindow.

To create a widget as a child of a DialogShell, click on a Palette icon (BulletinBoard, in this case), but rather than placing it by clicking again with MB1, click (and optionally drag to desired size) with MB3. Create this as a child of your MainWindow by locating the cursor over the parent (your MainWindow) when placing with MB3.

You can control the type of Motif Shell created at any given time with the Shells options (Browser:Options:User Preferences:Shells). For more information, see Shells .

Creating dialogs in ViewKit is a different procedure. You must create a subclass of VkGenericDialog by dragging out the VkGenericDialog object from the Palette. When prompted for the class name, enter "AboutBulletin".

2. Set the following resource on the BulletinBoard:

instance name: aboutBulletin

Create an instance of your AboutBulletin class as a child of the VkWindow. Resize the AboutBulletin if necessary, so that it is about 2" wide by 1.5" high.

3. Create a Label as a child of the BulletinBoard (genericDialog) and set the following resources:

labelString: Motif Color Editor
Version 1.0, Created by <your name>

Use the labelString extended editor to create a multiline label.

alignment: center

recomputeSize: true
We want the widget to resize itself to hold the labelString.

4. Create a PushButton as a child of the BulletinBoard and set the following resources:

instance name: okButton

labelString: OK

recomputeSize: true
We want the widget to resize itself to hold the labelString.

activateCallback: BxManageCB("aboutBulletin")
Just like the menu item that popped it up, this uses a built-in callback that unmanages ("pops down") the dialog's shell.

Skip this step for ViewKit. The dialog classes will handle all this automatically. We will connect this dialog to the Help menu item using VkApp::setAboutDialog(). Add this code to the <endcreate> User Code Block of MainWindow.C:

theApplication->setAboutDialog(_aboutBulletin);

Additionally, add the following lines to the <constructor> User Code Block of AboutBulletin.C:

_showCancel=False;

_showApply=False;

_allowMultipleDialogs=False;

No other changes are necessary to display the aboutBulletin.

5. Resize and position the Dialog and its contents to create an attractive window.

Your Interface in Progress shows the result of adding the menus and Dialog:

Your Interface in Progress

Depending on the project language you are using, the object instance hierarchy shown on your Browser display should look likeYour Interface in Browser Display (Using C) or Your Interface in Browser Display (Using ViewKit) .

Your Interface in Browser Display (Using C)

Your Interface in Browser Display (Using ViewKit)

Testing Your Application

We've now reached a point where we would like to test our application and its interface.

Saving the interface

1. Save the interface.(Browser:File).

The first time you save a new project, you'll be presented with a Motif file selection dialog. To change filenames for subsequent save or generate code operations, use the Save As option (Browser:File). Open, Save, Save As, and Generate Code operations all set your working directory for subsequent save and generate operations.

Play Mode

2. Enter Play Mode (Browser:Project) and test your interface.

In Play Mode, you can try out your interface. Click the OK button on the About dialog to dismiss the dialog. (Select Help:About from your application.) The dialog you created should reappear. Test the Scales; you'll see the result of the showValue resource. The labels should change as you move the sliders. Notice, however, the color of the DrawingArea did not change. In Play Mode, all predefined callbacks are active, hence the dialog behavior. Callbacks you've written, however, are not active.

Because the connection between the menu item and dialog is made in User Code Blocks, the dialog does not display in Play Mode.

Testing callbacks

To test callbacks, use one of the following methods:

· Generate Code (Browser:File), compile, link, and run. Using the UNIX command line is still the preferred method for many developers. Builder Xcessory generates both Imake and Makefiles for you.

See Working with Source Code for more information.

· Use an integrated environment (such as WorkShop, Developer Magic, FUSE, etc.).

Make Application (Browser:Project) sends a message to your environment's build tool to have it build your application.

Debug Mode (Browser:Project) runs your application through your environment's interpreter. This has the advantage of providing you with a full debugging environment for the code you've written.

See Integrating Builder Xcessory with Your Environment for more information on integrating Builder Xcessory with other tools.

3. When you are finished testing, re-enter Build Mode (Browser:Project).

Creating a Uniform Look and Feel for Your Application

There are many attributes, such as colors, fonts, and so forth, that contribute to an application's personality, or look and feel. Builder Xcessory helps you to define a total look and feel by building style sheets that can be reused and shared with other developers. You can use system styles to help all of your developers conform to a corporate style guide, clearly identifying all of your applications as part of a single family, and reducing the learning curve for your end-users.

A Builder Xcessory style is basically a collection of resource:value pairs that you define. Styles are related to one another as parents and children. Substyles inherit the resource values of their ancestors while overriding any ancestral values that are specifically re-defined in the substyle.

In this section, we'll build a very simple set of styles for your color selector.

Bringing up the Style Manager

1. Bring up the Style Manager (Browser:Managers:Styles).

In the Style Manager you see a style named "BaseStyle". This is the root style and serves as a placeholder. Notice the padlock symbol next to the name. This style, and any style with the padlock symbol, including system styles you create, cannot be edited.

Creating a new style

2. Create a new style.

Select Create Substyle from the Style Manager:Edit menu. This creates a new style as a child of the currently selected style, in this case as a child of BaseStyle.

---

Note: Just as with other UI objects, styles can be cut and copied or manipulated with the mouse, including all drag and drop operations, reparenting, and so forth.

---

Defining a new style

3. Define the new style.

Select the style (BaseStyle1). Select Edit Substyle from the Style Manager:Edit menu to bring up the Style Editor. You can also double-click on the style to invoke the Style Editor.

Creating a list of resources

First create a list of the resources you want to define in this style, using one of the following methods:

· Click on the Resources combination box arrow. This drops down a scrollable list of all available resources. Click on one or more resources to select them. You can deselect a resource by clicking on it a second time. When satisfied, click again on the combination box arrow.

· Type the resource names into the Resources combination box text field, separating multiple resources with commas. Enter Return to terminate the list.

Your selected resources appear below the combination box, where you can set their values just as you would in the Resource Editor.

You can add or delete resources from a style at any time. This affects all objects using the style.

Adding resources

Add the following resource:value pairs to the style:

background: blue

foreground: yellow

fontList:-*-helvetica-bold-r-*-*-*-100-*-*-*-*-iso8859-1
It's easiest to use the extended editor to select the font.
The font above is Helvetica, bold, 10 point. Choose any values you prefer.

See Extended Editors for more information.

Applying new definitions

Use the Apply button in the Style Editor to set the style definition.

Applying a style to an entire interface

4. Apply the style to your entire interface, preserving the background value of the DrawingArea widget.

You can apply a style to part, or all, of your interface by using one of the following methods:

· Select Apply from the Style Manager to apply the selected style to the selected object or to the selected object and all of its descendants. Force overrides any resource values already set on the affected objects. Otherwise, the resource values are preserved. Don't force the style in this case to maintain the white background of the Drawing Area.

· Dragging a style onto an object or its Browser representation with MB2 forces the style to the object, overriding any duplicated resource values.

· Dragging a style onto an object or its Browser representation with Ctrl-MB2 forces the style to the widget and all of its descendants, overriding any duplicated resource values.

· Selecting any group of widgets and entering the style name into the Style field of the Resource Editor applies the style to all of the selected widgets, preserving any resource values already set.

---

Note: Styles applied to classes while in Instances view are ignored. To apply a style to a class, you must be in Classes view.

---

5. Create a second style as a child of BaseStyle1 (the style we've created above).

Select the intended parent style, then select Create Substyle from the Edit menu of the Style Manager.

6. Add the following resource:value pairs to the style:

foreground: red

fontList: -*-times-bold-r-*-*-*-100-*-*-*-*-iso8859-1
It's easiest to use the extended editor to select the font.
The font above is Times, bold, 10 point.

7. Apply (force) this style to your DialogShell and its children.

Your new style has inherited the blue background from its parent.

8. Edit the first style you created (BaseStyle1), changing the value of the following resource:

background: black

Apply the change in the Style Editor. Note that each widget using that style immediately reflects the change and that each widget using a descendant of this style (including your dialog) also reflects the change.

For more information about styles, including the creation of system styles, refer to Styles .

Working with Source Code

You can generate source code and run your application at any point in the development process.

---

Note: Builder Xcessory always generates code that compiles and runs, generating stubs where your routines will placed. However, if you have begun adding incomplete routines such as callbacks, methods, and so forth, they may prevent your application from executing.

---

Creating source code

To create source code with Builder Xcessory, perform the following steps:

1. Customize your makefile to use your compiler of choice and reflect the library locations of your system (Browser:Options:Code Generation Preferences).

Be sure that your working directory is set correctly with the File Names tab sheet in the dialog. Use the Makefile tab panel to set up your makefile (specify your compiler, library locations, and so on).

You can also add your own include information, customize filenames, and turn on and off generation of any particular file.

See Code Generation Preferences for more information on these dialogs.

2. Generate source code (Browser:File:Generate).

3. Build and run your application.

You can build your application by using one of the following methods:

· Use the Make Application item on the Browser:Project menu. This sends a message to your environment's build tool (WorkShop, Developer Magic, FUSE, etc.) to have it build your application.

· Use the Make or Imake files that Builder Xcessory creates in your normal build process.

You can now run your color selector. This concludes our Motif example.

Additional work

Feel free to continue to explore Builder Xcessory's capabilities. Some ideas for additional work include:

· Experiment with Resource Placement in the Resource Editor and with your styles. With an app-defaults file, your end-user can change various attributes at start-up time with customized resource files, or with the X Toolkit command line options. See Resource placement and Resource Settings for a Widget Instance .

· Experiment with some advanced geometry management. Use the Resource Editor `Class Name' field and change the BulletinBoard to a Form. Edit the Constraint Resources of the Form's children with the Resource Editor to control the application's resize behavior. See XmForm for more information on the Form.

· Place the color sliders into a RowColumn widget. Drag the RowColumn along with its children to the Palette. Reuse the collection in another interface.

· Add mnemonics to the menus and test them in Play Mode.

· Do the tutorials in Appendix C Tutorials .

· Refer to the examples on the BX PRO CD-ROM in the directory {BX}/xcessory/examples/UsersGuide/Chap1 or the ICS Website (http:://www.ics.com) for samples of different programming languages.

Java Example

In this example, we will work with Java to construct a very simple color selector. The finished application will allow the user to choose a color and see it displayed. Additionally, we will include a simple dialog. The finished JAVA color selector is shown in A Simple Java Color Selector .

You have a choice of creating a program that runs as a Java Application, or as an Applet. You can make this choice at any time during the development cycle, and you can easily change your mind at any time as well.

---

Note: We will postpone work with the Abstract Window Toolkit (AWT) advanced layout classes, and classes in general, until later in this guide ( Classes and Methods and Java Layouts ).

---

A Simple Java Color Selector

Preparing for a Work Session

Starting Builder Xcessory

1. Start Builder Xcessory.

If you have been using Builder Xcessory, select New from the Browser File menu to begin a fresh session.

2. Select Java as your language from the Choose a Language dialog of the Browser Options menu.

Applets and Applications

1. Create your main window about three inches wide and two inches high.

You have a choice of creating a Java Application or Applet. To create an Application, use a Frame. To create an Applet, use the Applet. We'll be building a menu system in this example, so create a Frame.

2. Click on the Frame Palette icon. You are presented with a rectangular outline of the object. Move this to a convenient screen location and with MB1, drag the rectangle out to the desired size. (See Using the Palette for review.)

---

Note: From this point forward, we will refer to your top-level object, in this case, a Frame, as your "main window."

---

Creating Objects

1. Create a MenuBar and place it as a child of the main window, using one of the following methods:

· Click on the MenuBar Palette icon and click again on top of the main window.

· Drag the MenuBar Palette icon from the Palette and drop it on the main window.

· Drag the MenuBar Palette icon from the Palette and drop it on the main window instance representation in the Browser display area. (See Display area and Instances/ Classes view combination box for review.)

---

Note: The AWT Frame is the only container that accepts a Menu Bar as a child. It "knows" about MenuBar objects and automatically moves the MenuBar to the top of the window and resizes it to span the entire width of the container.

---

2. Create a Label and place it as a child of the main window.

---

Note: The first time you create and place an object, it is usually best to resize it as you place it. Otherwise you are likely to end up with a widget that is too small to easily deal with. If this happens, select Enlarge from the Browser:Edit menu, or from the MB3 Quick Access menu.

---

3. Create a Scrollbar and place it as a child of the main window.

Selecting Multiple Objects

Select both the Label and the Scrollbar in preparation for copying, using one of the following methods:

· Select the first object normally to ensure that no other objects are accidentally included. Select the other objects, each in turn, with Ctrl-MB1. You can perform this operation directly on your interface, or in the Browser clicking on the instance representations.

· Using Shift-MB1, drag out a rectangle, enclosing all of the desired objects. Any object entirely within the rectangle is selected. You can circle the objects directly, or you can circle their Browser representations.

Copying Objects

1. Copy the Label and Scrollbar, and paste two copies as main window children, for a total of three Label/Scrollbar groups. Use one of the following methods (check that both objects are currently selected, or select them by clicking on the objects or their Browser representations):

· Select Copy from the Browser Edit menu. Then select Paste from the same menu. You are presented with an outline of the object. Place it into the main window. Select Paste a second time and place the next object into the main window.

· Select Copy from the MB3 Quick Access menu by pressing MB3 while the cursor is over any of the objects or its Browser representation. Then select Paste from the same menu. You are presented with an outline of the object. Place it into the main window. Select Paste a second time and place the next object group into the main window.

Shortcut

· While holding down the Control-key, drag the objects with MB2 to another location in the main window and drop them. Repeat to create the third group. You can also perform this Ctrl-MB2 drag operation with the Browser representations.

---

Hint: Be careful not to drop a new scale onto another scale. That creates the new scale as a child of the existing scale. If this happens, use MB2 (without Ctrl) to drag the new scale out and onto the BulletinBoard.

---

Creating a Canvas

2. Create a Canvas and place it as a child of the main window.

This is the area in which the user will view the selected color. It should be about 1" wide and 1.5" high.

Your Interface in Progress shows the result of the preceding steps:

Your Interface in Progress

Setting Instance Names

Using your own instance names when working with Builder Xcessory is good practice. There's no guarantee that the default names will be maintained from session to session. (Besides, imagine sitting down to maintain your application months later and trying to figure out what pushButton73 is supposed to do...)

1. Assign instance names to the existing objects.

To save time, we'll only assign names to objects that are directly referenced in our code.

2. Select each object and enter the new name in the Instance Name field at the top of the Resource Editor. Use the following names:

label -> redLabel

label1 -> greenLabel

label2 -> blueLabel

scrollbar -> redScrollbar

scrollbar1 -> greenScrollbar

scrollbar2 -> blueScrollbar

canvas -> colorArea

---

Note: When generating Java source code, Builder Xcessory automatically prepends an underscore character to all instance names (following accepted convention). So redLabel appears as _redLabel in all generated code.

---

Working with Multiple Objects

Now that we have created the basic objects, we'll begin customizing them and designing the layout.

Setting resources

We'll begin this stage by setting a number of resources.

1. Select all of the Scrollbars using one of the following methods:

· Select the first object normally to ensure that no other objects are accidentally included. Select the other objects, each in turn, with Ctrl-MB1. You can perform this operation directly on your interface, or in the Browser by clicking on the instance representations.

· Using Shift-MB1, drag out a rectangle, enclosing all of the desired objects. Any object entirely within the rectangle is selected. You can circle the objects directly, or you can circle their Browser representations.

2. Update the Resource Editor using one of the following methods:

· Select Update from the Resource Editor View menu.

· Click on the Update toolbar icon.

· Double-click on the selected object or its Browser representation.

3. Set the following resources (check that All Resources is selected from the Resource Editor View menu):

maximum: 255

minimum: 0
Java deals with 8 bits of precision in each color, thus the range of 0 - 255

value: 255
We'll start off at white.

increment: 1
The increment value represents how much the scrollbar's value is changed when its end is clicked once. It represents the minimum change that can be made to the value. Here, and in most cases, we want this to be 1.

visible: 1
The visible value represents the "page size" of the scrollbar, or how much of the minimum-maximum range is represented by the visible area of the scrollbar. It controls the size of the scrollbar thumb. Here, where we are using the scrollbars to control single values, and not a scrolled area, the visible resource is not particularly meaningful. Setting it to one insures that the scrollbar thumb is as small as possible.

---

Hint: Use the search area of the Resource Editor to quickly locate each of the resources. (See Search area for review.)

---

4. Set the following resources on all the Labels:

label: 255
The label resource should match the value of the scrollbars at start-up.

5. Set the following resources on the Canvas:

background: white
We want to make sure all the settings start out in synch, so make the color display match the scale values.

height: 150

weight: 150
Canvas components have no default size, so we set a value here so the layout manager knows how much space to allow.

Java Layouts

Now we'll work on the layout. Java layout objects can be fairly complex to use. Builder Xcessory simplifies this by hiding the actual layout objects from you during the Builder Xcessory session. To specify a layout, you set an attribute on the container using the Resource Editor. For layout policies that allow you to specify positions for the container's children, you set constraint resources on each child using the Resource Editor. Builder Xcessory takes care of synthesizing this information and creating the proper layout and constraint objects for you. For discussion of the various layouts and how to use them, see Java Layouts .

Flow Layout

In our example, we will use the simplest layout, the Flow Layout. This allows our main window to manage each of its children into rows. Each child keeping its preferred size.

1. Set the following resource on your main window (Frame):

layout: FlowLayout

At this point, you'll notice that Builder Xcessory immediately applies the new layout policy to your interface. You can see that the labels, scrollbars, and canvas have all been placed into a row. You'll also notice that you cannot move or resize the children. This is because Java layout objects, for the most part, do not permit resizing.

Working with the Flow Layout

Your labels and scrollbars may not be in the proper order. The FlowLayout object manages its children in the order that they are created, from left to right, one row at a time. To change the order of creation, select an object and use one of the following methods:

· Use the Raise and Lower options from the Browser:Edit menu.

· Use the Raise and Lower options from the MB3 Quick Access menu.

Your Interface in Progress shows the result of the preceding steps:

Your Interface in Progress

Adding Action to your Interface

In this section, we add methods to various objects so that when the user adjusts the scrollbars, something actually happens. Some methods we will write, others are already part of the AWT classes.

1. Set the following resources on all of the Scrollbars.

scrollAbsolute: setColor()

scrollLineDown: setColor()

scrollLineUp: setColor()

scrollPageDown: setColor()

scrollPageUp: setColor()

An AdjustmentEvent argument is added automatically to the setColor() function when the code is generated.

For the last value that you set, use the Builder Xcessory extended editor, invoked by clicking on the button labelled... to the right of the resource field in the Resource Editor. We will use this editor in the next step.

2. Add the code for the setColor method using one of the following methods:

---

Note: In order to add code to a file, the file must exist. Builder Xcessory automatically generates code when you bring up the Method (or Callback) Editor. It's a good habit to be sure that you are in the correct working directory so that your files will be in the right place. Use the File Names tab panel (Browser:Options:Code Generation Preferences) to set your working directory. Performing a Save, Save As, or Open operation (Browser:File) also sets your working directory.

---

Callback Editor

· Write the setColor code using the Builder Xcessory Callback Editor. Bring this up by clicking on the Edit button to the right of the method name in the extended editor. This starts up the configured editor with the correct file loaded in at the appropriate User Code Block.

If this is your first time using the Callback Edit feature, you must specify an editor to use, such as emacs or vi. You can do this without dismissing the Callback Editor. Choose an editor from the Options menu (Browser:Options:Tools Preferences:Editor). See Using emacsclient for information on Emacs.

Generating code

· Add your callback code by generating code (Browser:File:Generate) and editing the appropriate file from outside the scope of Builder Xcessory.

User code blocks

In either case, you insert code into a User Code Block. User Code Blocks are present in many different locations in all Builder Xcessory-generated files. Any code that you insert into a User Code Block is preserved by Builder Xcessory whenever source code is generated.

---

Note: If you add code to any of the files outside of these User Code Blocks, it will be lost when you generate new versions of these files with Builder Xcessory.

---

Insert the following code into the setColor method User Code Block in the AwtFrame.java file.

// Begin user code block <setColor>

int red = _redScrollbar.getValue();
int green = _greenScrollbar.getValue();
int blue = _blueScrollbar.getValue();

_colorArea.setBackground(new Color(red,green,blue));

// The Windows Java ports don't update the canvas
// after setting the background, so we have to do a
// repaint here.

_colorArea.repaint();

_redLabel.setText(Integer.toString(red));
_greenLabel.setText(Integer.toString(green));
_blueLabel.setText(Integer.toString(blue));

// Don't pass this event any further. 
// It's been handled.

return(true);

// End user code block <setColor>

Working with Menus

Now that we have taken care of the basics of our application, we'll fill in the gaps by adding menus and a simple dialog window.

1. Create a File menu.

Drag a Menu onto the MenuBar. Builder Xcessory automatically creates a Menu object, a MenuPane object, and your first Menu Item.

---

Note: When you select the Menu, all of the menu items are displayed in your interface. You can control this display by turning Show Menu Children (Browser:View) on or off while the Menu is selected. With menu items posted, you can select any number of them in the usual manner, drag and drop, raise and lower them, and so forth.

---

2. Set the following resources on the Menu:

instance name: fileMenu

labelString: File

3. Set the following resources on the Menu Item:

instance name: exitButton

labelString: Exit

4. Create an Exit method for the Exit Menu Item:

For the next resource, use the extended editor to bring up the callback editor.

actionEvent: exitApp()

Using the Edit button on the extended editor, add the following line to the User Code Block:

---

Note: You must "Apply" the procedure name before editing it.

---

// Begin user code block <exitApp>

System.exit(0);

// Don't pass this event any further.

// It's been handled.

return(true);

// End user code block <exitApp>

An ActionEvent argument is added automatically to the exitApp() function when the code is generated.

Save the file and apply this method with the Apply button on the extended editor.

5. Create a Dialogs menu and apply the following resources to the Menu:

instance name: dialogMenu

labelString: Dialogs

6. Set the following resources on the Menu Item:

instance name: aboutButton

labelString: "About..."

actionEvent: popupAbout()

// Begin user code block <popupAbout>

_aboutDialog.show();

// Don't pass this event any further.

// It's been handled.

return(true);

// End user code block <popupAbout>

An ActionEvent argument is added automatically to the popupAbout() function when the code is generated.

We'll create the aboutDialog in the next section.

Working with Dialogs

1. Create a Dialog as a child of your main window.

When creating Dialogs, you are prompted for a class name. Specify the desired name.

2. Set the following resource on the Dialog:

instance name: aboutDialog

Resize the Dialog, if necessary, so that it is about 2" wide by 1.5" high.

3. Create the Dialog contents.

Because the Dialog is now a class, you cannot modify its instance directly. You need to enter Builder Xcessory Classes view. Select Classes from the combination box located under the Browser Panner. (See Builder Xcessory Browser .)

Once in Classes view, you can edit the object(s) directly.

4. Prepare the Dialog layout.

For this section, we'll use a new layout policy, Border. The Border layout places its children into North, South, East, West, and Center positions. (See Border .) Set the following resource on the Dialog:

layout: Border

5. Add two Labels to the Dialog. (Java does not directly support multiline labels.) Set the following resources:

label: Java Color Editor

alignment: Center

direction: North

label1:

label: Version 1.0, Created by <your name>

alignment: Center

direction: Center

6. Create a Panel as a child of the Dialog.

The Border layout policy resizes each child to entirely fill their specified region. We will add a "Dismiss" button to the dialog and do not want it to resize. Placing the button in the Panel prevents this. Set the following resources:

layout: Flow

direction: South

7. Create a PushButton as a child of the Panel and set the following resources:

label: OK

actionEvent: popdownDialog()

// Begin user code block <popdownDialog>

if(e.getActionCommand().equals("Ok"))this.setVisible(false);

// Don't pass this event any further.

// It's been handled.

return(true);

// End user code block <popdownDialog>

8. Enter Instances view.

Now that we've finished the Dialog, select Instances from the Browser combination box.

Your Interface in Progress shows the result of the preceding steps:

Your Interface in Progress

Testing Your Application

We've now reached a point where we would like to test our application and specifically, its interface.

1. Save the interface (Browser:File:Save).

The first time you save a new project, you'll be presented with a file selection dialog. To change filenames for subsequent save or generate code operations, use the Save As option (Browser:File). Open, Save, Save As, and Generate Code operations all set your working directory for subsequent save and generate operations.

2. Enter Play Mode (Browser:Project:Play Mode) and test your interface.

In Play Mode, you can try out your interface. Your menus will post, buttons will push, and so forth. You can test all of your resize behavior. Methods you've written, however, are not active. To test these methods, generate code by selecting Generate Code from the Browser File menu, compile, and run.

---

Note: Using the UNIX command line is still the preferred method for many developers. Builder Xcessory generates both Imake and Makefiles for you. See Working with Source Code for more information.

---

3. When you are finished testing, re-enter Build Mode (Browser:Project).

Creating a Uniform Look and Feel for Your Application

There are many attributes, such as colors, fonts, and so forth, that contribute to an application's personality, or look and feel. Builder Xcessory helps you to define a total look and feel by building style sheets that can be reused and shared with other developers. You can use system styles to help all of your developers conform to a corporate style guide, clearly identifying all of your applications as part of a single family, and reducing the learning curve for your end-users.

A Builder Xcessory style is basically a collection of resource:value pairs that you define. Styles are related to one another as parents and children. Substyles inherit the resource values of their ancestors while overriding any ancestral values that are specifically re-defined in the substyle.

In this section, we'll build a very simple set of styles for your color selector.

Bringing up the Style Manager

1. Bring up the Style Manager (Browser:Managers:Styles).

In the Style Manager you see a style named "BaseStyle". This is the root style and serves as a placeholder. Notice the padlock symbol next to the name. This style, and any style with the padlock symbol, including system styles you create, cannot be edited.

Creating a new style

2. Create a new style.

Select Create Substyle from the Style Manager:Edit menu. This creates a new style as a child of the currently selected style, in this case as a child of BaseStyle.

---

Note: Just as with other UI objects, styles can be cut and copied or manipulated with the mouse, including all drag and drop operations, reparenting, and so forth.

---

Defining a new style

3. Define the new style.

Select the style (BaseStyle1). Select Edit Substyle from the Style Manager:Edit menu to bring up the Style Editor. You can also double-click on the style to invoke the Style Editor.

Creating a list of resources

First create a list of the resources you want to define in this style, using one of the following methods:

· Click on the Resources combination box arrow. This drops down a scrollable list of all available resources. Click on one or more resources to select them. You can deselect a resource by clicking on it a second time. When satisfied, click again on the combination box arrow.

· Type the resource names into the Resources combination box text field, separating multiple resources with commas. Enter Return to terminate the list.

Your selected resources appear below the combination box, where you can set their values just as you would in the Resource Editor.

You can add or delete resources from a style at any time. This affects all objects using the style.

Adding resources

Add the following resource:value pairs to the style:

background: blue

foreground: yellow

fontList:-*-helvetica-bold-r-*-*-*-100-*-*-*-*-iso8859-1
It's easiest to use the extended editor to select the font.
The font above is Helvetica, bold, 10 point. Choose any values you prefer.

See Extended Editors for more information.

Applying new definitions

Use the Apply button in the Style Editor to set the style definition.

Applying a style to an entire interface

4. Apply the style to your entire interface, preserving the background value of the Canvas widget.

You can apply a style to part, or all, of your interface by using one of the following methods:

· Select Apply from the Style Manager to apply the selected style to the selected object or to the selected object and all of its descendants. Force overrides any resource values already set on the affected objects. Otherwise, the resource values are preserved. Don't force the style in this case to maintain the white background of the Canvas.

· Dragging a style onto an object or its Browser representation with MB2 forces the style to the object, overriding any duplicated resource values.

· Dragging a style onto an object or its Browser representation with Ctrl-MB2 forces the style to the widget and all of its descendants, overriding any duplicated resource values.

· Selecting any group of widgets and entering the style name into the Style field of the Resource Editor applies the style to all of the selected widgets, preserving any resource values already set.

---

Note: Styles applied to classes while in Instances view are ignored. To apply a style to a class, you must be in Classes view.

---

5. Create a second style as a child of BaseStyle1 (the style we've created above).

Select the intended parent style, then select Create Substyle from the Edit menu of the Style Manager.

6. Add the following resource:value pairs to the style:

foreground: red

fontList: -*-times-bold-r-*-*-*-100-*-*-*-*-iso8859-1
It's easiest to use the extended editor to select the font.
The font above is Times, bold, 10 point.

7. Apply (force) this style to your DialogShell and its children.

Your new style has inherited the blue background from its parent.

8. Edit the first style you created (BaseStyle1), changing the value of the following resource:

background: black

Apply the change in the Style Editor. Note that each widget using that style immediately reflects the change and that each widget using a descendant of this style (including your dialog) also reflects the change.

For more information about styles, including the creation of system styles, refer to Styles .

---

Note: Bugs in the current Windows implementation of AWT prevent the java.awt.Panel class from behaving correctly, particularly with regard to the background resource. If you display this example application on a Windows system, this will be evident.

---

Working with Source Code

You can generate source code and run your application at any point in the development process.

---

Note: Builder Xcessory always generates code that compiles and runs, generating stubs where your routines will be placed. However, if you have begun adding incomplete routines such as callbacks, methods, and so forth, they may prevent your application from executing.

---

Creating source code

To create source code with Builder Xcessory, perform the following steps:

1. Customize your makefile to use your compiler of choice and reflect the library locations of your system (Browser:Options:Code Generation Preferences).

Be sure that your working directory is set correctly with the File Names tab sheet in the dialog. Use the Makefile tab panel to set up your makefile (specify your compiler, library locations, and so on).

You can also add your own include information, customize filenames, and turn on and off generation of any particular file.

See Code Generation Preferences for more information on these dialogs.

2. Generate source code (Browser:File:Generate).

3. Build and run your application.

Use the Make or Imake files that Builder Xcessory creates from the UNIX command line, your normal build process. Builder Xcessory also generates an HTML file for you. You can load this file into your favorite Java-enabled web browser and run your Java application from there.

---

Note: Though you can launch a Java application from your browser, keep in mind that many common application-oriented methods, such as System.exit() generate security violations in a browser environment. In this case, it would mean that the only way to exit the application would be to exit the browser.

---

You can now run your color selector. This concludes our Java example.

Additional work

Feel free to continue to explore Builder Xcessory' capabilities. Some ideas for additional work include:

· Experiment with the GridBag layout.

One major problem with using the Flow layout is that the default size for Java scrollbars is very small. Simply setting their height resource does not work, as it does for the Canvas class (you'll have to ask Sun why this is so). Getting a reasonable size for the scrollbars requires using a layout manager that controls the size of its children. FlowLayout does not; it merely asks each component for its preferred size and tries its best to lay them out as they like. One idea would be to use a GridBag, with the components laid out along row 0. The fill for the scrollbars would be set to vertical, while the canvas would be filled along both axes. The labels would most likely want a center anchor.

(See GridBag for more information.)

· Allow the user to enter an RGB value directly.

The labels might be replaced with TextField components. The actionEvent method must first verify that a valid number had been typed (perhaps warning the user with another dialog), then ensure that the scrollbars and labels are in sync, and then call the setColor() method.

Creating a class

To create a class, use one of the following methods:

· In Instances view, select the top-level object of the hierarchy that you wish to make a class. Then select Make Class from the Browser:Edit menu (or MB3 Quick Access menu). You are prompted for the name of the new class.

· In Classes view, drag an object from the Palette and place it on the display. You are automatically prompted for the name of the new class. If you drag a widget, your class consists of only that widget. If you drag another class object, the new class is a subclass of the specified object.

Once you supply a class name in the dialog displayed for that purpose, the class is automatically included in the Project Classes group of the Palette.

For example, you might want to create a class that combines a label and text field within a form.

Example:
Creating an object

First, create the objects by following these steps:

1. Create a form.

2. Place a label and a text field within the form as shown in the following figure:

Widget Hierarchy

3. You can use the Form Editor and Ctrl+MB1 on the attachment handles to set any appropriate constraint resources. The collection should now look something like the following figure:

LabelField Widget Collection

Example:
Making a collection of objects into a class

To make this collection of objects into a class, follow these steps:

1. Select the container widget (the form) by clicking on its instance name in the Browser widget hierarchy.

2. Select Make Class from the Browser Edit menu, or from the MB3 Quick Access menu.

3. In the Name field, enter LabelField. The new class is automatically
added to the Palette in the Project Classes group as shown in the following figure:

LabelField Class on Palette

The collection is now collapsed into a class instance on the Browser as shown in the following figure:

Class Instance labelField

Switch the Browser to Classes view. The class is now expanded on the Browser and you can view its entire membership as shown in the following figure:

LabelField Widget Hierarchy

Editing resources and adding callbacks and event methods

When Builder Xcessory is in Classes view, any component of the class can be modified and any component's widget resource can be exposed. Select the component or components in question and edit the resource values, using the Resource Editor, extended editors, or styles. Callbacks and event methods are treated just as any other resource. Changes made to the class propagate to all instances of the class and its subclasses throughout the interface.

Callbacks for class members (Motif) are generated in source code as two separate methods, described in detail in Object-Oriented Programming with C++ and OSF/Motif (Prentice Hall, 1995, 2nd Ed. ISBN 0-13-209255-7) by Doug Young. Exposing a callback results in a third, public method.

See Using Callbacks in C++ Classes for detailed information on these methods.

Creating class instances

You create class instances in the same manner in which you would instantiate any other Palette object, that is, select it on the Palette and drag it to the interface window. Refer to Using the Palette .

Reusing classes

Once saved in the Palette Private Classes or Public Classes group, a class is available each time you start Builder Xcessory. You can also read a previously saved class file into an interface.

Additionally, as with widgets, you can add VkComponent and UIComponent subclasses to the Palette, allowing you to completely code a class and its methods and interact with the fully-working object in Play Mode. For more information on Play Mode see Using Play Mode . For information on adding classes to the Palette, see Permanently Placing Classes on the Palette .

Subclassing

Classes can also be subclassed, furthering the re-usability and usefulness of classes. Subclasses can be modified by adding additional widgets, adding methods and data members, and changing resources.

Adding Methods and Data Members

Methods

In addition to their component objects, classes include methods and the data on which they operate. You can add additional class members from the Resource Editor in Classes view (see Resource Editor in Classes View ). Both methods and data are displayed in a list sorted by item type and scope. Parameter argument types are displayed for methods only.

Class Member Editor

Class Member Editor illustrates the Class Member Editor for a class method:

User Code Blocks

Member methods and data can also be inserted directly into the User Code Blocks of the class file. These edits are not visible or editable in the Resource Editor. Because they are inside User Code Blocks, they are retained when the files are regenerated.

Exposing Resources

When designing a class with reuse in mind, you must decide what aspects of the class will be customizable on a per instance basis. Within Builder Xcessory, you can do this by exposing resources .

A resource on a component object is exposed when its default value can be overridden for a particular instance of the class. Ordinarily, you expose resources when you wish to vary a resource value for different instances of a class. For example, you might want to allow users of the LabelField class described at the beginning of this chapter to set the value of the labelString resource for each instance of the class.

---

Note: For any resource that you want to expose within a class, you must specify a default resource value in the class definition.

---

Exposing a resource

To expose a resource, follow these steps:

1. Switch the Browser to Classes view.

2. Update the Resource Editor for the desired component object.

3. Scroll the Resource Editor to the desired resource.

4. Set the resource to the value that you wish each instance to take by default.

5. Select Expose from the option menu to the right of the resource text field.

---

Note: Exposed resources are designated on the Resource Editor with an "open eye" icon to the left of the option menu. The option menu continues to display the resource placement setting (for example, "Code" or "App").

---

Editing the value of an exposed resource

To edit the value of an exposed resource on a class instance, follow these steps:

1. Select a class instance (Be sure to be in Browser:Instance view).

2. Update the Resource Editor.

The Resource Editor now displays exposed resources with the notation:

<element_name>.<resource>

3. Scroll the Resource Editor to the desired resource.

4. Edit and apply the resource value as you would any other resource value.

Only the currently selected instance takes this resource value. The default resource value in the class definition is unchanged.

---

Hint: To temporarily turn off display of the element's instance name in an exposed resource name (that is, display background instead of myElementInstance.background ), hold MB1 down while the cursor is over the name. To locate a particular resource quickly, use the Resource Editor Search Area.

Exposing Callbacks and Event Methods

In addition to customizing the appearance of your class, you might also want to customize its behavior. The behavior, or interaction between your UI and the rest of your application is generally controlled with callbacks in Motif, and with event methods in Java. For more information, see Callback Procedures and Event Methods .

As you build your classes, you build a great deal of functionality into your UI classes using the callbacks and event methods for the class elements and the methods, (public, private, and protected) for the class itself.

You can give instances of a class access to the callbacks or event methods of its elements by exposing them just as you would any other resource. The process with which you do this is identical regardless of the language you are using. The results, however, differ slightly.

---

Note: This is an area where it is very easy to break "good" object-oriented programming practice. Consider very carefully whether you want to use an exposed callback or event method, or whether you should use a subclass instead.

---

---

Note: In ViewKit, it is better practice to use ViewKit's callback mechanism, provided by VkCallbackObject, rather than exposed callback resources.

---

Exposing Callbacks

Exposing a resource

To expose a callback or event method, follow these steps:

1. Switch the Browser to Classes view.

2. Update the Resource Editor for the desired component object.

3. Scroll the Resource Editor to the desired callback or event method.

4. Set the resource to the value that you want each instance to take by default.

5. Select Expose from the option menu to the right of the resource text field.

---

Note: Exposed resources are designated on the Resource Editor with an "open eye" icon to the left of the option menu.

---

Callback Source Code

With Motif, you can choose whether the instance callback routine augments or replaces the class's exposed callback. This is controlled by the Remove Overridden Exposed Callbacks toggle on the Code Generation tab of the Code Generation Preferences dialog (Browser:Options). Refer to Toggle options for more information.

Callbacks for class members (Motif) are generated in source code as two separate methods, described in detail in Object-Oriented Programming with C++ and OSF/Motif (Prentice Hall, 1995, 2nd Ed. ISBN 0-13-209255-7) by Doug Young. Exposing a callback results in a third, public method.

See Using Callbacks in C++ Classes for detailed information on these methods.

Subclassing and Receptors

When designing your classes with reuse in mind, you must strike a balance between power and flexibility. If a class has too little functionality, you have little incentive to use and reuse it, and if a class has too much functionality, it often becomes overly specific and difficult to use in other situations. If a class has too much flexibility (through exposed resources and methods), it might be reused, but maintenance benefits to the application are lost.

Subclassing helps to balance functionality, flexibility, and power. Creating a new class by subclassing an existing class allows you to adapt the class to a specific situation, while allowing other developers to leverage their knowledge of the often-reused parent class. Builder Xcessory makes it extremely simple to create subclasses.

Subclassing

All classes created within Builder Xcessory can also be subclassed. A subclass is a class created from another class, which inherits all of the objects, resources, methods, and data members of the superclass while also adding its own.

Making a subclass

To make a subclass, follow these steps:

1. Place Builder Xcessory in Classes view (Browser:Classes view).

2. Select the class you want to subclass.

3. Select Make Subclass from the Browser Edit (or MB3 Quick Access) menu. You are prompted to name the subclass. A new class is created and displayed in the Browser.

Example: 
Make a subclass ToggleField

To continue the example that began on Example: Creating an object , you might want to make a subclass ToggleField from the class LabelField, which consists of a form container with a label and a text field as children.

To make a subclass ToggleField from the class LabelField, follow these steps:

1. Confirm the Browser is in Classes view.

2. Select LabelField on the instance hierarchy.

3. Select Make Subclass from the Browser Edit (MB3) menu.

4. You are prompted to name the subclass. Name it ToggleField. The new class is created and displayed in the Browser ( Superclass LabelField and Subclass ToggleField ):

Superclass LabelField and Subclass ToggleField

---

Note: Note that LabelField appears in ToggleField's hierarchy with a colon designating it as the superclass of ToggleField.

---

5. You can now add methods and data members to your new subclass using the Resource Editor and the Member Editor. (See Adding Methods and Data Members for review.)

Editing superclasses

You can edit any of the exposed resources of the parent, or superclass. Edits made to the superclass propagate to all subclasses. Likewise, in each subclass instance, the default value of an exposed resource can be overridden, as can methods and data members.

Overriding exposed resources

To override the exposed resources of a superclass, use the Browser to select the :superclass object, then use the Resource Editor to specify the new resource values. ( :LabelField is an example superclass in Superclass LabelField and Subclass ToggleField .)

Receptors

Frequently, a major element of a new subclass is one or more additional children. Builder Xcessory allows you to add children when subclassing by designating a container in your superclass as the receptor . Specifying a receptor on a class allows you to extend the object hierarchy of an existing class through its subclasses while not affecting the original class and its class instances.

Making receptors

To specify a receptor (only one is allowed per class), follow these steps:

1. Confirm the Browser is in Classes view.

2. Select the component object that you want to designate as the receptor.

3. Select Make Receptor from the Browser Edit (Quick Access MB3) menu. A small icon, consisting of a square within a square, is placed to the left of the object in the Browser class hierarchy, designating the object as the receptor (for example, see Receptor ).

Any objects subsequently added to a subclass automatically become children of the receptor.

Example: Making the Form widget a receptor

Continuing the previous example, you might want to add to the subclass ToggleField a toggle button not part of the superclass LabelField. The toggle button has the LabelField class's form widget as its parent; therefore, you make the form the receptor.

To make the Form widget a receptor, follow these steps:

1. Confirm that the Browser is in Classes view.

2. Select the Form component within the LabelField hierarchy.

3. Select Make Receptor from the Browser Edit (MB3 Quick Access) menu. The result is shown in the following figure:

Receptor

Once you make a component object of a class a receptor, you can add children to any of that class's subclasses.

Adding children to subclasses

To add a child to a subclass, follow these steps:

1. Confirm the Browser is in Classes view.

2. Using MB2, drag the child widget from the Palette and drop it on the object with instance name ":<SuperclassName>" on the desired subclass's instance hierarchy.

The superclass's receptor is the designated parent of any objects added to a subclass.

Adding a toggle button

Continuing the LabelField example, assume you want to include a toggle button to the subclass ToggleField.

Saving and Sharing Classes

An important part of reuse is making the classes easily available to other developers. Builder Xcessory enables you to store and share classes with other Builder Xcessory users.

---

Note: Individual reuse is useful only when entire groups and organizations reuse the same objects.

---

Saving Classes

When you make a class, the class is added automatically to the Project Classes group at the bottom of the Palette. Classes in the Project Classes group are saved with your project, allowing other developers to access those classes. To use the class in other projects, or move it to the Private or Public Classes group, you must save it to a separate file.

Saving a class

To save a class, follow these steps:

1. Confirm the Browser is in Classes view.

2. Select the desired class.

3. Select Save Class from the Browser File menu to display a file selection dialog:

File Selection Dialog

4. Enter the file name and directory path, and click OK to save the class.

Sharing Classes

Before you can share a class, you must save the class UIL file separately from the rest of the project. This separates the class definition from any given interface.

Conditions for sharing classes

You can share classes under the following conditions:

· By manually placing classes into locations accessible to all developers, and then importing the classes manually

· By using the Builder Xcessory Palette.

Sharing Class Libraries

You can also share a library of classes among a group of users.

Building a class library

To build a class library:

1. Generate code for your classes and build your library.

2. After generating the class files, deselect the Generate Class toggle (Resource Editor:Component) for each class in your library and save the classes into separate files using Save Class (Browser:File:Class).

3. Move the classes to the Public Classes group.

4. Move the header files and library to the desired location. Save the source files to preserve any user code blocks for future modifications.

Preparing a library for sharing

Now, when you use the class in an application, Generate Code is deselected by default. You still need to do a couple of things:

1. If you are generating C++ and included the BX-generated UIComponent in your library, deselect the Class Tree Root toggle button in the File Names tab (Browser:Options:Code Generation Settings).

---

Note: If you always want to include the UIComponent in your library, click the Save As Default button on the File Names tab. The UIComponent will not be generated in the future by default.

---

2. Add the include path for the class header files and library containing the class to the application Makefile and select the Don't Include Ungenerated Class Files toggle button on the Makefile tab (Browser:Options:Code Generation Settings).

---

Note: If you always want to include the library and its header file path in the Makefile, click the Save As Default button on the Makefile tab.

---

Moving Classes Between Groups

Dragging classes

Once you save the class, you can drag the class from the Project Classes group to either the Private or Public Class section on the Palette.

---

Note: You must be in Outline view to drag classes from one group to another.

---

· If you leave the class in the Project Class group, the class appears on the Palette when the project file is loaded.

· If you move the class into the Private Class group, the class is saved into the .builderXcessory directory in your home directory and appears on the Palette each time you start Builder Xcessory.

· If moved into the Public Class group, the class is saved into the {BX}/xcessory/classes system directory and appears on the Palette of all Builder Xcessory users in your organization.

---

Note: Classes moved into either the Private or Public groups are locked by default. You cannot edit these classes, regardless of directory permissions. Unlock classes by selecting Unlock Class from the Class menu of the Browser File menu.

---

Reading Classes

Reading a class

You can read classes that you or other developers saved. To read a class, follow these steps:

1. Select Read Class from the Class menu of the Browser File menu. A file selection dialog is displayed ( File Selection Dialog ).

2. Enter the file and directory of the class, and click OK.

Specifying Include Files

Each class can have its own set of include files, which can be specified from the Resource Editor when Builder Xcessory is in Classes view. When the class is selected, the Resource Editor includes a section labeled Class File Include Information that in turn includes two subsections: Base Class Includes and Derived Class Includes (see Class Includes Sections ).

---

Note: Derived Classes are available only when you choose C++ as your default language.

---

Resource Editor:

Class Includes Sections

The two sections are scrollable text regions. The contents of the text regions are included verbatim into the base and derived class .hfiles. This allows you to specify different include file information for each class that you create.

---

Note: Derived Classes are supported for backward compatibility only. We do not recommend using Derived Classes.

 

To add the toggle button to ToggleField, follow these steps:

1. Confirm the Browser is in Classes view.

2. Drag the toggle button from the Palette.

3. Place the toggle button on the LabelField object on ToggleField's instance hierarchy ( Subclass with Child ):

Code Generation

The following sections describe the files generated by Builder Xcessory for each language.

C Code Generation

Builder Xcessory generates the following files (see files generated for C for more information):

· main-c.c contains function calls necessary for any application.

· creation-c.c contains the code to initialize and create all widgets in the application.

· creation-c.h contains include information, constant definitions, and pixmap specifications.

· callbacks-c.c contains code for all callbacks specified.

· bxutils-c.c contains functions used by Builder Xcessory-generated code.

· makefile-c and Imakefile allow the generated code to be built into the application.

When using classes, Builder Xcessory generates the same files and adds some new ones. The differences are listed as follows:

· creation-c.c is the same for all widgets not part of a class. For each instance of a class, this file has a call to a function to create and initialize the widgets comprising that class. This results in a smaller file.

· creation-c.h also includes the <class>.h files for each class <class> that is generated.

· makefile-c and Imakefile contain the same targets, but include the additional class files to compile and link in to create the targets.

In addition, the following files are created for every class, <class>, created in Builder Xcessory:

· <class>.c contains the code to create and initialize the widgets comprising the class.

· <class>.h contains a data type that is a structure of the widget ID's of all widgets that are part of the class.

C++ Code Generation

If you do not have any classes when you generate the C++ code, the contents of each TopLevelShell are generated as a class and named using the instance name of the shell's immediate child.

In all cases, the following files are generated (see Files generated for C++ for more information):

· main-C.C contains function calls necessary for any application and calls the constructor of each generated top-level class.

· <class_name>.C contains the code for the constructor and destructor for each class generated. In the constructor, all the objects in the application are created (similar in C code to the creation-c.c file).

· <class_name>.h defines the class created by <class_name>.C and any required structures.

· UIComponent.C contains the base class for all objects created.

· UIComponent.h contains the definition of the UIComponent base class and any required structures.

· callbacks-C.C contains code for all callbacks specified on top-level shells and on other elements that are not specific class members.

· bxutils-C.C contains functions called in the other generated files.

· defs-C.h contains definitions of constants, pixmaps, and global instances of widgets or classes used in the application.

· makefile-C and Imakefile allow the generated code to be built into the application.

UIL Code Generation

Builder Xcessory generates the following files (see Files generated for UIL for more information):

· main-uil.c contains function calls necessary for any application.

· uil.uil contains a description of the widgets.

· callbacks-uil.c contains code for all callbacks specified.

· main-uil.h contains declarations of constants, and global instances of widgets or classes used in the interface.

· bxutils-uil.c contains functions used by Builder Xcessory code.

· makefile-uil and Imakefile allow the generated code to be built into the application. Imakefile specifies both UIL and C imake information. Makefile has targets for UIL as well as the associated C files.

· app-defaults includes all resources with app-defaults value set to App.

ViewKit Code Generation

Builder Xcessory divides ViewKit code generation into the following files (see Files generated for ViewKit for more information):

· main-vk.C contains function calls necessary for any application. VkApp is instantiated here along with other application level classes, such as your top-level window classes.

· <class_name>.C contains the code for the constructor and destructor for each class you created. In the constructor, all objects in the application are created (similar in C code to the creation-c.c file). The constructor also binds any callbacks assigned to widgets and contains the methods for those callbacks.

· <class_name>.h defines the class created by <class_name>.C and any structures that it needs.

· defs-vk.h contains the constants registered in your interface.

· callbacks-vk.C contains code for all callbacks specified on elements that are not specific class members.

· bxutils-vk.C contains functions for Builder Xcessory-generated code calls.

· makefile-vk and Imakefile allow the generated code to be built into the application.

Builder Xcessory automatically subclasses from VkWindow, VkSimpleWindow, and VkComponent as appropriate. Additionally, Builder Xcessory subclasses any classes you create from Motif widgets from VkComponent.

Java Code Generation

Builder Xcessory divides Java code generation into the following files (see Files generated for Java for more information):

· MainApp.java creates an instance of each top-level class in your program. If you have only one top-level class, you might not need to use this class. (This is similar to the C language file main.c .)

· MainApp.html is an HTML file in which your applet is embedded, or with which you can launch your application using the Java Virtual Machine in your browser.

· <class_name>.java contains the code for each class you created.

· Defs.java contains the constants registered in your interface.

· makefile-java allows the generated code to be built into the application or applet.

---

Note: All generated files have comments generated in the JavaDoc format.

---

Java application attributes

Builder Xcessory allows you to create Java applications or Java applets. Java applications have the following attributes:

· Contain a single main() method

· Execute in a stand-alone fashion

· Do not require a browser

Java applet attributes

A Java applet runs from a browser. Rather than having a single main() method, an applet implements a set of methods that control how it is initialized, drawn, handles events, and so forth. Java applets have the following attributes:

· Require a Java-enabled browser or applet viewer

· Must be embedded in an HTML page

· Typically subject to restrictions, depending upon the browser, due to security issues relating to the transfer of code

---

Note: Due to security restrictions present in most web browsers, many commonly used system methods, such as System.exit()cannot be used.

Using Builder Xcessory with DEC FUSE Tools

The DEC FUSE tools are launched from a small control panel. The tools use DEC MCMS (MultiCasting Message Service) as the underlying message layer.

To use Builder Xcessory with DEC FUSE tools, select Builder Xcessory from the control panel Tools menu.

Using Builder Xcessory with SunSoft Workshop Tools

The SunSoft Workshop tools can be used separately or from a small tool control panel. The tools use ToolTalk as a system for passing messages.

To start Builder Xcessory with SunSoft Workshop tools, use one of the following methods:

· Double-click on the Builder Xcessory icon in the Workshop Manager.

· Start Builder Xcessory from the command line with the -workshop flag. This flag tells Builder Xcessory to initialize ToolTalk messaging with the Workshop messages.

Using Builder Xcessory with Developer Magic

The SGI Developer Magic tools can be invoked separately or from a small tool control panel. The tools use ToolTalk as a system for passing messages. For example, the debugger can tell the editor to load a file.

To start Builder Xcessory with Developer Magic, use one of the following methods:

· Select Builder Xcessory from the Launch menu of any of the Developer Magic tools.

· Start Builder Xcessory from the command line with the -devmagic flag. This flag tells Builder Xcessory to initialize ToolTalk messaging with the Developer Magic messages.

From your environment manager, you can stop, iconify, and deiconify Builder Xcessory. You can also raise Builder Xcessory windows.

Selecting a build or make tool

When developing an application in Builder Xcessory, you can use your environment's build or make tool at any time. You must tell Builder Xcessory which tool you want to use, verify that your makefile parameters are correct, and then execute a build of your application.

To use your environment's build or make tool, follow these steps:

1. Select Tools Preferences from the Browser Options menu to display the Tools Customization dialog.

2. If you use your environment's build or make tool, skip to step 4.

3. If you want to use CodeCenter or ObjectCenter to manage the build instead of the environment-provided tool, select Use CenterLine Tools from the Debugger and Build Manager tab (see Debugger & Build Manager with Centerline Defaults ).

Debugger & Build Manager with Centerline Defaults

4. Verify the make parameters by selecting Code Generation Preferences from the Browser Options menu to display the Code Generation Preferences dialog, and then clicking the Makefile tab ( Makefile Tab on the Language Settings Dialog ).

Makefile Tab on the Language Settings Dialog

5. Change any incorrect parameters.

6. To execute a build of your application, select Make Application from the Browser Project menu.

Builder Xcessory actions

When you perform the preceding steps, Builder Xcessory:

· Generates all source code and files in the language you specified.

· Tells your environment to begin a build through that environment's build manager or make tool.

· Reports the status of the build in the Browser message window.

Example

This example assumes you are using Builder Xcessory with DEC FUSE, Developer Magic, or Workshop, and you are ready to execute a build of your application in C. (The procedure is similar in other languages.)

To execute the build, follow these steps:

1. Select Code Generation Preferences from the Browser Options menu to display the Code Generation Preferences dialog.

2. Click on the Makefile tab.

3. Verify the parameters on the Makefile Customization dialog.

4. Select Make Application from the Browser Project menu.

While your application is building, any related messages are displayed in the message area of the DEC FUSE Builder, Developer Magic Build View, or Workshop MakeTool.

Example

This example assumes you are using Builder Xcessory without a development environment, and you are ready to execute a build of your application in C++. (The procedure is similar in other languages.)

To execute the build, follow these steps:

1. Select Tools Preferences from the Browser Options menu to display the Tools Customization dialog.

2. Click on the Debugger & Manager tab ( Debugger & Build Manager Tab on the Tools Customization Dialog ):

Debugger & Build Manager Tab on the Tools Customization Dialog

3. Select Use CenterLine Tools from the Debugger & Build Manager tab.

4. Select Code Generation Preferences from the Browser Options menu to display the Code Generation Preferences dialog.

5. Click on the Makefile tab ( Makefile Tab on the Language Settings Dialog ):

Makefile Tab on the Language Settings Dialog

6. Verify the C++ parameters on the Makefile tab.

7. Select Make Application from the Browser Project menu.

8. Use Code/ObjectCenter to manage the make.

While your application is building, messages are displayed in the Browser message area.

Using a Debugger

While you are developing your application, you can debug it at any time without leaving Builder Xcessory.

If you are using Builder Xcessory with SunSoft Workshop or Silicon Graphics Developer Magic, you can access that environment's debugging tool or a CenterLine debugger.

If you are using Builder Xcessory on HP-UX platforms, CenterLine is the only debugger available.

Example

This example assumes you are using Builder Xcessory with SunSoft Workshop, and you are ready to execute a build of your application in C++.

To execute the build, follow these steps:

1. Select Tools Preferences from the Browser Options menu to display the Tools Customization dialog:

Entering a new source control command

Use the following notation to enter a new source code control command:

%file[option_specification %s]

%overwrite[option_specification]

%version[option_specification %s]

%keep[option_specification]

%comments[option_specification %s]

Builder Xcessory will copy option_specification and add the text in %s when one of the above options is indicated from the Check In or Check Out dialogs.

Example

For example, you can specify a version string for a file in both the Check In or Check Out dialogs. How this string is passed to the source code control commands varies from system to system. Suppose the check out command for the source code control system you are using is check_out , and in order to specify a version to check out you would enter:

check_out -v "version_string"

In Builder Xcessory you would enter:

check_out %version[-v "%s"]

When Builder Xcessory attempts to check out a file, it looks for %version in the command string. If you have specified a version string in the dialog, Builder Xcessory will add the option you specified within the square brackets and replace the %s with the string entered in the Check Out dialog.

Checking a 
file out

To check a file out of source code control, follow these steps:

1. Select Check Out Source from the Browser Project menu to display the Check Out dialog:

Check Out Dialog

2. Set or remove any check out options you want.

You can choose one of the following options:

· Lock a file when you check it out

· Check out a read-only version

· Remove a lock that you have set

In addition, you can specify a version string number, or overwrite a read-write version of a file that is currently checked out.

3. Navigate through your directory structure in the Directories window of the dialog, if the directory you want is not already displayed.

4. Select the file you want to check out from the Files window in the dialog. The full pathname of the file you selected is now displayed in the Selection input field.

5. To check out the file, click on Apply .

Checking a 
file in

Once you have finished modifying a file, you will need to check the updated version back into your source code control system. To do so, follow these steps:

1. Select Check In Source from the Browser Project menu. This displays the Check In dialog, as shown in Check In Dialog .

Check In Dialog

2. Select the file name you want to check in from the list of files displayed.

3. Specify comments for your modifications in the comments field.

4. If you want to keep a read-only copy of the file, set the Keep File Copy toggle.

5. To check the file back in, click on Apply .

Example

This example assumes you are using Builder Xcessory without an external development environment, and you are ready to check a file out of SCCS, modify the file, and check it back into SCCS.

Selecting SCCS as the source code control system

To select SCCS as your source code control system, use the following steps:

1. Select Tools Preferences from the Browser Options menu.

2. In the Source Code Control option menu, choose Use SCCS .

3. Check that the commands displayed on this dialog are correct.

4. Dismiss the Tools Customization dialog.

Checking a file out of SCCS

To check a file out of SCCS, use the following steps:

1. Select Check Out Source from the Browser Project menu.

2. Set the Check Out Locked toggle on the Check Out dialog.

3. Set the Overwrite Existing File toggle on the Check Out dialog.

4. Navigate through your directory structure in the Directories window of the dialog, if the directory you want is not already displayed.

5. Select the file you want to check out from the Files window in the dialog.

6. To check the file out, click on Apply .

Checking a file in to SCCS

After modifying the file, use the following steps to check in back into SCCS:

1. Select Check In Source from the Browser Project menu.

2. Select the file name you want to check in from the list of files displayed.

3. Document the changes you have made to the file in the comments field.

4. To check the file back in, click on Apply .

Using a Memory-Access Error-Checking Tool

You can also specify a memory error-checking tool to use with your code.

Selecting an error-checking tool

To specify an error-checking tool, follow these steps:

1. Select Tools Preferences from the Browser Options menu to display the Tools Customization dialog.

2. Click on the Test Tools tab ( Test Tools Panel on the Tools Customization Dialog ):

Character set

A character set is the set of all the characters required to represent the words in the language.

Code set

A code set is the set of binary values required to represent the character set of a language.

ISO8859-1/ Latin-1

ISO8859-1 (also called Latin-1), which contains the ASCII codes, is the standard code set for the representation of English, as well as several other alphabetic languages.

Code sets correspond to various languages or areas. For example:

Types of problems

When internationalizing an application, there are three broad types of problem:

· File processing problems

How are characters encoded; how does your application deal with storage formats for dates, addresses, currency, and so on?

· Input problems

How are the characters of a complex character set (for example, ideographic sets) actually entered when it is impractical to construct a physical keyboard capable of representing every one of those characters?

· Output problems

How are characters of different languages displayed within the application, especially within the same text area?

Note: A Japanese version is available. Contact your ICS Sales Representative.

Application Coding

An I18N program must operate regardless of the encoding of the characters in the user's language. A program that ignores or truncates the eighth bit of every character (as some English-based applications do) will not work in Europe, which requires eight bits to represent accented characters. Similarly, an application that assumes that every character is eight bits long will not work in Japan, where there are many thousands of ideographic characters. In addition, you cannot assume a single character size, because Japanese commonly intermixes 16-bit Japanese characters with 8-bit Latin characters.

Adding Localization Calls to the Code

Xt support of internationalization is trivial in most applications: the only code required is a call to XtSetLanguageProc() just before the call to XtAppInitialize(). This one function call does all the set-up necessary for an Xt-based application. Some additional work is required if your application is to support internationalized text output or input (as explained in Input methods ).

Builder Xcessory makes the XtSetLanguageProc() function call in the code generated if you set the Initialize Localization Support toggle in the Code Generation Preferences dialog.

Localization support is always enabled in ViewKit applications.

 

Locales

A locale is the language environment determined by the application at run time. The X/Open Portability Guide, Issue 3 (XPG3)defines locale as a means of specifying three characteristics of a language environment that might be required for localization:

· Language

· Territory

· Code set

These elements are represented by many systems in the following format:

<language>_<TERRITORY> . <code set> .

For example, ja_JP.ujis is the representation for Japanese, as used in Japan with the UJIS code set.

Using locales

At start-up, the application must find the correct UID file in either the DECW$USER_DEFAULTS or DECW$SYSTEM_DEFAULTS directories. See the DECwindows Motif Release Notes for more information.

As an example of using locales, assume you have an application with two different language versions. You set yourXUSERFILESEARCHPATH (see Static output ) to the following (all of which should appear on one line):

/usr/lib/X11/app-defaults/%l/%t/%c/%N:

/usr/lib/X11/app-defaults/%l/%t/%N:

/usr/lib/X11/app-defaults/%l/%N:

/usr/lib/X11/app-defaults/%L/%N:

/usr/lib/X11/app-defaults/%N

This search path allows your application to search from the most specific designation of the locale to the least specific, allowing you a high degree of flexibility in configuring your application. See the explanation of "XtResolvePathname" in Vol. 5 of the O'Reilly & Assoc. X Toolkit Intrinsics Reference Manual for an explanation of the various substitutions and how they relate to the locale designation.

Most vendors' implementations of X automatically include locale-specific searches in the default search path environment variables, so setting these variables is usually unnecessary.

Example

If you are using UIL for your application, you can use a similar mechanism to search for the compiled UIL (UID) files.

Set UIDPATH to the following (all of which should appear on one line):

<pathname>/%l/%t/%c/%U:<pathname>/%l/%t/%U:

<pathname>/%l/%U:<pathname>/%L/%U:

<pathname>/%U:

At start-up, the application finds the correct UID file based on how your UIDPATH is set. See the description of MrmOpenHierarchyin the 
OSF Motif 1.2 Programmer's Reference for further details.

Locales in Builder Xcessory

The application must have a way of recognizing the language environment in which it is running. Based on this information, the application can then make adjustments such as allowing the display of strings in the appropriate language. Builder Xcessory provides a code generation option to enable this support in your application.

---

Note: ViewKit applications always have localization support enabled by the VkApp object.

---

Enabling localization

To enable localization, follow these steps:

1. Select Code Generation Preferences from the Browser Options menu.

2. Click the Application tab on the Code Generation Preferences dialog ( Code Generation Preferences Dialog ).

3. Set the Initialize Localization Support toggle, and dismiss the dialog.

When the main C or C++ file is written, the following line is included:

(void) XtSetLanguageProc (NULL,

(XtLanguageProc)NULL,

NULL);

Builder Xcessory inserts code into the main routine to initialize the toolkit I18N features. When the code is compiled and run, the toolkit examines the LANG environment variable to determine the current locale, and then initialize its internal routines to deal with locale-specific issues.

For example, if the user has set the LANG environment variable to ja_JP . ujis , the application automatically initializes support for Japanese language character input and display, as well as monetary and date output, and so forth.

Code Generation Preferences Dialog

Setting locales

If the Initialize Localization Support toggle is not set, you can manually set the locale in your application using the ANSI C functionsetlocale . The function setlocale (LC_ALL,"") sets all locale-specific information to the default (the LANG environment variable). The function 
setlocale(LC_COLLATE,"ja_JP.ujis") sets only the collation order to that of the Japanese UJIS code set.

The function setlocale() is called from the default language procedure installed by XtSetLanguageProc() , described in detail in Asente, Converse, Swick's X Window System Toolkit . XtSetLanguageProc() also initializes the toolkit internationalization techniques, connects to the input method (if necessary), and sets various defaults for the current locale, as specified by the LANG environment variable.

---

Note: The default language procedure can be replaced using XtSetLanguageProc() with arguments other than NULL. Refer to O'Reilly & Associates' X Window System , Volumes 4 and 5 for a more detailed discussion of Xt language procedures.

---

Locale-friendly coding

When coding an application to be run in multiple locales, consider the following issues:

· Use ANSI C or C++; Kernigan & Ritchie 1 implementations may not support locale-aware string manipulation.

· Use strcoll() rather than strcmp() for string comparisons.
strcmp() routine assumes an ASCII character set when doing string comparisons; strcoll() has no such limitation and can deal with locale-specific character encoding and sorting order.

· Do not make assumptions about word order in strings, and do not make comparisons to specific, hardcoded, characters.

· Use strftime() rather than ctime() or asctime().
strftime() formats time and dates according to locale; both ctime() and asctime() are of limited flexibility.

· Use ctype(3) library routines to identify character ranges.

· Use wchar_t , rather than char as the type for string processing.
The char type allocates a fixed size (8 or 16 bit, depending on the architecture) for a character. This is not enough to hold the characters of some locales, particularly the idiographic languages. The wchar_t type allocates size sufficient to hold the largest character in the current locale. This can be grossly inefficient, so you should only use wchar_t for operations that index arrays of characters.

· Do not hardcode decimal separators in parsing or arithmetic operations. Some languages use a comma rather than a period for a decimal separator.

· Do not embed pixmap graphics in code; specific colors and graphics can have different meanings from locale to locale.

Placing Resource Values in Resource or UIL Files

Your application should not explicitly code any language-dependent information. 2 This includes strings, fonts, and language-dependent pixmaps. In order to do this, the Open Group (formerly OSF) suggests that these resources be placed in message catalogs, resource files or UIL files.

Builder Xcessory allows resources to be placed in resource files. Once a resource is set, you can choose (on an individual resource or resource class basis) whether that resource is set in the code or in a resource file.

Individually, this choice is made with the Resource Placement menu, to the right of the text field used to enter the resource value (seeResource Editor Placement Settings ).

Code

· Code indicates that the resource is hard-coded with calls to XtSetValues, and is the default.

App

· App indicates that the resource is placed in an app-defaults file, which can be edited to produce localized versions of the application.

Resource Editor Placement Settings

Resource values can also be placed in a resource file on a type basis by setting the resource's default resource placement. In the placement window, types can be specified to be put, by default, into Code or App (resource file).

Example

For example, if you want to place all compound strings and fonts into resource files, follow these steps:

1. Select Default Resource Placement from the Resource Editor Options menu to display the Default Resource Type dialog:

Default Resource Type Dialog

2. Scroll the dialog to find the Compound String and Font types, and set the App toggle for each (see Default Resource Type Settings).

Default Resource Type Settings

Generating Multiple UIL Files

Builder Xcessory also allows you to generate single or multiple UIL files, providing another language-independent way of specifying resource values that can be used to internationalize an application. To save resources in a UIL file, set the resource to be saved into code and when generating code, generate UIL instead of C or C++.

---

Note: You can only generate UIL files if generating an application in C (not in C++).

---

Once you generate a resource (or UIL) file, you must make copies of the file for each language supported and modify the contents accordingly. Then, using the locale of the machine and the environment variables LANG, UIDPATH, and XUSERFILESEARCHPATH, the different resource or UIL files are read and used by the application at run time.

For more information on this topic, refer to the OSF/Motif Programmer's Guide, Release 1.2, pages 11-26 to 11-31 and in the X Window System Toolkit, pages 433-436.

---

1. Kernigan, Brian & Ritchie, Dennis. The C Programming Language, 2nd ed. (Englewood Cliffs, NJ: Prentice Hall PTR, 1988).

2. OSF/Motif Programmer's Guide, Release 1.2, page 11-21; PTR Prentice Hall, Englewood Cliffs, New Jersey 07632

Text Input

An internationalized program must be able to display all the characters used in the user's language, and must allow the user to specify all those characters as input. When there are more characters in a language than there are keys on a keyboard, some sort of "input method" is required to convert multiple keystrokes to single characters.

Input methods

An input method is a mapping between keyboard input and the text data passed to the application. Such a mapping exists even within the familiar context of ISO8859-1 where, for example, the combination of the <Ctrl> or <Alt> key and a letter translates into a letter with a special accent mark: ü, é, and so forth.

---

Note: Within the 7- bit ASCII characters, there are no accented characters. However, ISO8859-1 is a superset of ASCII extending the code set to 8 bits, and includes accented characters and symbols.

---

The concept of an input method is especially important for ideographic languages. Review Chapter 11 of the OSF/Motif Programmer's Guide , Release 1.2 for a detailed discussion of the different aspects of input methods and how they are supported by Motif.

Motif support of input methods

Builder Xcessory assumes that you have access to an input method. Input methods are available in Motif 1.2. Prior to Motif 1.2 and X11R5, input methods were proprietary additions, and no standard existed. Builder Xcessory supports the use of X11R5-style input methods exclusively.

Using input methods

Input methods allow your users to enter text in their native language. There are several input methods available from hardware vendors and third party software vendors. The X source code distribution also includes a few sample implementations. They run as separate processes alongside the internationalized applications.

---

Note: Multiple input methods can run simultaneously for any number of internationalized applications.

---

Integrating with an input method

To allow your application to use a currently running input method, follow these steps:

1. Make sure that your locale is set correctly. Many platforms have dialogs to simplify this process, but usually setting the LANG environment variable is sufficient.

2. Make certain your application calls XtSetLanguageProc() before it calls XtAppInitialize(). This ensures that X/Motif localization support is properly initialized.

3. Create an application defaults file for your application that sets the font list resources to the font set appropriate for your locale.

4. Start your application.

The input method, with the locale set and the correct X11R5 calls in your application, communicates with your application automatically.

Text Output

An internationalized application displays all text in the user's chosen language. This includes prompts, error messages, and text on buttons, menus, and other widgets. The simplest approach to this requirement is to remove all strings that are to be displayed from the source code of the application and store them in a file that will be read when the application starts up. That file can then be translated into various languages, with the appropriate version being read at start-up.

In addition, an internationalized application must display times, dates, numbers, and so on, in the format that the user expects. For example, Americans expect dates in the form month/day/year, English expect day/month/year, and Germans expect day.month.year.

Setting Up Localized Output

Most languages use words from different languages and some require the word's native character set to be used. For example, a Japanese application might require error messages with a mix of Hirigana, Katakana, and Kanji characters, as well as some technical terms that require a Latin character set. This means that in one string there could be 5 words using Kanji characters and one word using Latin characters, requiring 2 different fonts.

---

Note: It is possible to display characters of multiple character sets within the same output string using compound strings and font lists.

---

Compound Strings

A compound string is a byte stream in ASN.1 encoding, consisting of tag-length-value segments.

Motif uses compound strings in many widgets. A compound string is used to set labels on label and button widgets as well as the contents of lists in Motif. These compound strings hold all information related to a string, including the text, direction and font used to display the string.

Compound string components

A compound string can contain the following components:

· Text of the string

· Separators (or line breaks)

· Font list tags

· Direction identifiers

Compound String Editor

The Compound String Editor allows strings to have multiple fonts and direction, and allows for a connection to an X input method. For more information on the Compound String Editor, refer to Compound String Editor .

Motif does not supply a String-to- XmString converter that understands font list tags or direction information. Builder Xcessory provides a String-to-XmString converter in the bxutils file, which supports Builder Xcessory style ASCII representations of compound strings.

Template code

The template code for the converter is in the file:

{BX}/xcessory/gen/common/bxutils.c

ASCII compound string format

The ASCII compound string format is:

:: [#tag][:t][:r]["xxxxx"]

where:

tag is font tag (or charset).

:t is set when a separator is requested.

:r is set when the string is displayed from right to left.

"xxxxx" is the text portion of the string.

Creating Multifont and Multidirectional Strings

A font list is a resource type that can be a single font or a font set. Font sets were introduced in X11R5 and Motif 1.2 (as the XFontSet). A font set is treated as a single entry in a font list, but contains all the fonts required to display all the characters of a locale. Internal X, Motif, and C routines are used to encode the font information for displaying a given string.

Font List Editor

The Font List Editor in Builder Xcessory supports the specification of font sets as well as regular Fonts (see Font List Editor ). For more information on the Font List Editor, refer to Font List Editor .

Font List Editor

You create the different font sets and tag them, so that they can be used in defining multifont strings.

---

Note: A font set is defined by the locale in which the program is running. For example, a font set that works in a Korean locale will not work in a Japanese locale.

---

Each font set member can use a different encoding, family, size, and so forth, and there are no limits on how many fonts can be defined for a given font set.

Once a font set has been added to a font list, it can be used like any other entry in the list. Motif and X control how to use the various fonts in the font set.

bxutils file

Although Motif 1.2 supports multiple entry font lists containing both fonts and font sets, Motif does not supply a String-to- XmString converter that understands font list tags or direction information. Builder Xcessory provides such a converter in the bxutils file. This converter is installed in your application by a call to RegisterBxConverters(). The converter supports a special textual representation of all the information encoded in a compound string: font tag, direction, etc. This allows you to quickly create multifont and multidirectional strings and use them with the Motif widget set, even though they are not supported in Motif 1.2. This code is completely portable and OS independent.

Generating Localized Files

The following sections discuss the generation of files for an internationalized application. Static and dynamic output are considered for both UIL and C/C++ generation. In static output, strings are created when the source code is generated. In dynamic output, strings are incorporated at run time by reference to a separate source.

Generating UIL

Static and dynamic output

Static and dynamic output are handled in the same manner when generating UIL. Typically, App-defaults files are not used. Instead, the application maintains a list of messages in a separate UIL file for each locale. When the application is built, the appropriate UIL is compiled into a UID and then used.

Use the Constant Manager and File Manager to create each of the locale-specific UIL files:

· Code all output (for example, warning, error, and informational messages) as constants.

· Set the file placement for this output to the appropriate UIL file. The application then fetches the value of the constant from the UID at run time.

Generating C and C++

Your application handles static and dynamic output differently in C/C++.

Static output

When generating C/C++, save Strings and XmStrings, as well as other locale-specific information such as fonts and colors, in app-defaults. To do this, you can take advantage of the X environment variables XFILESEARCHPATH andXUSERFILESEARCHPATH.

The following table lists the substitutions X and Motif allow in these paths:

Platform	Substitution	Description
X	%N	Value of the filename parameter, or the application's class name if filename is NULL
	%T	Value of the type parameter
	%S	Value of the suffix parameter
	%L	Language string associated with the specified display
	%l	Language part of the display's string
	%t	Territory part of the display's string
	%c	Code set part of the display's string
Motif	%U	Value of the UID filename parameter

See the section "Finding File Names" in X Window System Toolkit by Paul J. Asente and Ralph R. Swick (p. 860 in ISBN 1-55558-051-3) for further details.

Dynamic output

If you plan to use C or C++ instead of UIL to handle string output, write your application so that dynamic output uses a message catalog. A message catalog is a method for storing and fetching strings to/from external sources.

Message catalog options

You have three options for a message catalog:

· Use the MNLS standard

· Use the XPG standard

· Design your own

---

Note: To use one of the first two methods, your operating system must support it. Different operating systems require different storage locations for the catalog.

---

Designing Your Own Message Catalog

Designing your own message catalog is your only choice if you plan to run on a set of operating systems that do not share a common standard.

Example

The following procedure is one of many ways of designing your message catalog:

1. Use the Berkeley DBM library, which, given a key or a tag string, fetches the corresponding message string.

2. Represent the tag string in Builder Xcessory as constants.

3. Use the DBM string fetching routines, passing the tag string and a default message string as parameters. If the lookup of the message catalog yields no match for the tag string, display the default message string.

Suggested Reading

There are many considerations when designing an internationalized application. The following documents are useful references for I18N design issues:

· OSF/Motif Programmer's Guide, pp. 11-21. Prentice-Hall, 1993. 
(ISBN 0-13-643107-0)

· O'Donnell, Sandra Martin. Programming for the World: A Guide to Internationalization. Prentice Hall, 1994. (ISBN 0-13-722190-8)

· Scheifler, Robert W. and James Gettys. X Window System-Extension Libraries. Digital Press, 1997. (ISBN 1-55558-146-3)

· X/Open Portability Guide . 3rd ed. Prentice Hall, 1989. (ISBN 0-13-685868-6)

· Tuthill, Bill and David Smallberg. Creating Worldwide Software: Solaris International Developer's Guide. Prentice Hall, 1997. (ISBN 0-13-031063-8)

· Aldersey-Williams, Hugh. Nationalism and Globalism in Design . Rizzoli International Publications, 1992. (ISBN 0-84-781461-0)

· Nye, Adrian. Xlib Programming Manual . 3rd ed. O'Reilly and Associates, 1992. Volume 1 in the O'Reilly X Series. (ISBN 1-56-592002-3)

· Nye, Adrian and Tim O'Reilly. X Toolkit Intrinsics Programming Manual, Motif Edition. O'Reilly and Associates, 1992. Volume 4 in the O'Reilly X Series. (ISBN 1-56-592013-9)

· Heller, Dan and Paula M. Ferguson. Motif Programming Manual. 2nd ed. O'Reilly and Associates, 1994. Volume 6A in the O'Reilly X Series. (ISBN 1-56-592016-3)

· Asente, Paul, Donna Converse, and Ralph Swick. X Window System Toolkit. Digital Press, 1997. (ISBN 1-55558-178-1)

When you align a set of selected objects, you line up one edge or the center of the selected objects with that of some reference object. For example, to make a horizontal left alignment is to line up the left edges of all selected objects with the left edge of the object located farthest to the left on the interface. The selected objects are moved so that the left edge of every object lines up with that of the left-most object.

When you distribute a set of objects, you space them evenly without moving the outermost objects. For example, to distribute horizontal centers is to space the horizontal centers of all selected objects equally between the center of the left-most object and the center of the right-most object.

When you choose Java as your code generation language, you can only directly move or align objects (with the mouse, the Alignment Editor, etc.) if you have selected No Layout (in source code terms, foo.setLayout(null); ) for the parent. In all other cases, the layout policies of the parent object dictate the size and placement of the object.

Note: Frequently, geometry management policies of an object's parent dictate the size of the object. In these cases, the mouse, the placement grid, and the alignment menus and editors are all ignored.

You can rapidly align any set of existing objects with Builder Xcessory using the Align item from the Browser Edit menu (and also the MB3 Quick Access menu).

1. Select the objects you want to align with one of the following methods:

· Search/Select Area in the Browser

· Shift-MB1 Drag to circle the objects in the Browser, or your interface

· Ctrl-MB1 to select or deselect individual objects

2. Select Align from the Browser Edit menu or MB3.

3. Select the desired alignment from the resulting menu.

· Left, Right, Top, Bottom, Horizontal Center, Vertical Center

· Alignment Editor

The Alignment Editor provides extensive control over the positions of your objects. You can both align and distribute your objects. The Alignment Editor also displays an example of your alignment and distribution options, allowing you to view the effects of your changes before you commit them.

Alignment Editor describes the elements of the Alignment Editor window:

The following sections describe other techniques for layouts.

Converting GIL-2 files to GIL-3

If you have GIL-2 files, you can convert them to GIL-3 by reading them into Devguide Version 3, and then saving them. To determine the version of your GIL file, examine the first line of the file, which contains the following characters:

;GIL-n

where n is the version number.

Setting GIL options

Select GIL Options from the Browser Options menu to display the GIL Options dialog:

GIL Options Dialog

The GIL Customization dialog allows you to set the following options:

Look and feel

Builder Xcessory attempts to match the GIL file to either a Motif or an OPEN LOOK appearance and behavior.

Reposition

When set to Yes, Builder Xcessory attempts to lay out the interface based on the size changes encountered in the Motif versions of OPEN LOOK objects.

Matching interface geometry

The Motif versions of OPEN LOOK objects also alter the geometry of the GIL interface. The GIL Options dialog allows you to specify whether Builder Xcessory should try to lay out the interface based on the size changes.

Inserting Motif manager widgets

Both options are likely to result in some overlapping or misaligned objects, but you can easily reposition the objects from within Builder Xcessory. In many cases, the best way to align and position objects is to insert managers such as Forms and RowColumns into the hierarchy. A good understanding of how the different Motif managers work is necessary.

Editing class names

For the cases in which you do not want the groups mapped to a Motif BulletinBoard, you can edit the Class Name field in the Resource Editor and change the group's Class Name. Also change the instance name to reflect the new Class name or the object's function in the interface.

Inserting form widget parents

When the interface is imported, group anchors (attachments to other groups or objects) are ignored. In many cases, you will want to create a Motif Form widget as the parent of the group and set the attachments on the form widget's children to handle resizing properly.

Installing utilities

Builder Xcessory uses the following two PBM-Plus utilities:

· icontopbm

· pbmtoxbm .

These utilities are installed in the Builder Xcessory bin directory, which must be in your path. If Builder Xcessory cannot findicontopbm and pbmtoxbm , it displays a warning message.