[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Widget Writer's Guide

Providing UIL Access Through Three Small Files

Probably the simplest way to make your new widget accessible to UIL applications is to provide the following three files:

  1. A UIL creation header file

  2. An MRM initialization file

  3. A header file for the MRM initialization file

    Providing these files permits users to instantiate your new widget from their UIL applications.

    One important advantage of this mechanism is that it is portable. That is, the header file should work without modification on any UIL platform. One big disadvantage is that the UIL compiler will not be able to do complete data type checking on UIL applications.

    The following subsections detail these files and then explain how a UIL application can access them.

  4. The UIL Creation Header File

    The UIL creation header file specifies the names of the new widget(s) and new resources in a format that MRM will be able to read. Typically, you create one UIL creation header file that describes all the widgets that you have created. You can find a sample UIL creation header file for the Exm sample widget set in the demos/programs/Exm directory under the filename Exm.uil. Following are the contents of this file:

    !*  Exm.uil -  Exm widgets UIL creation header file
    !* Exm Creation API
    !* Exm Resources
        ExmNsimpleShape: private argument ('simpleShape', integer);
        ExmNcompoundString: private argument ('compoundString',
        ExmNgridMarginWidthWithinCell: private argument
        ExmNgridMarginHeightWithinCell: private argument
        ExmNopenSide: private argument ('openSide', integer);
        ExmNreportCallback: private argument ('reportCallback', callback);
        ExmNrubberBand: private argument ('rubberBand', boolean);
        ExmNcanvasWidth: private argument ('canvasWidth', integer);
        ExmNcanvasHeight: private argument ('canvasHeight', integer);
        ExmNsliderX: private argument ('sliderX', integer);
        ExmNsliderY: private argument ('sliderY', integer);
        ExmNsliderWidth: private argument ('sliderWidth', integer);
        ExmNsliderHeight: private argument ('sliderHeight', integer);

    The procedure section of the header file lists the convenience creation functions of all eight Exm widgets. The first value section describes the new resources of the Exm widgets. (Resource names already used in the Motif toolkit need not be listed in the value section.) The second value section associates numerical constants with the enumerated constants of the ExmNsimpleShape resource.

    If you decide to create your own WMD file, then you do not need to create the UIL creation header file.

    See the reference page for UIL(5X)for more information.

    MRM Initialization File

    Before a UIL application can use one of your new widgets, the widgets must be registered with the MRM. You register a widget by calling the MrmRegisterClass function. The easiest way to register a group of widgets is to pack all the MrmRegisterClass calls into one convenience function. For example, the MRM initialization file for all the Exm widgets is stored online in file demos/lib/Exm/ExmMrm.c. Following are its contents:

    #include <stdio.h>
    #include <Xm/Xm.h>
    #include <Mrm/MrmPublic.h>
    #include <Exm/Simple.h>
    #include <Exm/String.h>
    #include <Exm/StringTrans.h>
    #include <Exm/CommandB.h>
    #include <Exm/MenuB.h>
    #include <Exm/Grid.h>
    #include <Exm/TabB.h>
    #include <Exm/Panner.h>
     * ExmMrmInitialize - register Exm widget classes with Mrm
    int ExmMrmInitialize()
        MrmRegisterClass (MrmwcUnknown, "ExmSimple",
                            "ExmCreateSimple", ExmCreateSimple,
        MrmRegisterClass (MrmwcUnknown, "ExmString",
                            "ExmCreateString", ExmCreateString,
        MrmRegisterClass (MrmwcUnknown, "ExmStringTransfer",
        MrmRegisterClass (MrmwcUnknown, "ExmGrid",
                            "ExmCreateGrid", ExmCreateGrid,
        MrmRegisterClass (MrmwcUnknown, "ExmCommandButton",
        MrmRegisterClass (MrmwcUnknown, "ExmMenuButton",
                            "ExmCreateMenuButton", ExmCreateMenuButton,
        MrmRegisterClass (MrmwcUnknown, "ExmTabButton",
                            "ExmCreateTabButton", ExmCreateTabButton,
        MrmRegisterClass (MrmwcUnknown, "ExmPanner",
                            "ExmCreatePanner", ExmCreatePanner,
        return (0);

    This file includes the widget public header files of all eight Exm widgets.

    Creating an MRM initialization file is not a requirement; it is only a convenience for UIL applications programmers. The only requirement for a UIL application is that MrmRegisterClass gets called for each new widget.

    Header File for the MRM Initialization File

    If you create an MRM initialization file, then you should also create a header file for it. The header file will provide a convenient handle for UIL applications programs to access your MRM initialization file. We provide such a header file in file ExmMrm.h. The only code in the file is as follows :

    int ExmMrmInitialize(void);

    Accessing Widgets from a UIL Application

    After creating the three files described earlier in this section, UIL applications programs can access the new widgets. We provide a sample UIL application in the directory demos/programs/Exm/app_in_uil. This code looks very much like any other UIL application. In fact, there are only two differences between this UIL application and a UIL application that uses the standard Motif widget set.

    First, the UIL application must include the UIL creation header file; for example:

    include file ("Exm.uil");

    Second, the UIL callback file must invoke the registration function defined in the MRM initialization file. To make this work, the UIL callback file must also include the appropriate header file. For example, the UIL callback file app_in_uil.c contains the following code:

    #include <ExmMrm.h>
    MrmInitialize ();  /* standard Motif widget set */
    ExmMrmInitialize(); /* Exm widget set */

    [ Previous | Next | Contents | Glossary | Home | Search ]