XView Libraries

Terminology The XView toolkit, and the OLIT and Motif toolkits use some of the following terminology:

XView	OLIT and Motif
Package	Widget
Attributes	Resources

XView is based directly on Xlib, whereas Motif and OLIT are Intrinsic based toolkits that are based on the Xt Intrinsics layer. The Intrinsics layer is based on Xlib.

XView	OLIT	Motif
Xlib	Xt	Xt
	Xlib	Xlib

Because of this fundamental difference, the basic library functions to initialize the environment, create, modify and destroy graphical objects are different, as shown in the following examples:

XView	OLIT/Motif/Xt
xv_init()	XtAppinitialize()
xv_create()	XtCreateWidget()
xv_set()	XtSetValues()
xv_destroy()	XtDestroyWidget()

Functions that deal with event handling callbacks, and internationalization features, for example, get more complicated. For these features, simple correspondence does not exist.

Architecture

OLIT and Motif are Xt based toolkits that have very similar architectures. XView is not an Xt based toolkit and its architecture differs from the previously mentioned toolkits. When migrating form XView to Motif, you should note these toolkit differences.

The XView toolkit implements both the UI objects, called packages, and the routines and processes that hold the interface together (creation routines, event-processing), while Motif and OLIT implement basically just the UI object, widgets, leaving the routines and processes to the Intrinsics library.

The three toolkits represent two different GUIs. The appearance of the XView and OLIT toolkits are similar whereas the appearance of Motif 1.2.3 is noticeably different. Although there is a rough one-to-one correspondence between the function calls in the libraries, the behavior of parallel programs is different. That is, even after an OLIT (or XView) program has been converted to use the Motif 1.2.3 library, it still, to some degree, has an OPEN LOOK appearance. A program in such a state does not adhere to either style completely.

First Considerations When Porting

Porting an OLIT application to Motif 1.2.3 is easier than porting an XView application, because OLIT and Motif 1.2.3 have similar APIs. However, a conversion from OLIT is not necessarily easy and can require restructuring the software.

Potential Complications

Porting software from OPEN LOOK to Motif 1.2.3 involves more than changing the names and arguments of function calls or pointing the linker to a new library. A conversion of this sort is more than a mere translation; moving to Motif entails some subtle changes in how the software operates.

For programs in which important functions are insulated from the surrounding GUI, the impact of this difference can be negligible. However, if the code is tightly linked to the user's actions or relies on a specific OPEN LOOK feature, it may be difficult to produce a Motif equivalent. In an extreme case, you must choose between violating the style guide or redesigning part of the program.

A simple example illustrates this point. Suppose, in a text-editor application, the user is allowed to edit several sections of a text buffer simultaneously. It is easy to implement this feature with an OPEN LOOK split view. However, split views are not part of the Motif specification. To produce the split view effect, you have to maintain extra buffers--or link several Text widgets to the same buffer using XmTextGetSource() and XmTextSetSource() calls.

To determine the amount of time involved in taking full advantage of Motif significantly depends on how the application is laid out. You can eliminate porting options by the application's design. Applications that are well designed are easier to port and easy to properly break down for maintenance, and readability.

Programming Model

Although the APIs are different, both XView and Motif are based on the same object-oriented method for programming a user interface:

• Initialize the toolkit
• Instantiate UI Objects
• Register Callbacks on the UI Objects
• Enter event-loop, waiting for user to generate events on the UI objects

The overall structure of a program being ported from XView to Motif can remain intact even though all the function calls must be converted from one API to the other.

Commonalities

Both XView and Motif are UI toolkits that support some common types of UI objects. However, XView implements many of these objects at a higher level that requires more than one Motif widget to get the equivalent of a single XView object.

The following table lists the basic mapping of common objects for XView and its equivalent Motif widget(s):

Table 2-1

XView Package	Equivalent Motif Widget(s)
Base Frame	TopLevelShell + MainWindow
Command Frame	DialogShell + BulletinBoard
Notice	DialogShell + MessageBox (MessageDialog)
Canvas	ScrolledWindow + DrawingArea
Panel	Bulletin Board
Panel Button	PushButton
Menu Button	CascadeButton
Abbrev Menu Button	OptionMenu
Checkbox	RowColumn + ToggleButtons (CheckBox)
Exclusive Choice	RadioBox
Scrolling List	List (Scrolled List)
Message	Label
Slider	Scale
Text Field	TextField
Numeric Text Field	None
Text SubWindow	ScrolledWindow Text + Text (ScrolledText)
TTY SubWindow	None
Scrollbar	ScrollBar
Popup Menu	MenuShell + RowColumn (Popup Menu)
Pulldown Menu	MenuShell + RowColumn (Pulldown Menu)
Pullright Menu	MenuShell + RowColumn (Pulldown Menu)
File Chooser	DialogShell + FileSelectionBox
Split Control	Motif Paned Window

Differences

XView abstracts a number of other X11 functions that Motif (Xt) does not. In order to get equivalent functionality in Motif, these must be re-coded with direct Xlib calls. A list of the XView packages with no Motif equivalents follows:

• Icon
• Font
• Server Image
• Colormap (CMS)
• Cursor
• Fullscreen
• Server

Additionally, no Motif equivalent exists for the OPEN LOOK function to split windows into different views. It should be noted that subclassing a Motif Manager widget to implement this function is not easy. You can use a combination of the Motif paned window and the Motif text widget to give similar, more primitive functions.

Some XView functions have Motif equivalent functions; however, the APIs are significantly different. A sample list of some of the functions follows:

XView API	Motif/Xt
Selection Service	Xt Selection API
Drop Target Package	Motif Drop and Drag API
Notifier	Xt Event Management API

X Resources and Command Line Options

The X resources that allow runtime customization of XView and Motif applications are different. XView objects may not have instance names attached to them. Motif/Xt do contain either class or instance names attached, for example, mainframe.control_panel.button1.foreground. To make Xt resources affect more than one object, use wildcards, for example, mainframe*foreground.

For more details on Motif/Xt resources, refer to some of the Xt books listed in Appendix B, "References."

OPEN LOOK versus Motif 1.2.3

When you compare an OPEN LOOK application with its Motif counterpart, a few contrasting visual elements are immediately apparent. The OPEN LOOK buttons are round, whereas the Motif buttons are square. The shading applied to buttons and other objects for a three-dimensional appearance are also different. Such cosmetic elements do not affect a program's behavior, however, and can often be disregarded when porting.

Several differences are often significant in a conversion effort. The most critical of these features and other GUI elements are summarized in three sections:

• Aspects of OPEN LOOK that are missing from Motif
• Aspects of Motif that do not appear in OPEN LOOK
• Features or other elements that appear in both specifications but are implemented differently

See Appendix B, "References," for a list of style guides and other references that describe the OPEN LOOK and Motif GUIs.

Features Only in OPEN LOOK

The following features are found in OPEN LOOK and are implemented in XView or OLIT (or both):

• Secondary text selections
• Scrollbar anchors
• Menu Defaults

  · Automatic default, short cut method for selecting a menu default

  · Default menu item indicated by a ring

• Font chooser widgets
• Pointer warping
• Minimized windows are valid drop areas
• tty subwindows
• Visual feedback on menu item selections
• Numeric text widgets

Features Only in Motif

The following features are found in only Motif:

• A fully-specified file selection mechanism
• Standard X clipboard cut and paste

Notable Implementation Differences Between User Interfaces

Many features are roughly equivalent in Motif and OPEN LOOK but have significant implementation differences. The following are the most important differences:

• Tear off menus
• Input focus indicators
• Widget classes (sliders and gauges versus scales, for example)

Other significant differences include the following:

• Keyboard bindings
• Window manager controls associated with each window
• Approach to implementing internationalization
• Interpretation of specific mouse actions

Tear-off Menus

In Motif, tear-off menus replace the pinned menus of OPEN LOOK. Select the dashed line on the top of the menu to tear off the menu.

Window Controls

When the Motif user presses the window Menu button in the upper left corner of the title bar, or the OPEN LOOK user presses the Menu button anywhere on the title bar, a window menu is displayed. The options offered under the two GUIs introduce an important contrast.

The Motif window menu offers a choice of Restore, Move, Size, Minimize, Maximize, Lower, and Close. The OPEN LOOK base window menu offers Close, Full Size, Properties, Back, Refresh, and Quit. The two lists are fundamentally the same, but have very different effects.

In OPEN LOOK, selecting the Close option minimizes the window, and Quit terminates the application.

In Motif, selecting the Minimize option minimizes the window, and selecting the Close option terminates the application. Many users familiar with OPEN LOOK have found themselves exiting a Motif program when their intent was to close it to an icon.

Mouse Button Behavior

The structure of the mouse buttons is very similar in both specifications; however, the difference is significant enough to cause some confusion.

Table 1 shows the default left-to-right mapping of the three OPEN LOOK buttons.

Table 1

Button	Description
SELECT	Specifies an object or manipulates objects and controls, drag
ADJUST	Extends or reduces the number of selected objects
MENU	Displays a menu associated with the pointer location or specified object

The three Motif buttons, described in Table 2, also start by default with the left mouse button.

Table 2

Button	Description
BSELECT	Selects, activates, and sets the location cursor, drag
BTRANSFER	Moves and copies elements, drag and drag transfer
BMENU	Pops up menus

OLIT versus Motif 1.2.3 Libraries

In addition to widgets, Motif and OLIT support a number of features and convenience routines that are useful in manipulating widgets and the UI.

Only in OLIT

The following features are available only in OLIT:

Drag-and-Drop Support

OLIT 3.0 provides an API, along with a DropTarget widget, to make it easier to integrate Drag-and-Drop support for OpenWindows V3.

Dynamic Resources

OLIT provides support for the user to dynamically change the value of certain resources (colors, fonts) after an application has been started.

Error-Handling Routines

OLIT provides a range of routines to allow the application to customize error handling.

Input -Focus Routines

OLIT provides routines that you can use to manipulate and direct input focus around the UI.

Only in Motif

UIL Support

Motif supports using UIL definitions for the UI layout. This separation allows the UI to be modified without recompiling the executables of the program. OLIT's Devguide solution (golit) provides similar ability by allowing the UI to be defined in GIL file format; however, the application must be recompiled when the UI changes. However, the changed UIL file must be recompiled using uil.

Clipboard Routines

Motif provides a library for managing the clipboard and its selections.

Widget-Creation Routines

Motif provides a complete set of routines that create a particular type of widget or group of widgets.

Compound String Support

Motif requires the user of compound strings for all text. To support these special string formats, Motif provides a number of routines to create and manipulate compound strings.

Widgets

Both toolkits support a number of common widgets and gadgets with similar functionality. In addition, each supports a number of more exclusive widgets. If a widget is implemented in one toolkit but not in the other, it is often possible to build an equivalent object using multiple widgets in the other toolkit.

Table 2-1 matches the common widget name to the actual class name of the widget in each toolkit.

Table 2-1

High-Level Name	OLIT Class Name	Motif Class Name
BulletinBoard	BulletinBoard	XmBulletinBoard
Drawing Area	DrawArea	XmDrawingArea
Form Manager	Form	XmForm
Manager (Meta Class)	Manager	XmManager
Menu Button	MenuButton	XmCascadeButton
Message Popup	NoticeShell	XmMessageBox
Popup Dialog Shell	PopupWindowShell	XmDialogShell
Popup Menu Shell	PopupMenuShell	XmMenuShell
Primitive (Meta Class)	Primitive	XmPrimitive
PushButton	OblongButton	XmPushButton
RowColumnManager	ControlArea	XmRowColumn
ScrollBar	Scrollbar	XmScrollBar
Scrollable List	ScrollingList	XmList
Scrolled Window	ScrolledWindow	XmScrolledWindow
Sliding Scale	Slider	XmScale
StaticText/Label	StaticText	XmLabel
Text, Multi-line	TextEdit	XmText
TextField	TextField	XmTextField
Toggle Button	RectButton	XmToggleButton

OLIT Exclusive Widgets

AbbrevMenuButton

This button is a primitive widget that displays exclusive and nonexclusive choice menus.

DropTarget

This primitive widget implements both the source and destination ends of Drag-and-Drop operations.

Flat Widgets

These special widgets manage any number of subobjects within the context of a single widget. When implementing menus or choice objects that contain many subitems a significant memory savings is provided.

FooterPanel

This manager widget automatically supports a window with a floating footer area.

RubberTile

This manager widget allows relative-sizing constraints to be placed on its children.

Stub

This primitive widget exposes its method hooks for an application to program custom widget behavior.

Interoperability Issues

The following section summarizes some of the interoperability issues that exist between OPEN LOOK and Motif applications. You can not do the following:

• Use primary copy, move, and link in XView and OLIT applications.
• Make secondary selections between Motif applications and XView or OLIT applications.
• Copy or cut from a Motif application into the Clipboard and then paste to an XView text subwindow.

• Copy or cut and paste Asian text between a Motif application and an XView or OLIT application.
• Drag and drop between Motif applications and XView or OLIT applications.

The following section summarizes some of the interoperability issues between the Motif Window Manager (mwm) and OPEN LOOK Applications.

• The window manager items for some XView and OLIT windows are not correct, for example, some applications may display extra titles, or extra resize handles. These differences do not affect the functions of the application.
• The window manager function f.kill when executed on base frame windows of an XView application (typically done by pulling down the default window menu and selecting Quit or Close) may exit the application without user confirmation, or any further application-specific processing.
• The resource keyboardFocusPolicy if set to pointer in XView or OLIT applications does not darken the caret. To darken the caret, click inside the window.
• The default colors for XView applications are different from Motif.
• The drag-and-drop feature of dropping data onto an icon of a closed XView application will not work while running mwm. Running other Motif applications will work.

Porting from IXI Motif 1.2.2

• Incompatibilities between Motif 1.2.2 and OSF/Motif 1.2.2

  Some features present in the previous release were a legacy of IXI Motif 1.2.2. These features are not part of the OSF/Motif 1.2 specification, and are not present in this version of Motif released by SunSoft. Remove them if you have used them.

The following features are no longer supported by SunSoft:

• XmList convenience functions:

       XmListRecolorItem
       XmListRecolorPos
       XmListSetClientDataPos
       XmListSetClientDatasPos
· XPM format bitmap file support

IXI 1.2.2 supported conversion of XPM format files for some resources with bitmap semantics. This feature is not available in this release.

• XmForm widget

  The XmForm widget implementation in the 1.2.2 was an IXI implementation, and not the OSF original though the API was identical. You can make your applications work with other Motif 1.2 implementations by recompiling them. However, internal data structures and algorithms were different. Binary compatibility with other Motif implementations for applications using XmForm widgets is not assured. This SunSoft Motif release uses the OSF XmForm widget implementation.

• Directory hierarchy

  The directory hierarchy of the SunSoft Motif 1.2.3 software is different from 1.2.2 and of other Motif products. The distribution has a similar structure to the CDE hierarchy for consistency and to ease migration for future CDE users. Some other Motif 1.2 implementations install into /usr/lib, /usr/include and /usr/bin/X11. You will need to ensure that your environment and your make configuration files reflect use the MOTIFHOME scheme outlined in these release notes. See Chapter 1, "The Motif Environment," for more information.

Tools to Ease the Transition

Many third-party tools are offered to transition to Motif.

Integrated Computer Solutions (ICS) is offering two converters: one translates XView code to GIL code and one that translates GIL code to Motif code.

SunSoft's Devguide now offers Motif Conversion Utilities as a way of helping customers make the transition. Devguide's front end is still in OPEN LOOK, and it has the same OPEN LOOK palette, but it is possible to use the Motif Conversion Utilities to transform GIL files into UIL files or Motif C code. The Motif Conversion Utilities (guil and gmf) in Solaris 2.4 SDK allow conversion of GIL files to UIL and Motif C code. UIL files can be imported into Motif GUI builders to generate Motif-based GUIs.

A final strategy is to perform the conversion at the GUI-builder level. One third-party vendor is currently working on a program for Solaris 1.x to produce GIL files from XView source.

Application Architecture

The ease in migrating your application from OPEN LOOK to Motif is a function of how your software is laid out and the tools you used to develop it.

The following list of questions provides the most significant factors for determining the ease of your migration to Motif:

• Does your application cleanly separate UI capabilities from internals?

  If you can draw a line through your code modules and completely isolate those that constitute the UI from those that make up the remainder of your application, then you can focus your migration efforts on the process of replacing the UI modules with equivalent ones developed for Motif. Many application developers follow software development methods that require this kind of clean separation, and, in some cases, even formally specify the program boundaries between UI and application internals.

  Alternatively, if your software is more monolithic and has application-specific abilities embedded within functions that also provide the UI, then you may have to spend extra time separating the two types of functions, thereby complicating your migration.

• Did you use any UI development tools (for example, builders) in the development of your application?

  Your use of an application builder gives you opportunities for saving effort in your migration to Motif. In most cases, the use of a builder implies that you have some degree of separation between UI functions and application internals, the advantages of which were previously discussed.

  Also, builders typically use generalized internal storage formats or are capable of generating interchange files, each of which may be post-processed to automate some of the conversion process. Contact your builder vendor to see what migration tools they are currently offering.

  Other less tangible tools that you might have used and that could ease your transition include development approaches that produced functional requirements documents or high-level designs. These representations may describe your application in terms less specific to OPEN LOOK and that are more amenable to being mapped to Motif than your source code.

• How do you follow the event-oriented functional model inherent in the Xt Intrinsics?

  The asynchronous style of programming typically used in applications using the Xt Intrinsics requires much of the application capabilities to be concentrated in the main program and callback functions registered to respond when particular events occur in the running application. If your application uses the standard facilities provided by Xt and follows its model closely, then you can save some time migrating by making a detailed study of your main program and callback functions. This will allow you to see how much of what these functions do to application internals.

  If you follow the OLIT model because OLIT is an Intrinsics-based toolkit, you will have an easier time migrating than applications built with XView.

• Do you share code with other applications or developers?

  Do not overlook the possibility that you may share some of the migration work with others. If you use libraries or tools from other vendors, you should contact them to see what plans they have for transitioning those software products to Motif.