View3D Programming Guide

Software Version Information

Builder Xcessory uses the following software versions:

• X Window System Version 11 Release 5
• OSF/Motif 1.2.x (or equivalent)
• FLEXlm 3.0 License Manager

Builder Xcessory Documentation

The Builder Xcessory documentation set includes the following manuals:

• BX PRO 5.0 Installation Notes

  Describes the installation scripts and how to integrate Builder Xcessory with your configuration.

• BX PRO 5.0 Release Notes (this document)

  Describes version-specific notes.

• Builder Xcessory 5.0 User's Guide

  Describes the basic problems encountered when building an interface, demonstrating how to use Builder Xcessory to solve these problems.

• Builder Xcessory 5.0 Reference Manual

  Describes Builder Xcessory features, reviewing each main window, menu, manager and editor.

• Customizing Builder Xcessory

  Describes how to customize and extend Builder Xcessory to handle new widgets and component classes, different Resource Editors, and your own callback functions.

New Features in 
Builder Xcessory 5.0

Builder Xcessory 5.0 focuses on ViewKit integration and improved handling of user-defined components. This release allows you to access a large number of components and develop new classes that can easily be shared with other developers in your organization.

Design Changes and Improvements

Four major areas of redesign

The new features of Builder Xcessory 5.0 streamline the process of creating and using components. The following four major areas are affected by these design decisions:

• Builder Xcessory Palette

  The manner in which data is saved and displayed in the Palette has been completely redesigned in Builder Xcessory 5.0, so that you can easily add and manage large numbers of new components.

• Customizing Builder Xcessory

  On most platforms, both widgets and C++ components can now be added without recompiling Builder Xcessory.

• Builder Xcessory Class Member Editor

  The Class Member Editor has been significantly enhanced to be configurable from the normal Builder Xcessory initialization files.

• ViewKit Components on Palette

  Builder Xcessory 5.0 includes the ViewKit menu and dialog components on the Palette and significantly enhances ViewKit code generation.

Features and improvements

Builder Xcessory 5.0 includes the following features and improvements:

· Java 1.1 Support.

Builder Xcessory 5.0 supports the new AWT 1.1 delegation event model. Java applications generated with Builder Xcessory 4.0 will work with Builder Xcessory 5.0.

Note: Builder Xcessory 5.0 Java code generation is limited to the AWT components provided. Builder Xcessory does not support adding new Java components or JavaBeans.

• Cleaner presentation of methods and instance variables in the
  Resource Editor.
• Support for the CDE widgets.
• Position and state (iconified, normal) of the principal Builder Xcessory windows are saved on exit.

Palette

In Builder Xcessory 5.0, the redesigned Palette allows you to add and manage large numbers of new components.

Interface

The following Palette user interface changes provide you with more control:

· You can have an unlimited number of groups in a Palette.

• You can nest Palette groups; closing a hierarchically higher group folder hides any lower-level folders.
• You can display more than one Palette, each with its own set of Widgets and Components.
• The tabbed view of the Palette now uses the ViewKit TabPanel component.
• You can switch between Outline view and Tabbed view at run time and on a Palette-by-Palette basis.
• Changing the size of the Palette window changes the layout of the displayed widgets and components within that window to accommodate the new size.
• You can edit all attributes of Palette components at run time using the various Properties dialogs.

Catalog file

The Palette now uses a catalog file to save its contents rather than the previously used Tcl file. The catalog file maintains the contents of a Palette as well as any constraints on the groups or items within a group. Your changes to the layout or content of a Palette are saved to a personal catalog. You can create catalog files by using the new Builder Xcessory Object Packager.

Customizing Builder Xcessory

Options for customizing Builder Xcessory have been expanded as follows:

• You can now add Xt widgets or C++ components without recompiling Builder Xcessory. Simply provide the necessary description files (WML, Collection, Pixmap) and a shared library that is loaded dynamically by Builder Xcessory when you create the first instance of an object. This method allows you to easily add new widgets and C++ components to the Builder Xcessory Palette.
• A new tool, the Builder Xcessory Object Packager, helps you add objects to the Builder Xcessory Palette and configure the Builder Xcessory control files.

Class Member Editor Enhanced

The Class Member Editor is now configurable from the normal Builder Xcessory initialization files:

• You now have access to all of the programming language attributes of your selected language. The attributes of a language are described in the language's data file used by Builder Xcessory during initialization.
• For languages that support it (such as C++), you can specify initialization values for static data members.
• For languages that support it (such as C++), you can specify default values for method parameters.

Additionally, the six lists used to display class members in previous versions of Builder Xcessory have been consolidated into one list that indicates a member's attributes as well as its name, type, and so on.

ViewKit Components on Palette

Builder Xcessory 5.0 includes the ViewKit menu and dialog components on the Palette and significantly enhances ViewKit code generation:

• Builder Xcessory 5.0 adds all the ViewKit 1.3 dialogs as well as support for all ViewKit menu items.
• ViewKit code generation has been optimized for ViewKit 1.3, making use of features of that release (such as support for Fallback Resources) and the use of other data classes from ViewKit (such as VkPeriodic and VkBackground objects).
• If you regenerate source code designed with previous versions of Builder Xcessory, the code generator converts any menu items to their ViewKit menu equivalents.

bxutils Functions Renamed

To reduce collisions with other libraries and code sources, all functions generated in bxutils-{language} are now prefixed with "BX_". All code generated with Builder Xcessory 5.0 will use these functions. If you have code compiled to use the older function names, add "-DDEFINE_OLD_BXUTILS" to your compile command. The old functions will be defined and call the new versions.

ANSI C Code Generation

In previous versions of Builder Xcessory, the Generate ANSI C option was off (Generate K & R C) by default. This option has been moved to the appropriate Code Generation Preferences dialogs and is on (Generate ANSI C) by default.

Settings of this option from previous versions of Builder Xcessory are not properly carried over to Builder Xcessory 5.0. When working with projects begun with older versions of Builder Xcessory, verify the Code Generation Preferences before generating code with Builder Xcessory 5.0.

Known Problems in
Builder Xcessory 5.0

The following sections describe known problems in Builder Xcessory 5.0. These problems will be corrected with the next release of Builder Xcessory.

Unmake Class on VkWindow

Builder Xcessory incorrectly allows you to "unmake class" on a VkWindow, causing indeterminate results during code generation.

Adding Menu Bar to VkSimpleWindow

Builder Xcessory incorrectly allows you to add a menu bar to VkSimpleWindow.

Naming Classes

Builder Xcessory does not prevent you from assigning your class the same name as a ViewKit or Java class.

Color Limitations

Builder Xcessory will not read pixmaps or icons containing more than ninety colors. If an icon or pixmap has more than ninety colors, Builder Xcessory displays an error message. Use other utilities, such as "xv", to perform color reduction on images that exceed the limitation.

Generating UIL Classes

Within a class, child widgets of a Form should not reference other child widgets for attachments. The UIL compiler does not make proper alignments for multiple instances of the class. This is a limitation of the UIL compiler. Other code generation languages are not affected.

Callbacks for Children of VkHelpPane

Builder Xcessory does not correctly generate code for callbacks of children of the VkHelpPane when the callback uses other than the default (NULL) client_data.

Resource Editor Text Field Parsing

Class member entries typed in the text field of the Resource Editor are not robustly parsed. Use the Class Member Editor to take advantage of all features.

Java Code Generation

The Java code generator shipped with this release is not the final version. An update to the code generator will be shipped shortly after the general release. Contact ICS Technical Support or your sales representative for more information.

Java Resources

Event handling

Event handling has changed in Java 1.1, particularly in naming conventions and the way of handling events. The event handling resources from Java 1.0.2 are available on the Resource Editor along with the new resources from Java 1.1.

If you read a UIL file from Builder Xcessory 4.0 into Builder Xcessory 5.0 and generate Java code, the code generated from Builder Xcessory 5.0 changes from 1.0.2 compliant code to 1.1 compliant code. The Java 1.0.2 resources are available in the Resource Editor for backward compatibility.

Equivalent resources

The following table lists the obsolete resources in Java 1.0.2 and their equivalent resources in Java 1.1:

actionEvent equivalents

The actionEvent resource in Java 1.0.2 has different equivalents in Java 1.1 for different components:

New AWT Components

The Builder Xcessory Palette now includes the components Java AWT components ScrollPane and PopupMenu.

Label Component Limitation

The AWT Label component does not support multiline labels. Although Builder Xcessory allows you to apply a multiline label and displays it correctly, the generated code does not produce a multiline label.

Adding Events to a Java Dialog

To add events to a Java Dialog, you must subclass the Dialog (you cannot directly instantiate the Dialog class). Builder Xcessory automatically subclasses the AwtDialog.

Java Menus

Builder Xcessory allows you to create Java applications, including those with a menu system. However, Builder Xcessory does not make certain restrictions on the creation of the application interface that are enforced by the AWT objects and toolkit. It is therefore possible to create a menu system that is not considered valid in AWT usage.

Creating AWT applications

To create a valid AWT application, observe the following conventions:

· AwtMenuBar should be a child of AwtFrame only, not of other containers.

• AwtMenu should be a child of AwtMenuBar only.
• AwtMenuItem, AwtCheckboxMenuItem, and AwtMenuSeparator should be created as children of AwtMenu (pane), or of AwtPopupMenu only, and as separate top-level objects.

Notes for All Platforms

The following sections describe general notes for all platforms.

Java MB3

In Java, you cannot use MB3 for dialog placement. To display a dialog, select the Dialog or FileDialog object from the Palette.

Focus Model

Because Builder Xcessory uses many windows, we suggest that you use a "follow-pointer" focus model (Mwm*focusPolicy: pointer) instead of a "click-to-focus" model (Mwm*focusPolicy: explicit). The "click-to-focus" model might cause windows to be raised inconveniently.

Placement Grid

The placement grid is not visible, but you can change the placement grid configuration. Refer to the section "Snap To Grid" in theBuilder Xcessory Reference Manual for more detailed information.

Shrinking Panner

On very large interfaces, the Browser panner disappears because the size of the panner reflects the percentage of the interface seen in the Browser. Resizing the Browser or the panner canvas makes the panner visible again. Alternatively, click MB1 inside the panner canvas and drag the pointer to move the visible portion of the interface hierarchy inside the porthole.

Note: You can also traverse to the panner and use the arrow keys to pan.

XIO Errors

Resizing the Browser message window until it is completely obscured or takes up the entire Browser window results in an XIO Error. A message is printed in the message window. This XIO Error does not affect the operation of Builder Xcessory or the current interface, and you may safely ignore the error.

Notes for SGI IRIX

On SGI systems, you can run Builder Xcessory 5.0 with either the OpenGL-based GlwMDrawingArea widget or the IRIS GL-based GlxMDraw widget.

Using BX with OpenGL

To start Builder Xcessory with the OpenGL widget, use the "-openGL" switch on the command line:

% bx50 -openGL

Note: Your GL widget selection is saved from session to session.

---

CodeCenter and ObjectCenter

Version Support

Builder Xcessory supports CodeCenter 4.x and ObjectCenter 2.x for Solaris 1.x, Solaris 2.x, and HP-UX 9.0.x.

clms_registry

CodeCenter version 4.x (ObjectCenter 2.x) includes the communication server clms_registry, which should be installed during the normal CodeCenter installation. This program must be running in order for Builder Xcessory and CodeCenter to communicate.

Note: Problems running CodeCenter from Builder Xcessory are likely due to the Builder Xcessory execution of CodeCenter. To work around this, start CodeCenter on the same machine from another xterm (exiting Builder Xcessory is unnecessary), and connect to it from Builder Xcessory.

Notes for EPak PRO 3.0.1 and EnhancementPak 3.0.1

Support for HP-UX 11

EPak PRO 3.0.1 and EnhancementPak 3.0.1 support HP-UX 11 users. On page 8 of the EPak PRO 3.0 Installation Notes, the table in Step 1 does not include HP-UX 11 in the Platform column. The table should read as follows:

Documentation Errata

1. Change directories to the mount directory. For example, if the CD is mounted in /cdrom, enter the appropriate command for your platform at the prompt(%):

   Platform	Command
   SunOS 4.1.x Solaris 2.0, 2.1, 2.2 HP-UX 9.05+ OSF1 3.x, 4.x AIX 4.1	% cd /cdrom
   Solaris 2.3 or later	% cd /cdrom/epak30
   IRIX 5.x or 6.x	% cd /CDROM