Poly/ML for Motif

Quick Reference Manual

Mike Crawley

Chris Read

Copyright (c) 2000 Cambridge University Technical Services Limited
Copyright (c) 1992 Abstract Hardware Limited.
Copyright (c) 1992 Open Software Foundation, Inc.
Copyright (c) 1989 Digital Equipment Corporation.
Copyright (c) 1988 Massachusetts Institute of Technology.
All Rights Reserved.

Permission to use, copy, modify, and distribute these signatures and their documentation for any purpose and without fee is hereby granted, provided that the above copyright notices appear in all copies and that both the copyright notices and this permission notice appear in supporting documentation, and that the names of Digital, MIT, OSF, AHL and CUTS not be used in advertising or publicity pertaining to distribution of the signatures and their documentation without specific, written prior permission. Digital, MIT, OSF, AHL and CUTS disclaim all warranties with regard to these signatures and their documentation, including all implied warranties of merchantability and fitness, in no event shall Digital, MIT, OSF, AHL or CUTS be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of these signatures and their documentation.

Motif is a Trademark of OSF.
X Window System is a Trademark of MIT.

Contents

Chapter 1

Getting started with Motif

1.1 What is Motif

Motif is a user environment built on top of the X Window System and is designed to make interaction with your computer easier and more productive. Applications written for Motif are intended to follow a particular style of appearance and behaviour, so that you do not have to learn new techniques for working with each separate application program.

This document is intended to give enough information so that you can start programming Motif applications in Poly/ML without having to read all the standard OSF (Open Software Foundation) material. However, you will need more detailed information at later stages in your work and you should have the following three books at hand.

In addition to the reference material in these books, we recommend that you read a Motif programming manual from the following list.

1.2 What are Widgets

The Motif widget set is constructed on top of the Xt intrinsics, which are in turn constructed on top of the X Window System. A widget is an object providing a user interface abstraction, for example, a scroll bar. The Motif widget set aims to provide a set of useful abstractions that a programmer can join together to construct the application, often without having to invent any new additional behaviour or abstractions. The main advantages of the widget set are that all applications built with the same widget set provide the same set of abstractions, and the time to implement the application is drastically reduced, leaving the programmer more time to improve the program that is behind the user interface.

Each widget is a combination of an X Window, a well defined behaviour, and some state information. Each widget is a member of exactly one widget class which provides the functions and data for all members of that class. Widget classes may be inherited by subclassing.

A great deal of the visual appearance and some of the behaviour of each individual widget or an entire widget class can be customised by the user. This is typically done by using files of settings for the fields within the widget classes that affect colours, fonts, sizes, and so on. These fields are collectively known as resources, and this document contains tables of the permitted resources for each widget class.

1.3 Creating an application

An application must create a set of widgets to present to the user. First of all the application must create the application shell widget. Most applications only have one shell widget - this is the window which the window manager places and resizes on the screen. All the other widgets created by the application are typically children of this shell widget.

The structure XWindows contains all the definitions for the Xlib level of the interface. The structure Motif contains all the definitions for the Motif interface.

open XWindows ;
open Motif ;
...

val XtAppInitialise: string -> string -> string ->
                         string list -> Arg list -> Widget
...

The first parameter to XtAppInitialise is the name of the Display to open in the manner of the Xlib function X0penDisplay - this function is documented along with all the other Xlib functions in the Poly/ML for X Reference Manual. The second parameter is the name of this application, and the third parameter is the name of this class of application. Both these names are significant in loading the resource database and finding the resource values for all the widgets used inside this application. Finding resource values is discussed in more detail in a later section. The string list parameter is a list of fallback resource values and the Arg list parameter is a list of preset resource values. The preset resource values are always used in preference to resource values found in the database or in the fallback list. The fallback list provides values to use when values are not found in either the preset list or in the resource database. The resource values that each class of widget can accept are described in the sections about each individual widget class later in this document. The widget returned is an ApplicationShell widget on that display.

The following is the start of a small example program.

val shell =
    XtAppInitialise "" "xed" "Editor" [] [XmNwidth 400, XmNheight 400] ;

The display is opened and the first shell widget is created with preset width and height values.

Now that a shell widget has been created the other widgets in the application can be created. The functions to create different types of Motif widgets have differing names but they all have the same type.

val XmCreate<...>: Widget -> string -> Arg list -> Widget

The parameters specify the parent widget, the name of this widget, and any preset resource values. If no resource values are preset then they default to values in the user's resource files, or values in the fallback list, or to compiled-in defaults.

The next part of our example is as follows.

val main = XmCreateMainWindow shell "main" [] ;

val bar = XmCreateMenuBar main "bar" [] ;

val fileMenu = XmCreateCascadeButton bar "file" [XmNlabelString "File"] ;
val editMenu = XmCreateCascadeButton bar "edit" [XmNlabelString "Edit"] ;
val viewMenu = XmCreateCascadeButton bar "view" [XmNlabelString "View"] ;
val helpMenu = XmCreateCascadeButton bar "help" [XmNlabelString "Help"] ;

val command = XmCreateText main "command" [XmNeditMode XmSINGLE_LINE_EDIT] ;

val hscroll = XmCreateScrollBar main "hscroll" [XmNorientation XmHORIZONTAL] ;
val vscroll = XmCreateScrollBar main "vscroll" [XmNorientation XmVERTICAL] ;

val work = XmCreateDrawingArea main "work" [] ;

The code above creates a hierarchy of widgets. Each class of widget that can have child widgets is a subclass of Composite and provides a behaviour that manages those children. For example, in the code above, a MenuBar widget has four children which are all CascadeButtons. The MenuBar lays out the buttons horizontally and provides a behaviour for the buttons according to the movement of the mouse and the pressing of the mouse buttons. The MainWindow widget has the MenuBar, scroll bars and a drawing area as children, and provides a standard layout for these widgets.

1.4 Managing and Realizing Widgets

When a widget is managed it is added to the geometry-managed displayable subset of its parent's children. If a widget is not managed then it cannot be displayed and does not have its size and position changed by its parent. Managing and unmanaging can therefore be used to make different parts of an application appear and disappear, without the expense of creating and destroying widgets.

Realizing a widget is the process of creating and mapping an X window for the widget, and then recursively realizing the managed subset of the widget's children. Changing the managed subset will only have visible effects if the parent is already realized, or when the parent widget becomes realized later.

val XtManageChild: Widget -> unit
val XtUnmanageChild: Widget -> unit

val XtManageChildren: Widget list -> unit
val XtUnmanageChildren: Widget list -> unit

val XtRealizeWidget: Widget -> unit
val XtUnrealizeWidget: Widget -> unit

XtManageChild and XtUnmanageChild will manage and unmanage one widget at a time. XtManageChildren and XtUnmanageChildren can be given lists of widgets with a common parent and can be quicker than working on one widget at a time.

XtRealizeWidget is given the root of a widget tree and recursively creates and maps all the X windows required by the managed children in the tree.

XtUnrealizeWidget is given the root of a widget tree and recursively destroys all the X windows created by the managed children in the tree.

Our example continues with managing and realizing the widgets we have just created.

XtManageChildren [fileMenu, editMenu, viewMenu, helpMenu] ;
XtManageChildren [bar, command, hscroll, vscroll, work] ;

XmMainWindowSetAreas main bar command hscroll vscroll work ;

XtManageChild main ;
XtRealizeWidget shell ;

At this point the application becomes visible on the display and will look very similar to the application below.

1.5 What are Arg lists and Resources

A resource is a named field inside a widget that can be set with a value by the user in one of several ways. These resources are used to change the behaviour or the appearance of the widget. The names of all these resources are printed in tables in this manual for every widget class that is available in Motif. For example

The purpose of each resource is fully documented in the OSF/Motif Programmer's Reference.

1.5.1 Initialising with Arg lists

There are several ways to set the initial value of a resource. When a widget is created the user passes in an Arg list which contains preset resource values. These values are copied into the widget in preference to all other values. The Arg datatype is designed to provide an easy way of passing in values of many different types as a single Arg list. The constructors have names such as

val XmNshadowThickness: int -> Arg
val XmNsliderSize: int -> Arg

and can be used as destructors as well. Arg is actually implemented as an infinite datatype - it is the type exn - which means that signatures for functors that use only a few of the Arg destructors need not know the names of all the other destructors - which would be the case with a standard datatype. Instead they need only include the lines they need, as in the following example.

signature MOTIF_SIG = sig
   type Widget

   type Arg sharing type Arg = exn

   val XmCreateCascadeButton: Widget -> string -> Arg list -> Widget

   exception XmNshadowThickness of int
   exception XmNsliderSize of int
end ;

When compiling code that uses the signature above the compiler knows that the Arg list needed by XmCreateCascadeButton is the same type as exn list, and this will allow you to construct and destruct these lists using the exception constructors. If you pass in an exn that is not recognised by the Motif interface then it is rejected and an exception is raised.

1.5.2 Loading the resource database

If a resource value is not specified in the Arg list at creation time then the widget searches the resource database for that field.

A complicated process of merging together separate resource files into a single resource database is performed when the function XtAppInitialise is called. This process is fully documented in user manuals for X Windows, especially in Chapter 11 of Vol 1 of the O'Reilly series of X Manuals. Here we only give a simple example of how the resource files are located - which is enough for most users.

First the process attempts to load a class-specific resource file using the application class name and a search path which is stored in an environment variable. The third parameter to XtAppInitialise is the name of this class of application, and the search path is typically stored in the XFILESEARCHPATH environment variable as follows.

setenv XFILESEARCHPATH $HOME/%T/%N%S

The loading process replaces the %T component of the path with app-defaults and the %N component with the class name. The suffix component %S is not normally used here. In simpler terms, if the user has a directory called app-defaults in his home directory, and in that directory there is a file with the same name as the class name of the application, for example Editor, then that file is loaded into the resource database. Note that class names start with a capital letter by convention.

Then the process attempts to load another class-specific resource file using the application class name and a search path which is stored in the XAPPLRESDIR environment variable, which typically has a value like

/usr/motif/lib/app-defaults

If, in this directory, there is a file with the same name as the class name of the application then that file is merged into the resource database we have constructed so far.

The process then looks for a property which holds the default resources on the root window of the user's display. These defaults are often put in place by the xrdb program. These are merged into the database if they are found, otherwise the process looks for a file called $HOME/.Xdefaults and merges that into the database instead. Often the root property set by xrdb is a copy of the .Xdefaults file at the time the X server was started. If the user changes the .Xdefaults file then he should use

xrdb .Xdefaults

to copy the new version into the server.

Note the order of the merging process. The preset Arg list parameter overrides the values in the .Xdefaults file, which override the values in the XAPPLRESDIR directory, which override the values in the XFILESEARCHPATH directory, which override the values in the fallback resource list parameter.

Typically the user creates a file for each application class in his app-defaults directory. This keeps the resource settings for each application separate from one another, and keeps the .Xdefaults file small.

1.5.3 Finding resources in the database

The second and third parameters to XtAppInitialise are the name of this application instance, and name of this class of application. These names are used to construct the full names of the resource fields in the widgets.

For example, if the application name is xed and there is an XmMainWindow widget with the name main, then the resource fields XmNforeground and XmNshowSeparator have the full names

xed.main.foreground
xed.main.showSeparator

The levels in the widget hierarchy are represented by the names of the widgets from oldest parent down to youngest child with dots as separators. Therefore it is not a good idea to place dots inside the ML strings to be used for widget names.

The resource constructors/destructors have the prefix XmN in order to make them distinct from other ML identifiers. This prefix is not needed in the resource database and explains why the resource field XmNforeground of the widget main is printed as main.foreground in the example above.

If any entries in the database match these names then those values will be copied into the widget. Here are some example lines from a resource database

The full name xed.main.foreground matches the database line xed*foreground because the * character is a wildcard character that matches any number of levels in the widget hierarchy. The value from the database is automatically converted to the correct type for the resource field. In this case, the value black is converted to a Pixel by the built-in converter that allocates named colours and returns their pixel values. If a conversion fails then a message is output to the user and the resource field defaults to a compiled-in default.

The full name xed.main.showSeparator matches the database line xed.main.showSeparator exactly and the string True is converted to the corresponding ML boolean value true.

If resources cannot be matched by name, then the search tries to match by class instead. There are three classes to be aware of: firstly the application class, secondly the widget class, and thirdly the resource class. Resource classes are listed in the resource tables for each widget class. Each class name is prefixed by XmC to make them distinct from other ML identifiers. This prefix is not needed in the resource database.

In our example the application class is Editor, which means that the database line Editor.main.background will set the XmNbackground field of the main widget to wheat. If we had other applications with different names, but they were members of the same Editor application class, then they too would have their main.background resources set to wheat. In this way it is possible to change the user preferences for a whole class of applications with one line in the resource database.

In our example the widget class for main is XmMainWindow, which means that the database line *XmMainWindow.commandWindowLocation will set the XmNcommandWindowLocation field of the main widget to XmCOMMAND_ABOVE_WORKSPACE. In fact, because of the * wildcard it will set this field in every XmMainWindow in every application we run. In this way it is possible to change the user preferences for a whole class of widgets with one line in the resource database.

Note that the resource database string COMMAND_ABOVE_WORKSPACE has a corresponding ML value called XmCOMMAND_ABOVE_WORKSPACE which is one of the constant constructors of the XmCommandWindowLocation datatype.

To specify one value from a range of predefined constants, remove the Xm from the ML constant and use the remaining letters and underscores in the resource database.

The last line of our example is xed*ShowArrows. This will set all resource fields in the xed application that have a class of XmCShowArrows. The resource field XmNshowArrows in the scroll bars that we manage inside the main window have this resource class. In this way it is possible to change the user preferences for a whole class of resources with one line in the resource database.

If the resource value could not be found in the resource database then it looks through the fallback resources specified with the XtAppInitialise function. If the resource value has still not been found then it is set to a compiled-in default.

1.6 Changing and examining Widget state

The current value of widget resources make up the widget's state. To get the current value of a resource, or a list of resources, use the following functions.

val XtGetValue: Widget -> string -> Arg
val XtGetValues: Widget -> string list -> Arg list

The string to pass in is the resource name corresponding to the Arg required. For example, the Arg constructor XmNforeground has the corresponding string "foreground". The code for this example would look like

val (XmNforeground pixel) = XtGetValue widget "foreground" ;

Because the Arg type is an infinite datatype - it is the type exn - you must use the exception names as destructors to get the values out. In the above example the identifier pixel will be bound to the int returned inside the XmNforeground exception packet. This allows the system to be flexible and allow any type to be packaged up and stored as a widget resource.

To set a widget's resource value use one of the following functions.

val XtSetValue: Widget -> Arg -> unit
val XtSetValues: Widget -> Arg list -> unit

Construct the Arg values by applying the Arg exception constructors to the basic ML values. The widget will decide if it wants to accept the new value, or reject it, and may decide to move, resize or redraw itself - the user does not have to do this. For example, setting the current value and slider size on a XmScale widget is done by

XtSetValues scale [XmNvalue 42,XmNsliderSize 100] ;

1.7 What are Callbacks

Callbacks are used to apply ML functions when the user performs some user interface abstraction, such as clicking on a scrollbar, or selecting from a menu. This is a much higher level of abstraction than programming at the X Event level using Xlib. Each widget typically provides several callbacks that the programmer can attach ML functions to. These functions get called when specific user actions are performed - the resource tables later in this manual indicate which callbacks are valid for each widget, and the OSF/Motif Programmer's Reference can tell you more details about the actions that trigger the callbacks. Each callback within a widget has one of the following names from the XtCallback datatype.

datatype XtCallback = XmNactivateCallback | XmNapplyCallback

| XmNarmCallback | XmNbrowseSelectionCallback

| XmNcancelCallback | XmNcascadingCallback

| XmNcommandChangedCallback | XmNcommandEnteredCallback

| XmNdecrementCallback | XmNdefaultActionCallback

| XmNdestroyCallback | XmNdisarmCallback

| XmNdragCallback | XmNentryCallback

| XmNexposeCallback | XmNextendedSelectionCallback

| XmNfocusCallback | XmNgainPrimaryCallback

| XmNhelpCallback | XmNincrementCallback

| XmNinputCallback | XmNlosePrimaryCallback

| XmNlosingFocusCallback | XmNmapCallback

| XmNmessageCallback | XmNmodifyVerifyCallback

| XmNmotionVerifyCallback | XmNmultipleSelectionCallback

| XmNnoMatchCallback | XmNokCallback

| XmNpageDecrementCallback | XmNpageIncrementCallback

| XmNpopdownCallback | XmNpopupCallback

| XmNresizeCallback | XmNsimpleCallback

| XmNsingleSelectionCallback | XmNtoBottomCallback

| XmNtoTopCallback | XmNunmapCallback

| XmNvalueChangedCallback

The function XtSetCallbacks is used to attach a list of (XtCallback,function) pairs to a Widget. It has the following interesting type

val XtSetCallbacks: Widget ->

(XtCallback * (Widget * 'a XEvent * 'b -> 'b)) list ->

'b ->

int -> 'a -> unit

The first parameter is the widget to set the callbacks on. The second parameter is a list of (XtCallback,function) pairs which will replace the current set of callbacks for this widget. This works in the following way - if the user performs an action which causes the widget to trigger its XmNvalueChangedCallback, and if there is a corresponding pair (XmNvalueChangedCallback,f) in the list then the function f will be applied. Each function in the list has the same type

Widget * 'a XEvent * 'b -> 'b

When the widget calls the function, it passes itself as the first element of the tuple followed by the 'a XEvent that triggered the callback, and lastly the 'b user defined state for the widget. The function must return a new 'b value to use as the user defined widget state.

The next parameter to XtSetCallbacks is the 'b to use as the initial state for this widget. Only one callback is ever applied at any one time - the 'b state is passed from one callback to another in a series of state transformations. If a callback function wishes to look at or change part of the widget resource state it can call XtGetValues and XtSetValues.

XtSetCallbacks then returns a function of type

int -> 'a -> unit

which can be used for sending 'a messages to the widget. If the pair (XmNmessageCallback, f) is included in the callback list then f will receive 'a XEvent messages which it can destruct with the Message XEvent destructor. This is a way of sending strongly typed message information between collections of widgets. The int parameter is the delay in milliseconds before sending the message - this is often useful for sending wakeup messages, or for performing auto-repeats.

Chapter 2

Widget Classes

This chapter describes the major widget classes available in Motif and gives a picture showing their appearance. A diagram next to each picture shows the widget class hierarchy for this class. Tables are included showing the resource names that are applicable to each class. The ML types of related Motif functions are also shown, along with a short description of how the widget is generally used.

Resource names such as XmNforeground begin with an XmN prefix when used as Arg destructors or constructors. When compiling resource files the prefix is not needed.

Resource class names such as XmCPosition begin with an XmC prefix when used as the names of ML strings. When compiling resource files the prefix is not needed.

Constant constructors in datatypes such as XmARROW_DOWN have an Xm prefix in ML, but when used as values in a resource file the prefix is not needed.

2.1 ArrowButton

Description:

ArrowButton widgets are button widgets generally used to change the geometry or view of part of an application. The widget consists of an arrow indicating the direction of the desired change. Shadows are placed around the arrow to give the appearance that the ArrowButton has been pressed in when the button is selected. The XmNarrowDirection resource is used to choose which way the arrow will point.

Resources:

Functions:

datatype XmArrowDirection = XmARROW_UP | XmARROW_DOWN | XmARROW_LEFT | XmARROW_RIGHT

datatype XmMultiClickType = XmMULTICLICK_DISCARD | XmMULTICLICK_KEEP

val XmCreateArrowButton: Widget -> string -> Arg list -> Widget
val XmCreateArrowButtonGadget: Widget -> string -> Arg list -> Widget

val XmIsArrowButton: Widget -> bool
val XinIsArrowButtonGadget: Widget -> bool

2.2 BulletinBoard

Description:

BulletinBoard is a general container widget used as the basis for most dialog widgets. It provides simple geometry management for its children, without forcing any positioning constraints on them. It can be set to reject geometry requests that result in overlapping children by changing the XmNallowOverlap resource to false.

Resources:

Functions:

datatype XmDialogStyle = XmDIALOG_MODELESS | XmDIALOG_PRIMARY_APPLICATION_MODAL | XmDIALOG_FULL_APPLICATION_MODAL | XmDIALOG_SYSTEM_MODAL

datatype XmResizePolicy = XmRESIZE_NONE | XmRESIZE_ANY | XmRESIZE_GROW

datatype XmShadowType = XmSHADOW_ETCHED_IN | XmSHADOW_ETCHED_OUT | XmSHADOW_IN | XmSHADOW_OUT

val XmCreateBulletinBoard: Widget -> string -> Arg list -> Widget
val XmCreateBulletinBoardDialog: Widget -> string -> Arg list -> Widget
val XmCreateForm: Widget-> string -> Arg list -> Widget
val XmCreateFormDialog: Widget-> string -> Arg list -> Widget

val XmIsBulletinBoard: Widget-> bool
val XmIsForm: Widget-> bool

2.3 CascadeButton

Description:

CascadeButton widgets are used to construct menu systems. It is the only widget that can have a Pulldown MenuPane attached to it as a submenu via the XmNsubMenuId resource.

To create a menu system CascadeButtons are placed inside a MenuBar. Each of these buttons has a MenuPane attached to it as a submenu. These submenus may also contain CascadeButtons which have further submenus, and so on.

CascadeButtons must have RowColumn parents - a MenuPane and a MenuBar are special cases of a RowColumn widget.

Resources:

Functions:

val XmCreateCascadeButton: Widget-> string -> Arg list -> Widget
val XmCreateCascadeButtonGadget: Widget-> string -> Arg list -> Widget
val XmCreateSeparator: Widget-> string -> Arg list -> Widget
val XmCreateSeparatorGadget: Widget-> string -> Arg list -> Widget
val XmCreateMenuBar: Widget-> string -> Arg list -> Widget
val XmCreateOptioMenu: Widget-> string -> Arg list -> Widget
val XmCreatePopupMenu: Widget-> string -> Arg list -> Widget
val XmCreatePulldowrLMenu: Widget-> string -> Arg list -> Widget

val XmCascadeButtonHighlight: Widget-> bool -> unit

val XmIsCascadeButton: Widget-> bool
val XmIsCascadeButtonGadget: Widget-> bool

2.4 Command

Description:

Command widgets are special purpose widgets designed for the entry of textual commands with a history mechanism for retaining previous commands. The widget allows new commands to be entered, or old commands can be selected from a history list and edited to make new commands. Each new command is automatically added to the history. The XmNcommand resource is used to get or set the current command string. The XmCommandError can be used to display an error message at the bottom of the history list.

One additional WorkArea child may be added to a command widget.

Resources:

Functions:

val XmDIALOG_COMMAND: XmDialogType

val XmDIALOG_COMMAND_TEXT: XmDefaultButtonType
val XmDIALOG_PROMPT_LABEL: XmDefaultButtonType
val XmDIALOG_HISTORY list: XmDefaultButtonType

val XmCreateCommand: Widget -> string -> Arg list -> Widget

val XmCommandError: Widget -> XmString -> unit
val XmCommandGetChild: Widget -> XmDefaultButtonType -> Widget

val XmIsCommand: Widget -> bool

2.5 ErrorDialog

Description:

An ErrorDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, and the error icon which resembles a Stop sign. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_ERROR: XmDialogType

val XmCreateErrorDialog: Widget -> string -> Arg list -> Widget

2.6 FileSelectionDialog

Description:

A FileSelectionDialog allows the user to choose one file from among the files and directories in the file system. The dialog has the following components :-

The Filter text field is used for editing the mask which specifies both the base directory and the filter applied to display the entries in that directory. Pressing the RETURN key after editing this field resets the base directory and reapplies the filter. This is equivalent to pressing the Filter button.

The Files list shows the list of filenames that result from applying the filter to the files in the base directory. Clicking on a filename in the list copies it to the Selection field. Double clicking copies the filename to the Selection field and presses the OK button.

The Directories list shows the list of directories found in the base directory. Clicking on a directory in the list inserts that directory name into the mask in the Filter field. Double clicking inserts the directory into the mask and presses the Filter button to reapply the filter to the new base directory.

The Selection text field shows the currently selected filename appended to the current base directory. If this is not the filename that you require you may either edit it by hand, or use the methods described above to choose another filename.

The OK button does not change any of the fields, it simply causes the XmNokCallback to be applied. This function typically gets the value of the XmNtextString resource, and then performs some action with that filename. If the XmNautoUnmanage resource is set to true then the dialog automatically unmanages itself.

Pressing the Filter button reapplies the filter to the filenames found in the base directory, and updates the Files list.

Pressing the Cancel button applies the XmNcancelCallback function, and if the XmNautoUnmanage resource is set to true then the dialog automatically unmanages itself.

Pressing the Help button applies the XmNhelpCallback function.

Resources:

Functions:

datatype XmFileTypeMask = XmFILE_REGULAR | XmFILE_DIRECTORY | XmFILE_ANY_TYPE

val XmDIALOG_FILE_SELECTION: XmDialogType

val XmDIALOG_APPLY_BUTTON: XmDefaultButtonType
val XmDIALOG_CANCEL_BUTTON: XmDefaultButtonType
val XmDIALOG_DEFAULT_BUTTON: XmDefaultButtonType
val XmDIALOG_DIR_LIST: XmDefaultButtonType
val XmDIALOG_DIR_LIST_LABEL: XmDefaultButtonType
val XmDIALOG_FILTER_LABEL: XmDefaultButtonType
val XmDIALOG_FILTER_TEXT: XmDefaultButtonType
val XmDIALOG_HELP_BUTTON: XmDefaultButtonType
val XmDIALOG_LIST: XmDefaultButtonType
val XmDIALOG_LIST_LABEL: XmDefaultButtonType
val XmDIALOG_OK_BUTTON: XmDefaultButtonType
val XmDIALOG_SELECTION_LABEL: XmDefaultButtonType
val XmDIALOG_SEPARATOR: XmDefaultButtonType
val XmDIALOG_TEXT: XmDefaultButtonType

val XmCreateFileSelectionBox: Widget -> string -> Arg list -> Widget
val XmCreateFileSelectionDialog: Widget -> string -> Arg list -> Widget

val XmFileSelectionBoxGetChild: Widget -> XmDefaultButtonType -> Widget
val XmFileSelectionDoSearch: Widget -> XmString -> unit

val XmIsFileSelectionBox: Widget -> bool

2.7 InformationDialog

Description:

An InformationDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, and the information icon which resembles an Information sign. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_INFORMATION: XmDialogType

val XmCreateInformationDialog: Widget -> string -> Arg list -> Widget

2.8 List

Description:

List widgets are used to select of one or more entries from a list of text strings. The XmNselectionPolicy resource determines one of several different selection modes the list may operate in. The XmNitems resource is used to pass in the list of strings to select from. The XmNselectedItems resource is used to set or get the currently selected items.

Resources:

Functions:

datatype XmScrollBarDisplayPolicy = XmSTATIC | XmAS_NEEDED

datatype XmSelectionPolicy = XmSINGLE_SELECT | XmMULTIPLE_SELECT | XmEXTENDED_SELECT | XmBROWSE_SELECT

datatype XmVisualPolicy = XmVARIABLE | XmCONSTANT | XmRESIZE_IF_POSSIBLE

val XmCreateList: Widget -> string -> Arg list -> Widget
val XmCreateScrolledList: Widget -> string -> Arg list -> Widget

val XmIsList: Widget -> bool
val XmIsScrolledWindow: Widget -> bool

2.9 MainWindow

Description:

The MainWindow widget can be used to manage the primary view of an application. This widget has a number of optional components including a menu bar, a command window, a message window, scroll bars, and a work area. The required components are first created and managed and are then passed to the function XmMainWindowSetAreas so that they can be organised together to create the application's primary view. The XmNcommandWindowLocation resource can be used to control the positioning of the command window relative to the other windows.

Resources:

Functions:

datatype XmCommandWindowLocation = XmCOMMAND_ABOVE_WORKSPACE | XmCOMMAND_BELOW_WORKSPACE

val XmCreateMainWindow: Widget -> string -> Arg list -> Widget

val XmMainWindowSetAreas: Widget -> Widget -> Widget -> Widget -> Widget -> Widget -> unit

val XmMainWindowSepl: Widget -> Widget

val XmMainWindowSep2: Widget -> Widget

val XmMainWindowSep3: Widget -> Widget

val XmIsMainWindow: Widget -> bool

2.10 MessageDialog

Description:

A MessageDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, but does not have any predefined symbol icon. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_MESSAGE: XmDialogType

val XmDIALOG_CANCEL_BUTTON: XmDefaultButtonType
val XmDIALOG_DEFAULT_BUTTON: XmDefaultButtonType
val XmDIALOG_HELP_BUTTON: XmDefaultButtonType
val XmDIALOG_MESSAGE_LABEL: XmDefaultButtonType
val XmDIALOG OK BUTTON: XmDefaultButtonType
val XmDIALOG_SEPARATOR: XmDefaultButtonType
val XmDIALOG_SYMBOL_LABEL: XmDefaultButtonType

val XmCreateMessageBox: Widget-> string -> Arg list -> Widget
val XmCreateMessageDialog: Widget-> string -> Arg list -> Widget

val XmIsMessageBox: Widget-> bool

val XmMessageBoxGetChild: Widget -> XmDefaultButtonType -> Widget

2.11 OptionMenu

Description:

An OptionMenu is a specific instance of a RowColumn widget containing a label and a cascade button. Pressing the cascade button pulls down a menu pane so that one of the menu pane items can be selected. The menu pane is then removed and the selected item is displayed inside the cascade button. The XmNlabelString resource is used to set the label, and the XmNsubMenuId resource is used to set the menu pane.

Resources:

Functions:

val XmCreateOptionMenu: Widget-> string -> Arg list -> Widget
val XmCreateSimpleOptionMenu: Widget-> string -> Arg list -> Widget

val XmOptionButtonGadget: Widget -> Widget
val XmOptionLabelGadget: Widget -> Widget

2.12 PanedWindow

Description:

A PanedWindow is a composite widget that arranges its children vertically. The width of a paned window is equal to the widest child. The height of each pane can be adjusted by dragging the sash in the separators between the panes.

Resources:

Functions:

val XmCreatePanedWindow: Widget -> string -> Arg list -> Widget

val XmIsPanedWindow: Widget -> bool

2.13 PromptDialog

Description:

A PromptDialog widget is a specific instance of a MessageBox widget. It has an editable text field, OK, Cancel and Help buttons, and a prompt label. The XmNtextString resource is used to set the editable text string, and the XmNselectionLabelString resource is used to set the prompt.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_PROMPT: XmDialogType

val XmCreatePromptDialog: Widget -> string -> Arg list -> Widget

2.14 QuestionDialog

Description:

A QuestionDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, and the question icon which resembles a question mark. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_QUESTION: XmDialogType

val XmCreateQuestionDialog: Widget -> string -> Arg list -> Widget

2.15 Scale

Description:

A Scale widget is used to display and select a value from within a range of values. The XmNminimum and XmNmaximum resources set the range of the values, and the XmNvalue resource can be used to set and get the current value. The XmNtitleString resource is used to set the title label.

Resources:

Functions:

datatype XmOrientation = XmVERTICAL | XmHORIZONTAL

datatype XmProcessingDirection = XmMAX_ON_TOP | XmMAX_ON_BOTTOM | XmMAX_ON_LEFT | XmMAX_ON_RIGHT

val XmCreateScale: Widget -> string -> Arg list -> Widget

val XmIsScale: Widget -> bool

2.16 ScrollBar

Description:

A ScrollBar widget is used to indicate how much of a data set is currently being displayed in some other widget. The scrollbar can be adjusted by the user so that any part of the data set is displayed. The XmNminimum and XmNmaximum resources set the range of the data set, and the XmNvalue resource can be used to set and get the current position. The XmNsliderSize resource should be set to indicate how much of the set is currently visible.

Resources:

Functions:

datatype XmOrientation = XmVERTICAL | XmHORIZONTAL

datatype XmProcessingDirection = XmMAX_ON_TOP | XmMAX_ON_BOTTOM | XmMAX_ON_LEFT | XmMAX_ON_RIGHT

val XmCreateScrollBar: Widget -> string -> Arg list -> Widget

val XinIsScrollBar: Widget -> bool

2.17 ScrolledList

Description:

A ScrolledList widget is a composite widget consisting of a list widget contained within a scrolled window. list widgets are used to select of one or more entries from a list of text strings. The XmNselectionPolicy resource determines one of several selection different modes the list may operate in. The XmNitems resource is used to pass in the list of strings to select from. The XmNselectedItems resource is used to set or get the currently selected items.

Resources:

Functions:

datatype XmScrollBarDisplayPolicy = XmSTATIC | XmAS_NEEDED

datatype XmSelectionPolicy = XmSINGLE_SELECT | XmMULTIPLE_SELECT | XmEXTENDED_SELECT | XmBROWSE_SELECT

datatype XmVisualPolicy = XmVARIABLE | XmCONSTANT | XmRESIZE_IF_POSSIBLE

val XmCreateList: Widget -> string -> Arg list -> Widget
val XmCreateScrolledList: Widget -> string -> Arg list -> Widget

val XmIsList: Widget -> bool
val XmIsScrolledWindow: Widget -> bool

2.18 ScrolledText

Description:

A ScrolledText widget is a composite widget consisting of a text widget contained within a scrolled window.

Resources:

Functions:

datatype XmScrollBarDisplayPolicy = XmSTATIC | XmAS_NEEDED

datatype XmScrollingPolicy = XmAUTOMATIC | XmAPPLICATION_DEFINED

datatype XmTextScanType = XmSELECT_POSITION | XmSELECT_WHITESPACE | XmSELECT_WORD | XmSELECT_LINE | XmSELECT_ALL | XmSELECT_PARAGRAPH

val XmCreateText: Widget -> string -> Arg list -> Widget
val XmCreateScrolledText: Widget -> string -> Arg list -> Widget

val XmTextGetString: Widget -> string
val XmTextSetString: Widget -> string -> unit
val XmTextSetInsertionPosition: Widget -> int -> unit

val XmIsText: Widget -> bool
val XmIsScrolledWindow: Widget -> bool

2.19 ScrolledWindow

Description:

A ScrolledWindow is a widget that can manage two scroll bars and a work area. If the XmNscrollingPolicy resource is set to XmAUTOMATIC then all the scrolling behaviour is provided by the ScrolledWindow widget and the user just has to make the work area big enough to display all of the data. Other modes of operation exist for cases where this is inappropriate, such as displaying the text from a very long file.

Resources:

Functions:

datatype XmScrollBarDisplayPolicy = XmSTATIC | XmAS_NEEDED

datatype XmScrollBarPlacement = XmBOTTOM_RIGHT | XmTOP_RIGHT | XmBOTTOM_LEFT | XmTOP_LEFT

datatype XmScrollingPolicy = XmAUTOMATIC | XmAPPLICATION_DEFINED

datatype XmVisualPolicy = XmVARIABLE | XmCONSTANT | XmRESIZE_IF_POSSIBLE

val XmCreateScrolledWindow: Widget -> string -> Arg list -> Widget

val XmScrolledWindowSetAreas: Widget -> Widget -> Widget -> Widget -> unit

val XmIsScrolledWindow: Widget -> bool

2.20 SelectionDialog

Description:

A SelectionDialog includes a scrolled list, an editable text field, labels and four buttons which are labelled OK, Cancel, Apply and Help by default. Use the XmNlistItems resource to set the contents of the scrolled list, and the XmNtextString resource to set and get the value of the editable text field.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_SELECTION: XmDialogType

val XmDIALOG_APPLY_BUTTON: XmDefaultButtonType
val XmDIALOG_CANCEL_BUTTON: XmDefaultButtonType
val XmDIALOG_DEFAULT_BUTTON: XmDefaultButtonType
val XmDIALOG_HELP_BUTTON: XmDefaultButtonType
val XmDIALOG_LIST: XmDefaultButtonType
val XmDIALOG_LIST_LABEL: XmDefaultButtonType
val XmDIALOG_OK_BUTTON: XmDefaultButtonType
val XmDIALOG_SELECTION_LABEL: XmDefaultButtonType
val XmDIALOG_SEPARATOR: XmDefaultButtonType
val XmDIALOG_TEXT: XmDefaultButtonType

val XmCreateSelectionBox: Widget -> string -> Arg list -> Widget
val XmCreateSelectionDialog: Widget -> string -> Arg list -> Widget

val XmSelectionBoxGetChild: Widget -> XmDefaultButtonType -> Widget

val XmIsSelectionBox: Widget -> bool

2.21 Text

Description:

The text widget provides both single and multi-line text editors with cut/copy/paste facilities. Use the XmNeditMode resource to choose single or multi-line editing. Use the function XmTextSetString to copy a string into the widget, and the function XmTextGetString to get it back again. Line breaks within multi-line strings are represented by "\n" characters.

Resources:

Functions:

datatype XmTextScanType = XmSELECT_POSITION | XmSELECT_WHITESPACE | XmSELECT_WORD | XmSELECT_LINE | XmSELECT_ALL | XmSELECT_PARAGRAPH

val XmCreateText: Widget-> string -> Arg list -> Widget
val XmCreateScrolledText: Widget-> string -> Arg list -> Widget

val XmTextGetString: Widget -> string
val XmTextSetString: Widget -> string unit
val XmTextSetInsertionPosition: Widget int -> unit

val XmIsText: Widget -> bool
val XmIsScrolledWindow: Widget -> bool

2.22 ToggleButton

Description:

A ToggleButton is used to display and set boolean or one-of-many states. When used for boolean states the ToggleButton uses a filled or empty square indicator to show the set or unset state. When used for one-of-many states the ToggleButton uses a filled or empty diamond to show the set and unset states. Pressing a boolean ToggleButton toggles the state from set to unset. Pressing one button in a RowColumn widget that has its XmNradioBehavior resource set to true, will set that button and unset all the others. In this case all the ToggleButtons automatically set their XmNindicatorType resource to XmONE_OF_MANY.

Resources:

Functions:

datatype XmIndicatorType = XmN_OF_MANY | XmONE_OF_MANY

val XmCreateToggleButton: Widget -> string -> Arg list -> Widget
val XmCreateToggleButtonGadget: Widget -> string -> Arg list -> Widget

val XmIsToggleButton: Widget -> bool
val XmIsToggleButtonGadget: Widget -> bool

2.23 WarningDialog

Description:

A WarningDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, and the warning icon which resembles an exclamation mark. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_WARNING: XmDialogType

val XmCreateWarningDialog: Widget -> string -> Arg list -> Widget

2.24 WorkingDialog

Description:

A WorkingDialog widget is a specific instance of a MessageBox widget. It has a message field, OK, Cancel and Help buttons, and the working icon which resembles an hourglass. The XmNmessageString resource is used to set the message string.

Resources:

Functions:

datatype XmAlignment = XmALIGNMENT_BEGINNING | XmALIGNMENT_CENTER | XmALIGNMENT_END

val XmDIALOG_WORKING: XmDialogType

val XmCreateWorkingDialog: Widget -> string -> Arg list -> Widget

Chapter 3

Resource Tables

The following type conversions are implicit in the Poly/ML implementation of the Motif library. Wherever it refers to the C type in publications about the Motif library the corresponding ML type is substituted.

Note that often the Motif documentation often incorrectly specifies the type Window instead of Widget when describing resource lists.

Note also that in the current implementation the type XmString is identical to string.

3.1 ApplicationShell

3.2 Composite

3.3 Core

3.4 Object

3.5 RectObj

3.6 Shell

3.7 TopLevelShell

3.8 TransientShell

3.9 VendorShell

3.10 WMShell

3.11 XmArrowButton

3.12 XmBulletinBoard

3.13 XmCascadeButton

3.14 XmCommand

3.15 XmDrawingArea

3.16 XmDrawnButton

3.17 XmFileSelectionBox

3.18 XmForm

3.19 XmFrame

3.20 XmGadget

3.21 XmLabel

3.22 XmList

3.23 XmMainWindow

3.24 XmManager

3.25 XmMenuShell

3.26 XmMessageBox

3.27 XmPanedWindow

3.28 XmPrimitive

3.29 XmPushButton

3.30 XmRowColumn

Note that XmNwhichButton is obsoleted by XmNmenuPost.

3.31 XmScale

3.32 XmScrollBar

3.33 XmScrolledWindow

3.34 XmSelectionBox

3.35 XmSeparator

3.36 XmText

Note that XmNvalue is already declared of type int in the resource tables for XmScale and XmScrollBar, and it cannot therefore appear in the table for XmText as a string. To access this value you have to use the functions XmTextSetString and XmTextGetString instead.

3.37 XmTextField

Note that XmNvalue is already declared of type int in the resource tables for XmScale and XmScrollBar, and it cannot therefore appear in the table for XmTextField as a string. To access this value you have to use the functions XmTextSetString and XmTextGetString instead.

3.38 XmToggleButton