Xmp(1)

NAME
Xmp - Motif Public Library

SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/Wc/WcCreate.h>
#include <X11/Xmp/Xmp.h>
/* All Wcl applications should provide at least the Wcl options:
*/
static XrmOptionDescRec options[] = {
    ... application specific command line options ...
    WCL_XRM_OPTIONS
};
main ( argc, argv )
    int    argc;
    char*  argv[];
{
    /*  -- Intialize Toolkit creating the application shell
    */
    Widget appShell = XtInitialize (
        argv[0], WcAppClass( argc, argv ),      /* app name & class  */
        options, XtNumber(options),             /* argv option descr */
        &argc, argv
    );
    XtAppContext app = XtWidgetToApplicationContext(appShell);
    /*  -- Register application specific callbacks and widget classes
    */
    RegisterApplication ( app );
    /*  -- Register all widget classes and constructors
    */
    XmpRegisterMotif( app );
    /*  -- Create widget tree below toplevel shell using Xrm database
    */
    if ( WcWidgetCreation ( appShell ) )
        exit(1);
    /*  -- Realize the widget tree
    */
    XtRealizeWidget ( appShell );
    /*  -- Catch `Close' from mwm menu on top level shell.
    */
    XmpAddMwmCloseCallback( appShell, DeleteWindowCB, clientData );
    /*  -- and finally, enter the main application loop
    */
    XtMainLoop ( );
}

LINK BY
    example% ld -o prog prog.o -lXmp -lXm -lWc <dynLinkLib> -lXmu -lXt -lX11

On SunOS or SVR4 machines, the <dynLinkLib> is named -ldl.
Other architectures cannot use the dynamic linking capabilites of
Wcl, and therefore do not need any dynamic link library.

DESCRIPTION

Xmp is intended to be used with Wcl and the Motif widget set. Xmp provides a procedure for registering all Motif widgets, and convenience functions frequently needed by Motif applications.

REGISTRATION PROCEDURES

Wcl must be told the names of all widgets and widget constructors before it can create widgets as specified in the resource file of client applications. Xmp provides a registration procedure for registering all Motif widgets. For backward compatibility with previous releases of Wcl, this registration procedure has three names: MriRegisterMotif(), XmpRegisterAll(), and XmpRegisterMotif(). These procedures are exactly equivalent.

void XmpRegisterMotif( XtAppContext )
    This procedure registers all of the Motif widget class pointer names, widget class names, and widget constructor function names with Wcl. It also registers all Xmp converters and action procedures with Xt, and all Xmp callback procedures with Wcl.

CONVERTERS

Xmp provides converters which are useful for specifying look and feel attributes of Motif user interfaces from resource files. It causes the WcCvtStringToWidget() converter to be invoked for setting constraints and menuIds. WcCvtStringToWidget() uses WcFullNameToWidget() to resolve the name, so the Wcl relative path naming conventions can be used to navigate the widget tree to find a specific widget.

Xmp causes the XmpCvtStringToXmString() converter to be invoked to provide multi-line labels to Motif widgets. This converter uses XmStringCreateLtoR() and the XmSTRING_DEFAULT_CHARSET to convert strings in the resource database into XmStrings. XmStringCreateLtoR() recognizes the two characters " (backslash followed by a lower case "n"), and causes the XmString to break to a new line. Hence, "Hellohere" ends up being a two line label on an XmLabel.

ACTIONS AND CALLBACKS

Most Xmp actions are available as callbacks, and all callbacks are available as actions. The provided procedures, as named in the resource database, are as follows:
XmpFixTranslations( widget [widget ...] )
XmpAddMwmCloseCallback( widget callback(args) [callback(args) ...] )
XmpAddTabGroup( [widget] )
XmpTableChildConfig( widget col row [h_span [v_span [opts]]] )
XmpTableChildPosition( widget col row )
XmpTableChildResize( widget h_span v_span )
XmpTableChildOptions( widget options )
XmpPopup( widget )

Each callback procedure can also be named in resource files as the name of the procedure followed by CB: i.e, XmpFixTranslations() can also be invoked as a callback by giving the name XmpFixTranslationsCB() for a callback resource value. Also, each action procedure can also be named by appending ACT to the procedure name. Normally, I just use the procedure name, so it is less trouble to change behavior from callbacks to actions triggered by translations or accelerators, and vice versa. The CB and ACT endings are maintained for backward compatibility, and because some people like to be more explicit. It is all a matter of taste.

Arguments to the procedures are provided as strings, the characters between the parenthesis following the procedure name. If no parenthesis follow the procedure name, then a NULL string is passed to the procedure. Some procedures require arguments, some provide reasonable defaults when no arguments are given. For example:
    *foo.wcCreate:         XmText
    *foo.wcCallback:       XmpFixTranslations( this ^that )
    *bar.wcCreate:         XmPushButton
    *bar.activateCallback: XmpAddTabGroup

Each
Xmp
procedure is discussed in detail below.

XmpFixTranslations( widget [widget ...] )
    This works on XmText widgets only, and has the effect of fixing
    translations which get hammered when XmText widgets are put into
    dialogs.  Normally, pressing newline in a multi-line text widget
    does a newline action.  In a dialog, pressing return causes the
    dialog to go away.

XmpAddMwmCloseCallback( widget callback(args) [callback(args) ...] )
    The callbacks are invoked in an Xt dependent order when the named widget
    receives the WM_DELETE_WINDOW or WM_SAVE_YOURSELF protocol event.  Each
    of the named callbacks are added to the widget using XmAddProtocolCallback().

XmpAddTabGroup( [widget] )
    The named widget, or the widget providing the context for the callback if
    no widget is named, is passed to XmAddTabGroup().  The effect is simple:
    if the widget is a manager widget, then all the children are put in a
    tab group together.  If the widget is a primitive, then that widget
    is in its own tab group.

XmpPopup( widget )
    This is only available as an action triggered due to translations of
    accelerators, it cannot be invoked as a callback.  The argument is the
    name of a menu pane (usually, a widget which was created with
    XmCreatePopupMenu()).  The menu is positioned using XmMenuPosition()
    which is the same procedure used by Motif itself.  This depends on
    the existance of an XmRowColumn somewhere in the interface.  If
    you have a menuBar, then this will work.  This is because XmRowColumn
    provides all sorts of wierd and wonderful event handlers for dealing
    with menus.

XmpTableChildConfig( w col row [h_span [v_span [opts]]] )
    This allows a child of an XmpTable to be moved to a new row or
    column, to be given a different horizontal or vertical span, and
    to change the justification and re-size options of the child.

XmpTableChildPosition( w col row )
    This allows a child of an XmpTable to be moved to a new row or
    column.

XmpTableChildResize( w h_span v_span )
    This allows a child of an XmpTable to be given a different horizontal
    or vertical span.

XmpTableChildOptions( w options )
    This allows a child of an XmpTable to be given new
    justification and re-size options.

SEE ALSO
XmpTable(3), Mri(1), Wcl(3), X(1)

BUGS

realizeCallback, destroyCallback, popupCallback, and popdownCallback MUST NOT be specified using resource values for shell widgets derived from Motif Vendor Shell in most releases of Motif. Sorry, there is no way I can see for Wcl to work around this bug in the list of resources fetched by the Motif Vendor Shell Extension VendorExtInitialize() procedure.

If you want to specify these resources, specifiy a wcCallback resource and add the callbacks using WcAddCallbacks().

Explanation for Xt and Motif gurus with source code: Xt has fetched these resources for the shell, and compiled the XtCallbackRec array generated by WcCvtStringToCallback into the InternalCallbackRec/XtCallbackRec "thang." This happens in Xt'Create.c'_XtCreate in R5. _XtCreate then allows the widget to initialize itself, calling CallInitialize(). This eventually invokes the Motif Vendor Shell initialization, which invokes the Motif Vendor Shell Extension initialization. Here, Motif incorrectly fetches again the above callback resources, applying the resources straight into the "new" widget with its already compiled callback lists. This causes the compiled callback list storage to be overwritten with the original, uncompiled form previously generated by WcCvtStringToCallback. The next XtAddCallback or XtCallAllCallbacks or XtSetValues on these resources will (or should!) fail due to mis-interpreting the callback list (the first element will again be an XtCallbackRec instead of an InternalCallbackRec). The fix is messy: somehow treat the callback resources as uniquely as Xt does everywhere else: fetch into a different (local) Widget instead of new, and then traverse the list of callbacks, invoking XtAddCallback( new, <callbackName>, cb->callback, cb->closure ), and then free up that locally allocated dummy widget. Yuck!

AUTHOR
David E. Smyth (David.Smyth@sniap.mchp.sni.de) at Siemens Nixdorf Informationssysteme AG, Munich Germany.