4. Managing the Virtual Bindings

The virtual binding mechanism in VirtKeys.c provides four additional (``undocumented'') functions to mess with:

_XmVirtualToActualKeysym_XmVirtKeysInitialize_XmVirtKeysLoadFileBindings_XmVirtKeysLoadFallbackBin-
dings

void _XmVirtualToActualKeysym(Display *Dsp, KeySym VirtualKeysym,
                              KeySym *RealKeysymReturn,
                              Modifiers *ModifierReturn);
void _XmVirtKeysInitialize(Widget w);
Boolean _XmVirtKeysLoadFileBindings(String filename, String *binding);
int _XmVirtKeysLoadFallbackBindings(Display *Dsp, String *Bindings);

These four functions are available with M*TIF as well as with LESSTIF. With _XmVirtualToActualKeysym() you can check how a virtual keysym would look like in real life. You also get back from the function the necessary modifiers which must be active in order to convert the real keysym into a CSF keysym.

The contents of a file can be loaded into memory by means of the _XmVirtKeysLoadFileBindings() function. The memory needed to hold the contents is allocated by the function and must be freed when it's not needed any more. If the function fails for any reason (file not found, not enough memory available) _XmVirtKeysLoadFileBindings() returns False.

If for any reason you need to set up the _MOTIF_DEFAULT_BINDINGS property of the root window of a given display, you can use _XmVirtKeysLoadFallbackBindings() for this task. If applicable, the function will load a vendor-specific set of virtual bindings. Otherwise it will fall back to a generic set of virtual bindings. _XmVirtKeysLoadFallbackBindings() returns in the parameter Bindings the current set of virtual bindings. You are responsible for freeing the string with XtFree() when you don't need it any longer. The most interesting use of this function is within the xmbind client. If no binding file is specified and there is no .motifbind file available, then xmbind can install the default fallback bindings in the _MOTIF_DEFAULT_BINDINGS property. More on this in the next section.

You will hardly need to call _XmVirtKeysInitialize(), as this sets up the virtual bindings on a XmDisplay widget. It gets automatically called during the initialising phase of this kind of widget. This function is solely for use within the LESSTIF modules VirtKeys.c and Display.c.