Mrm functions and variables -- X Python Reference Manual

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

# 6.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)
  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)
  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])
  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)
  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.

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