SGI Techpubs Library

IRIX 6.5  »  Books  »  Developer  »  
Motif 2.1 Porting Guide
(document number: 007-3951-001 / published: 1998-11-25)    table of contents  |  additional info  |  download
find in page

Chapter 2. Motif API Changes

Official Open Group Changes

With the introduction of Motif 2.0, the Open Software Foundation, now The Open Group, cleaned up the APIs. Most of the public (that is, intended for application use) API was left as it was, but the private (needed by Widget writers) was completely changed. Before 2.0, there were two types of symbols, public (prefixed by Xm), and private (prefixed by _Xm). Motif 2.0 introduced a new type, (prefixed by Xme), and renamed most of the _Xm symbols to be Xme. There are still some _Xm symbols, but these are internal to the library and are not guaranteed to be exported.

Some symbols (EditDone, EditError, EditReject, XmTextStatus) have been moved from a private header file (Xm/TextStrsoP.h) to a public one (Xm/Xm.h). This can cause some problems with applications and libraries which use those symbols themselves. In these cases, there is a namespace conflict at compile time due to redefinition. The problem can be acute because some of these symbols do not have a Xm prefix.

Because these symbols can break existing applications, they have been moved back to their old, private locations as the default. To get the standard OSF behavior (with these symbols in the public header file), define _SGI_OSF_PUBLIC_SYMBOLS before any Motif header file is included.

Obsolete Symbols

The Table 2-1 lists symbols that were in Motif 1.2 but are not in 2.1, along with any replacement.

Table 2-1. OSF Obsoleted Symbols

Motif 1.2 Symbol

Motif 2.1 Symbol

_XmOSPutenv()

 

_XmGetDefaultTime()

XmeGetDefaultTime()

_XmGetColors()

XmGetColors()[a]

_XmDrawShadows()

XmeDrawShadows()a

_XmEraseShadow()

XmeClearBorder()

_XmGetArrowDrawRects()

XmDrawArrow()

_XmOffsetArrow()

XmeDrawArrow()a

_XmDrawSquareButton()

 

_XmDrawDiamondButton()

XmeDrawDiamond()

_XmDrawShadowType()

XmDrawShadows()a

_XmDrawBorder()

XmeDrawHighlight()

_XmMoveObject()

XmeConfigureObject()a

_XmResizeObject()

XmeConfigureObject()a

_XmVirtualToActualKeysym()

XmeVirtualToActualKeysyms()a

[a] API has changed.


Silicon Graphics Changes

XPM

Motif 2.x makes use of the Xpm library for colored pixmaps (implemented internally to the library). ViewKit 1.2 distributed its own copy of this library as well. Silicon Graphics has consolidated this and now ships a standalone copy of libXpm.so as part of the Motif 2.1 images. Documentation, in the form of the original PostScript report and examples, may be found in /usr/share/src/X/motif-2.1/xpm.

Archive Libraries

With IRIX 6.5, Silicon Graphics moved the Motif archive libraries (that is, libXm.a) out of the default installation images. With Motif 2.1, archive libraries are no longer shipped; all the required libraries are shipped as shared objects (DSOs) in the standard execution environment.

Consistent APIs

Considerable effort has been made toward tidying up the various Silicon Graphics APIs. Some symbols have been renamed to better highlight which APIs have been added by Silicon Graphics. In the past, some of these symbols were mistakenly prefixed with Xm. These have now been renamed to have a prefix of Sg. Table 2-2 lists these symbols.

To help in porting older code that may have used these APIs, the old symbol names can be activated by defining _SGIMOTIF_OBSOLETE_API before any Motif header file is included. By default, this flag is not enabled.

Table 2-2. New Names for Silicon Graphics Symbols

Silicon Graphics Motif 1.2 Symbol

Silicon Graphics Motif 2.1 Symbol

XmNmenuBarRepeatTimeout

SgNmenuBarRepeatTimeout

XmCMenuBarRepeatTimeout

SgCMenuBarRepeatTimeout

XmNarrowsAdjacent

SgNarrowsAdjacent

XmCarrowLayout

SgCarrowLayout

XmNarrowType

SgNarrowType

XmRArrowType

SgRArrowType

XmRIndPixel

SgRIndPixel

XmRSelectPixel

SgRSelectPixel

XmRArrowType

SgRArrowType

XmNindicatorBackground

SgNindicatorBackground

Xm3D_ONE_OF_MANY

Sg3D_ONE_OF_MANY

Xm3D_N_OF_MANY

Sg3D_N_OF_MANY

XmNOT_ADJACENT

SgNOT_ADJACENT

XmLEFT_ADJACENT

SgLEFT_ADJACENT

XmRIGHT_ADJACENT

SgRIGHT_ADJACENT

XmTOP_ADJACENT

SgTOP_ADJACENT

XmBOTTOM_ADJACENT

SgBOTTOM_ADJACENT

XmNORMAL_ARROWS

SgNORMAL_ARROWS

XmROTATE_ARROWS

SgROTATE_ARROWS

XmNO_THUMB_WHEN_EMPTY

SgNO_THUMB_WHEN_EMPTY


New #define Statements

Table 2-3 lists three basic #define statements used in the various libraries and applications. They are listed here primarily for information value. The only one that can be turned off is _SGIMOTIFAPI. _SGIMOTIF and _SGIBUGFIX should never be turned off.

Table 2-3. Silicon Graphics #define Statements

Statement

Effect

#define _SGIMOTIF

All Silicon Graphics look and feel changes. This should not be turned off at application compile time, because internal structures will be incorrectly sized.

NOTE: If _SGIMOTIF is defined, the application should be able to count on the full Silicon Graphics look and feel (that is, Schemes/desktop integration, and so forth). However, because this has not been fully tested, be cautious in making this assumption.

#define _SGIBUGFIX

A change that has either been sent to TOG for inclusion into the standard source base, or a change that is required for the Silicon Graphics build environment that is not directly related to the look and feel. This is also something that should not be touched by an application.

#define _SGIMOTIFAPI

Wraps extensions to the Motif API. This can be turned off by an application program by using the following statement before any Motif headers are included:

#define _NO_SGIMOTIFAPI

Note: Using the #undefine statement with _SGIMOTIFAPI does not work.


New Resource: SgNshowVersion

To further help in porting, Silicon Graphics has added a new resource SgNshowVersion (type Boolean). If SgNshowVersion is True (the default is False), a message will be printed out to stdout indicating that the application is linking against Motif version 2.1 library. The following message will be printed out:

SGI Irix Indigo Magic 2.1, based on OSF/Motif 2.1.10

New Widgets

For a quick introduction to the new widgets, compile and run either sampler2_0 demo (in /usr/share/src/X/motif-2.1/osf_demos/programs/sampler2_0) or periodic (in /usr/share/src/X/motif-2.1/osf_demos/programs/periodic). Each shows the new widgets, and how they can be used. (Sampler2_0 is probably preferable, because it is straight C code, rather than a mix of C and UIL.)

The following sections give a brief overview of the new widgets:

Notebook

The Notebook is the Motif version of a tabbed-dialog (in Windows terms) widget. It is a generic solution, where any widget that holds the XmQactivatable trait can be used as the button. Currently, XmPushButton, XmDrawnButton, XmArrowButton, XmPushButtonGadget, and XmArrowButtonGadget hold this trait.

Container

The container is a layout widget suitable for use as an outliner (where it is possible to expand or contract individual items). It may also be used as a base on which to place icons that can then be dragged around.

The file /usr/share/src/X/motif-2.1/osf_demos/programs/sampler2_0 shows an example of how to use this widget.

Combobox

This is a drop down list. It may be configured to be editable or not.

SpinBox

A combination of a text field and arrow buttons, a SpinBox is commonly used to step through an array of known values (for instance, the months of the year).

Notable Changes to Existing Widgets

The following sections briefly describe changes to existing widgets.

Toggle Button

The toggle button has a new resource XmNtoggleMode to allow the selection of a simple on/off toggle (XmTOGGLE_BOOLEAN) or a three state on/off/not set toggle (XmTOGGLE_INDETERMINATE).

Scale

The scale has a new visual mode, XmNslidingMode, which allows a thermometer type look (using XmTHERMOMETER) as well as the existing slider look (XmSLIDER).

New Features

Vertical Writing

IRIX 6.2 (and later) allow an application to use vertical writing (for use by Asian languages). This is set with the XmNlayoutDirection resource.


Note: Not all the widgets support XmNlayoutDirection; XmTextField for example, does not.

The code fragments in Example 2-1 illustrate the use of these widgets. Figure A-2 (in Appendix A) shows the resulting dialog box.

Example 2-1. Sample Code: Vertical Writing


/* vertical text widget */
vert = XtVaCreateManagedWidget(“vertical”,xmTextWidgetClass,form,
            XmNtopAttachment, XmATTACH FORM,
            XmNleftAttachment, XmATTACH FORM,
            XmNbottomAttachment, XmATTACH FORM,
            XmNlayoutDirection, XmTOP TO BOTTOM,
            XmNrows, 10,
            NULL);    
 
/* horizontal text widget */    
horiz = XtVaCreateManagedWidget(“horizontal”,xmTextWidgetClass,form,
            XmNtopAttachment, XmATTACH FORM,
            XmNleftAttachment, XmATTACH WIDGET,
            XmNleftWidget, vert,
            XmNrightAttachment, XmATTACH FORM,
            NULL);    

POSIX Style Message Catalogs

All of the Motif error messages are now stored in a POSIX style message catalog to allow for easy localization.

Motif 2.1 Porting Guide
(document number: 007-3951-001 / published: 1998-11-25)    table of contents  |  additional info  |  download

    Front Matter
    About This Guide
    Chapter 1. Developing With Motif 2.1
    Chapter 2. Motif API Changes
    Appendix A. Examples
    Index


home/search | what's new | help