Next: Callback models Prev: Mrm Up: Mrm Top: Top

5.1. Mrm functions and variables

Written by Bob Novas, Century Computing, Inc., updated and converted to LaTeX by Sjoerd Mullender.

The Motif Resource Manager (Mrm) and the User Interface Language (UIL) provide a convenient, standard interface to many commercial GUI-builders. UIL describes the static initial state of a user interface for a widget based application. A UIL module describes a widget hierarchy, the resources of the widgets in the hierarchy, and the callbacks of those widgets. Mrm provides programmatic access to UIL-module definitions.

One powerful feature provided by this Mrm binding is the ability for an interface designer to create an interface using a GUI-builder, bind the UIL-defined interface to (existing) Python functions, and produce a functional GUI program without having to write code (or, at least, not much). We believe that this capability can be used to quickly prototype applications; and, that use of these prototypes operationally is not out of the question.

The Mrm binding is in module Mrm. As usual, you must import Mrm to use the Mrm functions.

The Mrm module defines the following function:

OpenHierarchy (filename_or_filename_list) -- function of module Mrm

Returns mrm_hierarchy_object. This function corresponds with MrmOpenHierarchy.

This Python function allocates a Mrm ID and opens all the UID files named. A single file name or a list of file names may be passed. This function returns an mrmhierarchyobject that can be used to fetch widget trees from the hierarchy. The function also registers the function PyEval(string) (see below) with Mrm for the hierarchy. The function must be called before calling any other Mrm module function but after calling Xt.Initialize().

Examples of using this function are:

    import Xt, Mrm

    toplev = Xt.Initialize()    # must be called first

    mrm_hier1 = Mrm.OpenHierarchy("file-1.uid")

    mrm_hier2 = Mrm.OpenHierarchy(["file-1.uid","f2.uid"])

A .uid file is the output of the UIL compiler, which is typically invoked:

uil file-1.uil -o file-1.uid

A Python run-time exception is invoked if the uid file cannot be found.

The mrm_hierarchy_object has the following methods:

FetchWidget (index, parent_widget) -- Method on MrmHierachy object

Returns widget. This function corresponds with MrmFetchWidget.

This Python function fetches the UIL-object named index and its children from the mrm_hierarchy object and creates these widgets in a widget-tree under parent_widget. FetchWidget returns the UIL-object named index wrapped as a Python widget object. Widgets that are children of index are created but are not wrapped as Python widget objects. None of the widgets created are managed.

The following Python code snippet shows the use of the FetchWidget method and also shows how to obtain a child widget of index as a Python widget object by using the widget NameToWidget method.

    top_level = Xt.Initialize()
    mrm_hier = Mrm.OpenHierarchy("panel_cp.uid")

    main_w = mrm_hier.FetchWidget("main", top_level)

    child_w = main_w.NameToWidget("child-widget-name")

"child-widget-name" is the partially qualified name of the desired widget child of main_w; see XtNameToWidget() for details. Usually the simple widget name can be prefixed with an asterisk to fetch the appropriate widget even if it is not the immediate child of the main widget.

PyRegister (function_object, argument_type[, function_name]) -- Method on MrmHierachy object

Returns None. This function corresponds more-or-less with MrmRegisterNamesInHierarchy.

This Python function registers the Python function function_object with Mrm so that the Python function function_object can be declared as a callback function in UIL. argument_type is a string that declares the type of the client argument to function_object. The only types currently supported are "integer", "string", and "widget".

function_object must be declared in Python with three arguments, which correspond to the standard callback widget, clientdata and calldata arguments. argument_type causes the clientdata argument passed to function_object to be wrapped as a Python integer, string or widget object.

By default, PyRegister registers the name of the Python function with Mrm as the UIL-declarable callback function. An optional third string argument to PyRegister can be used to explicitly specify the UIL-declarable callback name registered with Mrm.

Currently, the internal implementation of PyRegister is ugly and only supports registering 250 routines.

There is one UIL-declarable function:

PyEval (string) -- UIL-declarable function

This UIL-declarable-function is a Mrm-registered callback function that accepts a string argument that it evaluates in the context of the Python __main__ module. PyEval is for use in UIL, not in Python code. Any non-indented Python code is legal as the string argument; semi-colons can be used to construct a multi-statement argument. Beware of spaces, which are significant. The string argument originates in the uil file as the tag argument to the PyEval function.

An example of using PyEval in UIL code is:

    procedure PyEval(string);
    ...

    XmNactivateCallback = procedure PyEval("MyPrint(g_var)");

Before evaluating the string argument, PyEval adds two special symbols to the namespace of the Python __main__ module. __widget__ is the widget argument to the actual Mrm-registered PyEval callback function wrapped as a Python widget object. __calldata__ is the calldata argument to this function wrapped as a Python callback object.