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

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

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

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.

---

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

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)

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

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 .

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

---