User Interface
TOC PREV NEXT INDEX

2 Cross-Platform Compatibility and Third-Party UI Widgets

This section contains information regarding details of the User Interface Kit that will help programmers who are developing applications that require GUI consistency.

Achieving such consistency across all supported UNIX-based platforms is relatively straightforward because they all use X11/Motif widgets. However, moving user interfaces developed on these systems to a PC/Windows system requires knowledge of the incompatibilities of the behavior of certain modules in the different environments.

This section also describes how to import third-party widgets into AVS/Express.

It includes:

2.1 Cross-Platform User Interface Compatibility

This section discusses:

Differences Between Motif and PC Widget Sets

When designing a User Interface for an application that is to be implemented on multiple platforms, you must aim to achieve consistency of

Functional consistency means that the set of user operations with the GUI are consistent on all platforms. Look and feel consistency means that the appearance of the GUI and the flow of user interactions with the GUI are the same on all platforms. Both aspects must be present for the product to be cross-platform compatible.

Functional Differences

Functional differences are fewer than look and feel differences between the PC/Windows and X11/Motif systems but may have a greater affect and are more difficult to work around for the developer/end-user. This section details the functional differences between the widget sets.

Differences in Behavior

The following table summarizes the behavior differences in the current UI widget sets for the PC/Windows and X11/Motif systems. If a User Interface Kit module is not listed in the table, assume that its function is the same across PC/Windows and X11/Motif systems.

Table B-1
User Interface Modules
PC/Windows System
X11/Motif System
UIapp
No remote display capability
 
UIcmd
No multiple instance capability
 
UIcomboBox
 
Does not exist
UIdial
No direct keyboard interface
 
UIonePoint
Control<BtnLDown>
Control<Btn1Down>
UIoption
No multiple instance capability
 
UIOptionMenu
Does not exist
 
UIprintDialog
 
Does not exist
UIshell
No remote display capability
display attribute has no effect
 
UItemplateDialog
 
Must use UIpanel between UItemplateDialog and other objects added to dialog.
UItext
No cut and paste
No paste into UItext field.
UItwoPoint
<ButtonLDown >
<ButtonLMotion>
<ButtonLUp>
<Button1Down>
<Button1Motion>
<Button1Up>
PrintViewer
No Graphics Printing
Prints to Printer
 
Prints to File

Missing Functionality

The following lists the functionality that is missing from AVS/Express or that differs on the PC/Windows and X11/Motif platforms.

Missing Widgets

The following lists the widgets that are missing from the implementation.

Look and Feel

Differences in look and feel are the most obvious between the PC/Windows and X11/Motif versions of the User Interface Kit. The following table summarizes these inconsistencies. If a User Interface Kit module is not listed in the table, assume that its function is the same across PC/Windows and X11/Motif platforms.

Table B-2
User Interface Modules
PC/Windows System
X11/Motif System
UIapp
Panel always includes space for the status bar at the bottom, even if no status string is set.
Space for the status bar is only allocated in the panel if a status string is set. The status bar may differ in size depending on the window manager in use.
UIbutton
Background pixmap is obscured by label
 
UIcmd
No accelerators
Accelerators are available only on menu bar pull-down commands.
UIcolor (base type)
Need different color name strings
 
UIcomboBox
 
Does not exist
UIdial
Different look and feel details
 
UIfield
4 pixels shorter than Motif
 
UIfileDialog
Different GUI
 
UIframe
Frame always 3 pixels wide
Any size allowed
UIframeEtchedIn
Same appearance as UIframeEtchedOut
 
UIframeEtchedOut
Same appearance as UIframeEtchedIn
 
UIhelpCmdList
Does not position in top right menu
 
UIlabel
String defaults to left justification
String defaults to center
UIlist
Default height smaller
 
UImultiSelBox
Smaller shell size default
 
UIoption
No accelerator labels
There is a larger spacing between items in the options list than on PC/Windows.
UIoptionBox
X in boxes = on
Pressed-in buttons = on
UIoptionMenu
Does not exist
 
UIpanel
Background pixmap covers all other children objects
 
UIradioBox
Circles with dots = on
Pressed-in buttons = on
UIslider
Label at top left, value text is fixed at top right
Label at bottom left, value text moves with slider
Label height pixels thicker than PC
UItext
Background white
Background same as parent
UItoggle
No foreground or background colors, check in box = on
Different default size,
button pressed in = on
Print Viewer
Different GUI layout
Different GUI layout

Other Differences

Window Sizes

Many widgets default to different sizes initially due in part to constraints of child widgets and the presence or absence of different window managers. Even across UNIX platforms, each system tends to run its own window manager.

Color Mapping

Specifying color text names does not result in the generation of the same color on screen. This is especially true from X11/Motif to PC/Windows systems but can also be subtly different across X11/Motif systems since AVS does not use the CMS color specifications.

Mouse/Keyboard Interaction

There are physically different mouse buttons and keyboard controls, which force a difference in the look and feel between PC/Windows and X11/Motif systems. Also, style specifications in the Windows style guide differ from the Motif style guide.

Workarounds

The most commonly used solution to cross-platform compatibility is the conditional compilation of V-code files based on a defined platform type. This consists of defining code sections with different values for each platform type. This solution is straightforward but requires much prototyping, testing, and debugging.

A slightly more evolved solution is to define a library of cross-platform pre-tested objects for use in further development.

2.2 Importing Third-Party User Interface Widgets

This section discusses:

Overview

You can import third-party widgets into AVS/Express by performing the following steps:

1. implement the V-code object
2. generate the class interface
3. implement methods for the new class
4. compile the project
5. test the new widget

This section illustrates how to integrate a specific widget into AVS/Express. Reading it will give you a general understanding of how to import widgets, but the exact steps of the example are only valid for X11/Motif and UNIX versions of AVS/Express. If you have FTP access to the internet, you can also download and try this example yourself from the AVS FTP server (ftp.avs.com). Here, the compressed tar file, matrix.tar.Z is located in /pub/express/training.

The widget that is to be imported is the XbaeMatrix table (matrix) widget. This widget, which is publicly available from the X Consortium FTP Site (ftp.x.org), is a useful addition to the native widget set. After importing it, you should be able to integrate any third-party widget (or other code) into AVS/Express.

Note: A compressed tar file of the AVS/Express Project directory matrix, which is available via either the AVS Web page or the AVS FTP server, contains all of the code required for this example. See the AVS/Express FTP site for the latest example files.

Implementing the V-code Object

The V-code object represents the public interface to the widget from the AVS/Express Object Manager view. Various resources of the widget may be exposed for get and set operations. Synthetic resources that extend the basic widget functionality may be added.

The UImatrix object inherits its basic functionality from the UIprimitive class. The V code for the UImatrix class is as follows:

                       UIprimitive UImatrix<src_file="src/matrix.cxx",link_files="-lXbae"> {

                           /* Set UIprimitive attributes for width and height */
                           width  = 200;
                           height = 200;

                           /* Add UImatrix specific attributes */
                           int rows;                          /* Number of rows in the matrix */
                           int columns;                       /* Number of columns in the matrix */
                           int columnWidths[] = {5};          /* Array of column widths */
                           int+nonotify stringdims => array_size(strings);    /* Size of string array */
                           string strings<NEportLevels={2,0}>[];    /* Array of cell entries */
                           string colLabels[];                /* Array of strings for column labels */
                           string rowLabels[];                /* Array of strings for row labels */

                           /* Attributes set by some action or event on the widget */
                           int+nonotify selectedRow;          /* Row number of selected cell */
                           int+nonotify selectedColumn;       /* Column number of selected cell */
                           string+nonotify selectedString;    /* String content of selected cell */

                           /* Creation and update method definitions */
                           method+notify_inst inst<NEvisible=0,lang="cxx",interruptable=0> = "UImatrixInstance";
                           method+notify_val update<NEvisible=0,lang="cxx",interruptable=0> = "UImatrixUpdate";
                       };

Note: The file UImatrix.v contains this source code. It is available via either the AVS Web page or the AVS FTP server.

Generating the Class Interface

The V code in UImatrix.v represents the UImatrix object in AVS/Express. You must also provide a representation of the class in the User Interface C++ class hierarchy. You can generate code that provides the virtual functions for this class either using the OMX code generator or by hand.

The UIimport class definition is located in the file unsupp/UIimport/ui/import.h in the installed AVS/Express directory. You can also download the import.h file via either the AVS Web page or the AVS FTP server.

All classes that inherit from UIimport must provide their own instances of the instanceObject() virtual function because this is a pure virtual function in the UIimport class. The UImatrix class also provides its own instances of the UIimport class virtual functions updateObject and destroyObject. Most derived classes will need to do this also. The following hand-generated code inherits from the UIimport class interface.

class UImatrix: public UIimport {

    public:
        UImatrix( OMobj_id );
        ~UImatrix();

        virtual Boolean instanceObject( OMobj_id );
        virtual void updateObject( OMobj_id );
        virtual void destroyObject( OMobj_id );

        static void selectCB(  Widget, UImatrix *,
                              XbaeMatrixSelectCellCallbackStruct *);

        // returns UIclass type info for upcast verification
        virtual ClassType classType() { return( "UImatrix" ); }

    private:
        void loadMatrix();
        void loadColWidths();
        void setColLabels();
        void setRowLabels();
        short *colWidths;
        String *colLabels;
        String *rowLabels;
        int num_rows, num_columns;
        int old_nrows, old_ncolumns;
};
Note: The implementation file matrix.cxx contains this UIimport class interface. It is available via either the AVS Web page or the AVS FTP server.

Implementing Methods for the New Class

In order to implement methods for the new UIimport class, you provide code that "glues" them to the functions that create, update, and destroy the imported widget.

The functions that you must implement include three virtual functions, a callback function, and a number of private functions, as specified in the following table:

Table B-1
Function type
Function
Virtual
virtual Boolean instanceObject( OMobj_id );
virtual void updateObject( OMobj_id );
virtual void destroyObject( OMobj_id );
Callback
static void selectCB( Widget, UImatrix *,      XbaeMatrixSelectCellCallbackStruct *);
Private
void loadMatrix();
void loadColWidths();
void setColLabels();
void setRowLabels();

Note: These functions are implemented in the file matrix.cxx. It is available via either the AVS Web page or the AVS FTP server.

Compiling the Project

You use the AVS/Express Compile Project mechanism to add the widget code to the AVS/Express executable. After you create the V-code object and the C++ class and implementation files, you must compile and link them with the main AVS/Express executable so that you can instance and use the new object. To do this, perform the following steps:

1. Uncompress and untar the file matrix.tar.Z and change to the directory where it is installed on your system. (This file is available via either the AVS Web page or the AVS FTP server.)
2. In your shell, verify that the MACHINE environment variable is set to the correct value for your particular platform.
3. Modify the file avsenv in the matrix project directory to reflect the correct path for the directory on your machine.
4. In the matrix project directory, start AVS/Express.
5. Load your new V code for the UImatrix widget UImatrix.v with the Load Objects command on the Objects menu.
6. Change to the Library Workspaces page and place the UImatrix object in the Express Functions library.
7. Select the Express Functions folder and pull down the Projects menu on the Main menu bar.
8. Select the Compile command and wait while AVS/Express generates the Makefiles and source files that it needs to recompile itself. AVS/Express will pop up a dialog box saying that it cannot compile itself while it is running.
9. Exit AVS/Express.
10. Recompile and relink AVS/Express by typing the following command at the UNIX shell prompt:
make -f express.mk
11. Restart AVS/Express in the matrix project directory by typing the following command:
bin/$MACHINE/express

Testing the New Widget

Test the new widget as follows:

1. Run the new AVS/Express executable, bin/$MACHINE/express.
2. Check out your new widget by instancing the object in the ModuleStack Workspace and connecting it to a UIshell or UIapp parent.
3. Load the example V code, matrix_region3.v, which demonstrates using the matrix widget to display the color values of a selected region. (This file is available via either the AVS Web page or the AVS FTP server.)

TOC PREV NEXT INDEX