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

Virtual Keysyms

Xlib and the Intrinsics provide a level of mapping between physical keys and keysyms. Motif adds one more level of mapping on top of keysyms; Motif can map keysyms to virtual keysyms. Table 7-1 describes the purpose of some common Motif virtual keysyms.

Table 9. Purpose of Common Motif Virtual Keysyms

Virtual Keysyms Purpose
osfActivate Activates a default action
osfAddMode Toggles the selection mode between Normal and Add mode
osfBackSpace Deletes the previous character
osfBeginLine Moves the cursor to the beginning of the line
osfCancel Cancels the current operation
osfClear Clears the current selection
osfCopy Copies to the clipboard
osfCut Cuts to the clipboard
osfDelete Deletes data
osfDeselectAll Deselects the current selection
osfDown Moves the cursor down
osfEndLine Moves the cursor to the end of the line
osfHelp Calls the function specified by the XmNhelpCallback resource
osfInsert Toggles between Replace and Insert mode (if specified without modifiers)
osfLeft Moves the cursor left
osfMenu Activates the Popup Menu
osfMenuBar Traverses to the MenuBar
osfPageDown Moves down one page
osfPageLeft Moves left one page
osfPageRight Moves right one page
osfPageUp Moves up one page
osfPaste Pastes from the clipboard
osfPrimaryPaste Pastes the primary selection
osfRestore Restores a previous setting
osfRight Moves the cursor right
osfSelect Establishes the current selection
osfSelectAll Selects an entire block of data
osfSwitchDirection Toggles the string layout direction
osfUndo Undoes the most recent action
osfUp Moves the cursor up

We recommend that the translations string of Motif widgets use Motif virtual keysyms instead of traditional keysyms whenever possible. For example, the following well-defined translations string uses five different Motif virtual keysyms:

static char defaultTranslations[] = "\
:<Key>osfActivate:      PrimitiveParentActivate()\n\
:<Key>osfCancel:        PrimitiveParentCancel()\n\
:<Key>osfHelp:          PrimitiveHelp()\n\
:<Key>osfDelete:            MyDeletionMethod()\n\
:<Key>osfInsert:            MyInsertionMethod()\n\

Virtual keysyms let your widget provide consistent behavior across a wide variety of keyboards. (For more information on virtual keysyms, refer to the Motif Style Guide and to the VirtualBindings reference page of the Motif Programmer's Reference.)

The following subsections take a closer look at some commonly used bindings for certain virtual keysyms.

The osfActivate and osfCancel Virtual Keysyms

The PrimitiveParentActivate action is ordinarily bound to the osfActivate virtual keysym. The PrimitiveParentCancel action is ordinarily bound to the osfCancel virtual keysym.

When activated, the PrimitiveParentActivate action routine typically does the following:

  1. Examines the value of the XmNdefaultButton resource in the managing widget. This resource holds the widget ID of one of the widgets that it is managing.

  2. Invokes the arm_and_activate method of the widget named by XmNdefaultButton.

    In other words, the ultimate responsibility for handling the PrimitiveParentActivate action belongs to the widget named by XmNdefaultButton.

    The PrimitiveParentCancel action routine works like PrimitiveParentActivate. The only difference is that PrimitiveParentCancel depends on the XmNcancelButton resource rather than XmNdefaultButton.

    (See Chapter 4 for more details on the parent_process method.)

  3. The osfHelp Virtual Keysym

    You may associate any action routine with the osfHelp virtual keysym. One interesting choice of an action routine is PrimitiveHelp.

    Specifying PrimitiveHelp causes Motif to invoke the callback associated with the widget's XmNhelpCallback resource. It is quite possible, however, that your widget does not define such a callback. In that case, PrimitiveHelp looks for a help callback inside the widget that is managing your widget.

    For example, the ExmString widget binds the PrimitiveHelp action to the osfHelp virtual keysym. Suppose that an XmForm widget is managing several ExmString widgets. Furthermore, suppose that none of the ExmString widgets define a help callback. In this case, PrimitiveHelp automatically tries to find a help callback inside the XmForm widget. Therefore, the help callback of XmForm can serve as the help callback for all the widgets that it manages. If the XmForm widget does not define a help callback, then Motif looks for a help callback in the widget that manages the XmForm widget. Motif keeps going up the parent chain until it finds a help callback.

    The osfMenuBar and osfMenu Virtual Keysyms

    You may associate any action with the virtual keysyms osfMenuBar and osfMenu; however, there is a good possibility that Motif will never execute the action you specify.

    If your application defines a menu bar, the menu bar will grab any osfMenuBar events before your widget can process it. Similarly, if your application defines any popup menus, the popup menu widget will grab any osfMenu events before your widget can process it.

    The osfBeginLine, osfEndLine, osfLeft, osfRight, osfUp, and osfDown Virtual Keysyms

    You should be very careful about defining any of the following virtual keysyms inside the tm_table string of the CoreClassPart:

    1. osfBeginLine

    2. osfEndLine

    3. osfLeft

    4. osfRight

    5. osfUp

    6. osfDown

      As we mentioned earlier in this chapter, the translations field of the PrimitiveClassPart takes precedence over the tm_table field of the CoreClassPart. The PrimitiveClassPart of XmPrimitive defines actions for all six of the preceding virtual keysyms. Therefore, if your widget inherits these translations (by specifying XtInheritTranslations), then Motif will ignore any translations defined for these virtual keysyms in the tm_table field. Therefore, if you really do want to provide a non-default binding for any of these virtual keysyms, you should set the translations field of the PrimitiveClassPart to either NULL or to the name of a new translations string. Another possibility is to update the translations string as part of your widget's initialize method.

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