NAMES

OlClassSearchIEDB, OlClassSearchTextDB, OlCreateInputEventDB, OlLookupInputEvent, OlWidgetSearchIEDB, OlWidgetSearchTextDB

SYNOPSIS AND DESCRIPTION

Applications developers should avoid using these functions, since the virtual event mechanism will be replaced with a completely translation manager-based solution in a future release. 

Note:

For all functions discussed here the registration order determines the search order when doing a lookup. 

OlClassSearchIEDB

Synopsis:

#include <Xol/OpenLook.h>
 . . .
voidOlClassSearchIEDB(

WidgetClass wc;
OlVirtualEventTable db);

The OlClassSearchIEDB procedure is used to register a given database on a specific widget class. The db value was returned from a call to OlCreateInputEventDB(). 

Once a database is registered with a given widget class, the OlLookupInputEvent() procedure (if db_flag is OL_DEFAULT_IE or db) will include this database in the search stack if the given widget id is a subclass of this widget class. 

EXAMPLE

/∗ To create a client application database ∗/
#include <Xol/OpenLook.h>
#include <Xol/Stub.h>
     /∗ start with a big value to avoid ∗/
     /∗ the "virtual_name" collision    ∗/
#define OL_MY_BASE            1000
#define OL_MY_DRAWLINEBTN     OL_MY_BASE+0
#define OL_MY_DRAWARCBTN      OL_MY_BASE+1
#define OL_MY_REDISPLAYKEY    OL_MY_BASE+2
#define OL_MY_SAVEPARTKEY     OL_MY_BASE+3
 #define XtNmyDrawLineBtn      "myDrawLineBtn"
#define XtNmyDrawArcBtn       "myDrawArcBtn"
#define XtNmyRedisplayKey     "myRedisplayKey"
#define XtNmySavePartKey      "mySavePartKey"
 static OlKeyOrBtnRec     OlMyBtnInfo[] = {
     /∗name         default_value    virtual_name        ∗/
      { XtNmyDrawLineBtn,  "c<Button1>",       OL_MY_DRAWLINEBTN  },
     { XtNmyDrawArcBtn,   "s<myDrawLineBtn>", OL_MY_DRAWARCBTN   },
};
 static OlKeyOrBtnRec     OlMyKeyInfo[] = {
     /∗name               default_value      virtual_name        ∗/
      { XtNmyRedisplayKey, "c<F5>",           OL_MY_REDISPLAYKEY },
     { XtNmySavePartKey,  "c<F5>",           OL_MY_SAVEPARTKEY  },
};
 static OlVirtualEventTable     OlMyDB;
 OlMyDB = OlCreateInputEventDB(
               w,
               OlMyKeyInfo, XtNumber(OlMyKeyInfo),
               OlMyBtnInfo, XtNumber(OlMyBtnInfo)
     );
     /∗ assume: all stub widgets are interested in OlMyDB ∗/
OlClassSearchIEDB(stubWidgetClass, OlMyDB);
     /∗ once this step is done, all stub widget instances ∗/
     /∗ will receive the OlMyDB commands after a call to  ∗/
     /∗ OlLookupInputEvent(), or in the XtNconsumeEvent   ∗/
     /∗ callback’s OlVirtualEvent structure supplied with ∗/
     /∗ the call_data field.                              ∗/
 

OlClassSearchTextDB

Synopsis:

#include <Xol/OpenLook.h>
 . . .
voidOlClassSearchTextDB(

WidgetClasswc);

The OlClassSearchTextDB procedure is used to register the OPEN LOOK TEXT database on a specific widget class. 

Once the OPEN LOOK TEXT database is registered with a given widget class, the OlLookupInputEvent() procedure (if db_flag is OL_DEFAULT_IE or OL_TEXT_IE) will include this database in the search stack if the given widget id is a subclass of this widget class. 

EXAMPLE

    ...
#include <Xol/OpenLook.h>
#include <Xol/Stub.h>
    ...
      /∗ assume: all stub widgets are interested in the    ∗/
     /∗          OPEN LOOK TEXT database                  ∗/
OlClassSearchTextDB(stubWidgetClass);
     /∗ once this step is done, all stub widget instances ∗/
     /∗ will receive OPEN LOOK TEXT commands after a      ∗/
     /∗ call to OlLookupInputEvent(), or in the           ∗/
     /∗ XtNconsumeEvent callback’s OlVirtualEvent         ∗/
     /∗ structure supplied with the call_data field.      ∗/
   ...

OlCreateInputEventDB

Synopsis:

#include <Xol/OpenLook.h>
 . . .
OlVirtualEventTableOlCreateInputEventDB(

Widget w,
OlKeyOrBtnInfo key_info,
int num_key_info,
OlKeyBtnInfo btn_info,
int num_btn_info);

The OlCreateInputEventDB function is used to create a client specific Key and/or Button database. This function returns a database pointer if the call to this function is successful otherwise a NULL pointer is returned. 

Mapping for a new virtual command can be composed from the mappings of a previously defined virtual command. 

The returned value from this function is an opaque pointer (
 
OlVirtualEventTable).  A client application should use this pointer when registering and/or looking up this database. 

typedef struct _OlVirtualEventInfo ∗OlVirtualEventTable;

The key_info and btn_info parameters are a pointer to an OlKeyOrBtnRec structure. 

typedef struct {
Stringname;
Stringdefault_value; /∗ "," separate string ∗/
OlVirtualNamevirtual_name;
} OlKeyOrBtnRec, ∗OlKeyOrBtnInfo;

Caveat

A client application can create a Key–only database by having the NULL btn_info. The same applies to a Button only database.

Each virtual command can have two different bindings because the OPEN LOOK toolkit allows the alternate key or button sequence. 

The OPEN LOOK toolkit already has a set of predefined OPEN LOOK virtual names. It is important that the virtual_name value of a client application database starts with a big value to avoid the virtual_name collision.

EXAMPLE

     /∗ To create a client application database ∗/
     ...
#include <Xol/OpenLook.h>
     ...
     /∗ start with a big value to avoid ∗/
     /∗ the "virtual_name" collision    ∗/
#define OL_MY_BASE            1000
#define OL_MY_DRAWLINEBTN     OL_MY_BASE+0
#define OL_MY_DRAWARCBTN      OL_MY_BASE+1
#define OL_MY_REDISPLAYKEY    OL_MY_BASE+2
#define OL_MY_SAVEPARTKEY     OL_MY_BASE+3
 #define XtNmyDrawLineBtn     "myDrawLineBtn"
#define XtNmyDrawArcBtn      "myDrawArcBtn"
#define XtNmyRedisplayKey    "myRedisplayKey"
#define XtNmySavePartKey     "mySavePartKey"
 static OlKeyOrBtnRec     OlMyBtnInfo[] = {
     /∗name             default_value      virtual_name        ∗/
      { XtNmyDrawLineBtn,  "c<Button1>",       OL_MY_DRAWLINEBTN  },
     { XtNmyDrawArcBtn,   "s<myDrawLineBtn>", OL_MY_DRAWARCBTN   },
};
 static OlKeyOrBtnRec     OlMyKeyInfo[] = {
     /∗name               default_value      virtual_name        ∗/
      { XtNmyRedisplayKey, "c<F5>",           OL_MY_REDISPLAYKEY },
     { XtNmySavePartKey,  "c<F5>",           OL_MY_SAVEPARTKEY  },
};
 static OlVirtualEventTable     OlMyDB;
       ...
OlMyDB = OlCreateInputEventDB(
               w,
               OlMyKeyInfo, XtNumber(OlMyKeyInfo),
               OlMyBtnInfo, XtNumber(OlMyBtnInfo)
     );
    ...

OlLookupInputEvent

Synopsis:

#include <Xol/OpenLook.h>
 . . .
OlVirtualEventTableOlLookupInputEvent(

Widget w,
XEvent ∗xevent,
OlVirtualEvent virtual_event_ret,
XtPointer db_flag);

The OlLookupInputEvent procedure is used to translate a X event to an OPEN LOOK virtual event. The X event ( xevent) could be a KeyPress, ButtonPress, ButtonRelease, EnterNotify, or event. The procedure attempts to translate this event based on the setting of the OPEN LOOK defined dynamic databases. 

The virtual_event_ret parameter is a pointer to an OlVirtualEventRec structure:

typedef struct {
     Boolean         consumed;
     XEvent ∗        xevent;
Modifiers       dont_care;
     OlVirtualName   virtual_name;
     KeySym          keysym;
     String          buffer;
     Cardinal     length;
     Cardinal        item_index;
} OlVirtualEventRec, ∗OlVirtualEvent;

(Note that this structure is also used by the callbacks to the XtNconsumeEvent resource.) 

If the X event is a KeyPress, the keysym, buffer, and length information will be included in virtual_event_ret.  The information was returned from a call to XLookupString(). 

The db_flag parameter is an XtPointer type.  The valid values are OL_DEFAULT_IE, or the return value from a OlCreateInputEventDB() call. 

The ( w, db_flag) pair determines the searching database(s). If the db_flag value is not OL_DEFAULT_IE then only the given database (for example, OL_TEXT_IE means: search the OPEN LOOK TEXT database) will be searched, otherwise a search stack will be built. This stack is based on the widget information (w) and the registering order to determine the searching database(s). Once this stack is built, the procedure searches in a LIFO (Last In First Out) manner. 

All widgets have an XtNconsumeEvent callback.  When this callback is called, the call_data field is a pointer to an OlVirtualEventRec structure which is filled in with the results of calling with the db_flag set to OL_DEFAULT_IE. 

Virtual Event Databases

The following abbreviations are used to shorten the “Default Bindings” column of the two tables that follow. 

  Table 1 Virtual Event Abbreviations

     Key           Abbreviation
     Alt key       a
     Ctrl key      c
     no modifier   n
     Shift key     s

  Table 2 Core Virtual Event Key Bindings

                                Core Database (OL_CORE_IE)
Command Name      Virtual Expression   Virtual Event        Default Binding
ADJUST            adjustBtn            OL_ADJUST            n<Button2>
ADJUSTKEY         adjustKey            OL_ADJUSTKEY         a<Insert>
CANCEL            cancelKey            OL_CANCEL            n<Escape>
CONSTRAIN         constrainBtn         OL_CONSTRAIN         c<Button1>
COPY              copyKey              OL_COPY              n<F16>
CUT               cutKey               OL_CUT               n<F20>
DEFAULTACTION     defaultActionKey     OL_DEFAULTACTION     <Return>,c<Return>
DRAG              dragKey              OL_DRAG              n<F5>
DROP              dropKey              OL_DROP              n<F2>
DUPLICATE         duplicateBtn         OL_DUPLICATE         s<Button1>
DUPLICATEKEY      duplicateKey         OL_DUPLICATEKEY      s<space>
HELP              helpKey              OL_HELP              n<Help>
HSBMENU           horizSBMenuKey       OL_HSBMENU           a<h>
MENU              menuBtn              OL_MENU              n<Button3>
MENUDEFAULT       menuDefaultBtn       OL_MENUDEFAULT       s<Button3>
MENUDEFAULTKEY    menuDefaultKey       OL_MENUDEFAULTKEY    c<space>
MENUKEY           menuKey              OL_MENUKEY           a<space>
MOVEDOWN          downKey              OL_MOVEDOWN          <Down>
MOVELEFT          leftKey              OL_MOVELEFT          <Left>
MOVERIGHT         rightKey             OL_MOVERIGHT         <Right>
MOVEUP            upKey                OL_MOVEUP            <Up>
MULTIDOWN         multiDownKey         OL_MULTIDOWN         c<Down>
MULTILEFT         multiLeftKey         OL_MULTILEFT         c<Left>
MULTIRIGHT        multiRightKey        OL_MULTIRIGHT        c<Right>
MULTIUP           multiUpKey           OL_MULTIUP           c<Up>
NEXTAPP           nextAppKey           OL_NEXTAPP           a<n>
NEXTWINDOW        nextWinKey           OL_NEXTWINDOW        a<w>
PAGEDOWN          pageDownKey          OL_PAGEDOWN          a<R15>
PAGELEFT          pageLeftKey          OL_PAGELEFT          a c<R9>
PAGERIGHT         pageRightKey         OL_PAGERIGHT         a c<R15>
PAGEUP            pageUpKey            OL_PAGEUP            a<R9>
PAN               panBtn               OL_PAN               a<Button1>
PASTE             pasteKey             OL_PASTE             n<F18>
PREVAPP           prevAppKey           OL_PREVAPP           a s<n>
PREV_FIELD        prevFieldKey         OL_PREV_FIELD        s<Tab>,c s<Tab>
PROPERTY          propertiesKey        OL_PROPERTY          n<F13>
SCROLLBOTTOM      scrollBottomKey      OL_SCROLLBOTTOM      a c<R13>
SCROLLDOWN        scrollDownKey        OL_SCROLLDOWN        a<Down>
SCROLLLEFT        scrollLeftKey        OL_SCROLLLEFT        a<Left>
SCROLLLEFTEDGE    scrollLeftEdgeKey    OL_SCROLLLEFTEDGE    a <R7>
SCROLLRIGHT       scrollRightKey       OL_SCROLLRIGHT       a<Right>
SCROLLRIGHTEDGE   scrollRightEdgeKey   OL_SCROLLRIGHTEDGE   a <R13>
SCROLLTOP         scrollTopKey         OL_SCROLLTOP         a c<R7>
SCROLLUP          scrollUpKey          OL_SCROLLUP          a<up>
SELCHARBAK        selCharBakKey        OL_SELCHARBAK        s<Left>
SELCHARFWD        selCharFwdKey        OL_SELCHARFWD        s<Right>
SELECT            selectBtn            OL_SELECT            n<Button1>
SELECTKEY         selectKey            OL_SELECTKEY         n<space>
SELFLIPENDS       selFlipEndsKey       OL_SELFLIPENDS       a<Insert>
SELLINE           selLineKey           OL_SELLINE           c a<Left>
SELLINEBAK        selLineBakKey        OL_SELLINEBAK        s<R7>
SELLINEFWD        selLineFwdKey        OL_SELLINEFWD        s<R13>
SELWORDBAK        selWordBakKey        OL_SELWORDBAK        c s<Left>
SELWORDFWD        selWordFwdKey        OL_SELWORDFWD        c s<Right>
STOP              stopKey              OL_STOP              n<F11>
TOGGLEPUSHPIN     togglePushpinKey     OL_TOGGLEPUSHPIN     c<t>
UNDO              undoKey              OL_UNDO              n<F14>
VSBMENU           vertSBMenuKey        OL_VSBMENU           a<v>
WINDOWMENU        windowMenuKey        OL_WINDOWMENU        a<m>
WORKSPACEMENU     workspaceMenuKey     OL_WORKSPACEMENU     a s<m>
                             Text Database (OL_TEXT_IE)
Command Name   Virtual Expression   Virtual Event   Default Button
CHARBAK        charBakKey           OL_CHARBAK      <Left>
CHARFWD        charFwdKey           OL_CHARFWD      <Right>
DELCHARBAK     delCharBakKey        OL_DELCHARBAK   <BackSpace>,<Delete>
DELCHARFWD     delCharFwdKey        OL_DELCHARFWD   s<BackSpace>,s<Delete>
DELLINE        delLineKey           OL_DELLINE      m<BackSpace>,m<Delete>
DELLINEBAK     delLineBakKey        OL_DELLINEBAK   c<BackSpace>
DELLINEFWD     delLineFwdKey        OL_DELLINEFWD   c<Delete>
DELWORDBAK     delWordBakKey        OL_DELWORDBAK   c s<BackSpace>
DELWORDFWD     delWordFwdKey        OL_DELWORDFWD   c s<Delete>
DOCEND         docEndKey            OL_DOCEND       c<R13>
DOCSTART       docStartKey          OL_DOCSTART     c<R7>
LINEEND        lineEndKey           OL_LINEEND      n<R13>
LINESTART      lineStartKey         OL_LINESTART    n<R7>
PANEEND        paneEndKey           OL_PANEEND      c s<R13>
PANESTART      paneStartKey         OL_PANESTART    c s<R7>
RETURN         returnKey            OL_RETURN       <Return>
ROWDOWN        rowDownKey           OL_ROWDOWN      <Down>
ROWUP          rowUpKey             OL_ROWUP        <Up>
WORDBAK        wordBakKey           OL_WORDBAK      c<Left>
WORDFWD        wordFwdKey           OL_WORDFWD      c<Right>
 

  Table 3 Text Virtual Event Key Bindings

EXAMPLE

         ...
#include <Xol/OpenLook.h>
         ...
OlVirtualEventRec    ve;
      /∗ To look up the OPEN LOOK CORE database ∗/
OlLookupInputEvent(w, xevent, &ve, OL_CORE_IE);
switch (ve.virtual_name)
{
     case OL_UNKNOWN_INPUT:
         ...
          break;
     case OL_UNKNOWN_BTN_INPUT:
         ...
          break;
     case OL_UNKNOW_KEY_INPUT:
         ...
          break;
     case OL_ADJUST:
          printf ("pressed the adjustBtn\n");
         ...
          break;
     case OL_ADJUSTKEY:
          printf ("pressed the adjustKey\n");
         ...
          break;
         ...
}
         ...
         ...
#include <Xol/OpenLook.h>
         ...
OlVirtualEventRec     ve;
     /∗ To look up the OPEN LOOK TEXT database ∗/
OlLookupInputEvent(w, xevent, &ve, OL_TEXT_IE);
switch (ve.virtual_name)
{
         ...
     case OL_DOCEND:
          printf ("pressed the docEndKey\n");
         ...
          break;
     case OL_LINEEND:
          printf ("pressed the lineEndKey\n");
         ...
          break;
         ...
}
         ...
#include <Xol/OpenLook.h>
         ...
OlVirtualEventRec     ve;
     /∗ To look up all possible databases ∗/
     /∗ assume: "w" is a textfield widget ∗/
OlLookupInputEvent(w, xevent, &ve, OL_DEFAULT_IE);
switch (ve.virtual_name)
{
         ...
case OL_ADJUST:
     printf ("pressed the adjustBtn\n");
         ...
          break;
     case OL_ADJUSTKEY:
          printf ("pressed the adjustKey\n");
        ...
          break;
         ...
     case OL_DOCEND:
          printf ("pressed the docEndKey\n");
         ...
          break;
     case OL_LINEEND:
          printf ("pressed the lineEndKey\n");
         ...
          break;
         ...
}

OlWidgetSearchIEDB

Synopsis:

#include <Xol/OpenLook.h>
 . . .
void OlWidgetSearchIEDB(

Widget w,
OlVirtualEventTable db);

The OlWidgetSearchIEDB procedure is used to register a given database on a specific widget instance. The db value was returned from a call to

Once a database is registered with a given widget instance, the OlLookupInputEvent() procedure (if db_flag is OL_DEFAULT_IE or db) will include this database in the search stack if the given widget id is this widget instance.

EXAMPLE

      /∗ To create a client application database ∗/
   ...
#include <Xol/OpenLook.h>
     ...
      /∗ start with a big value to avoid ∗/
      /∗ the "virtual_name" collision    ∗/
#define OL_MY_BASE            1000
#define OL_MY_DRAWLINEBTN     OL_MY_BASE+0
#define OL_MY_DRAWARCBTN      OL_MY_BASE+1
#define OL_MY_REDISPLAYKEY    OL_MY_BASE+2
#define OL_MY_SAVEPARTKEY     OL_MY_BASE+3
 #define XtNmyDrawLineBtn      "myDrawLineBtn"
#define XtNmyDrawArcBtn       "myDrawArcBtn"
#define XtNmyRedisplayKey     "myRedisplayKey"
#define XtNmySavePartKey      "mySavePartKey"
 static OlKeyOrBtnRec     OlMyBtnInfo[] = {
     /∗name             default_value      virtual_name        ∗/
      { XtNmyDrawLineBtn,  "c<Button1>",       OL_MY_DRAWLINEBTN  },
     { XtNmyDrawArcBtn,   "s<myDrawLineBtn>", OL_MY_DRAWARCBTN   },
};
static OlKeyOrBtnRec     OlMyKeyInfo[] = {
    /∗name               default_value      virtual_name        ∗/
      { XtNmyRedisplayKey, "c<F5>",           OL_MY_REDISPLAYKEY },
     { XtNmySavePartKey,  "c<F5>",           OL_MY_SAVEPARTKEY  },
};
 static OlVirtualEventTable     OlMyDB;
    ...
OlMyDB = OlCreateInputEventDB(
               w,
               OlMyKeyInfo, XtNumber(OlMyKeyInfo),
               OlMyBtnInfo, XtNumber(OlMyBtnInfo)
     );
     ...
     /∗ assume: "w" is a stub widget that is interested in ∗/
     /∗          OlMyDB                                    ∗/
OlWidgetSearchIEDB(w, OlMyDB);
     /∗ once this step is done, this widget instance will  ∗/
     /∗ receive OlMyDB commands after a call to            ∗/
     /∗ OlLookupInputEvent(), or in the XtNconsumeEvent    ∗/
     /∗ callback’s OlVirtualEvent structure supplied with  ∗/
     /∗ the call_data field.                               ∗/
     ...

OlWidgetSearchTextDB

Synopsis:

#include <Xol/OpenLook.h>
 . . .
voidOlWidgetSearchTextDB(

OlVirtualEventTable w);

The OlWidgetSearchTextDB procedure is used to register the OPEN LOOK TEXT database on a specific widget instance. 

Once the OPEN LOOK TEXT database is registered with a given widget instance, the OlLookupInputEvent() procedure (if db_flag is OL_DEFAULT_IE or OL_TEXT_IE) will include this database in the search stack if the given widget id is this widget instance. 

EXAMPLE

 ...
#include <Xol/OpenLook.h>
 ...
      /∗ assume: "w" is a stub widget that is interested in ∗/
     /∗          the OPEN LOOK TEXT database               ∗/
OlWidgetSearchTextDB(w);
     /∗ once this step is done, this widget instance will  ∗/
     /∗ receive OPEN LOOK TEXT commands after a call       ∗/
     /∗ to OlLookupInputEvent(), or in the XtNconsumeEvent ∗/
     /∗ callback’s OlVirtualEvent structure supplied with  ∗/
     /∗ the call_data field.                               ∗/
  ...

Version 3.0.1  —