BX PRO 5 Getting Started

Builder Xcessory Overview

Builder Xcessory is a WYSIWYG ("what you see is what you get") visual development environment for user interfaces. Builder Xcessory has an extensible palette of user interface (UI) objects with which you construct your interface, and includes the following features:

· Generates source code in the high-level programming languages UIL, C, C++, ViewKit, and Java.

· Integrates with your existing development environment. You can use SunSoft Workshop, SGI Developer Magic, DEC FUSE, or stand-alone components such as Purify, ClearCASE, XRunner, CodeCenter, ObjectCenter, RCS, or SCCS.

Direct manipulation

Using Builder Xcessory, you interactively create your application's graphical user interface using Motif widgets, ViewKit Components,user-defined components, or Java classes. With Builder Xcessory, you directly manipulate your interface. For example, to resize a pushbutton, select the pushbutton with the mouse and stretch it. If you want to move the pushbutton, select it with the mouse and move it.

Builder Xcessory also has specialized editors to simplify working with the various Motif and Java layout objects by visually representing abstract constraints, attachments, and records. You can directly manipulate these layouts. For example, to connect the resize behavior of a pushbutton to the size of its parent window, select the pushbutton attachment with the mouse and drag it to the edge of the container. When you change an object's attributes, whether it's a layout record or a background color, you see the result immediately.

High-level object reuse

Builder Xcessory takes advantage of the object-oriented nature of today's user interface systems, Motif and Java AWT. While you develop your interface, Builder Xcessory helps you create high-level UI objects to store, share, and reuse .

Rather than building an interface from pushbuttons and scrollbars, you work toward building your application from dialogs and screens. Builder Xcessory simplifies creation of new UI classes and saves them in locations accessible to all developers in your group and in your organization. You can extend these classes by subclassing.

Starting Builder Xcessory

After installing Builder Xcessory on your system, enter the following command at the command line:

% {BX}/bin/bx50

where {BX} is the directory where you installed Builder Xcessory.

If your system administrator copied the bx50 script to another location, enter the following command at the command line:

% bx50

Note: Refer to the BX PRO Installation Notes for complete installation instructions.

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).

Closing the Startup Panel

Once Builder Xcessory is loaded, the Builder Xcessory main windows are displayed, with the Startup Panel in the foreground. Click on the Next Tip button to read more tips, or click on Dismiss to close the window.

Dismissing the Startup Panel automatically

To dismiss the Startup Panel automatically when the system is ready, enable the Auto Dismiss Startup Panel toggle on the Behavior tab of the Browser User Preferences dialog.


Note: In your first Builder Xcessory session, the "Next Tip" button is not active until Builder Xcessory finishes loading and you select a default language. See the next section, Language Dialog for more information.

Language Dialog

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

Language Dialog

Selecting a default language

You must select a default language before proceeding. The language you select determines the available UI objects and the contents of the Builder Xcessory menus and dialogs. The language is saved in your .bxrc file, and becomes the default language for subsequent Builder Xcessory sessions.

You can change the language for each application, or change the default language at any time by selecting Choose A Language from the Browser Options menu. See Choose A Language for more information.

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.

 

Documentation: