EZwgl (2.5 Resources)

## 2.5 Resources

Resources are used to customize applications by the user. EZwgl supports widget resources. The appearance of widgets is completely customizable by resources. However, the functionality of widgets cannot be altered via resources. EZwgl does not support event-action translations.

### 2.5.1 The Resources Aware Functions

Three new routines were introduced in version 1.40. `EZ_InitializeXrm`, `EZ_CreateWidgetXrm`. and `EZ_CreateItemXrm`. They are the resources-aware replacements to `EZ_Initialize`, `EZ_CreateWidget` and `EZ_CreateItem`. An application should use these resource-aware functions in order to use the resource manager fully.

### 2.5.2 Class and Instance Names

An application has a `ClassName` and an `instanceName`. The class name is set by `EZ_InitializeXrm`. It is normally the application name with the first letter captalized, unless the first letter is 'X' or 'x', in which case the first two letters are capitalized. The instance is the command name, or any string set by the `-name` command line option. These two names are used by the resource manager to identify the application resources for the application.

The command line option `-className` can be used to set the class name.

Each widget has a `ClassName` and a `instanceName` also. The two names are introduced solely for the purpose of using Xlib's resources manager. They otherwise have nothing to do with the structure of the library. Consequently, one can use "class name" to group an arbitary set of widgets together and use their class name to set a common attribute, like foreground color.

Widget class and instance names are set by `EZ_CreateWidgetXrm`. For widgets implemented internally, the class and instance names can also set by using `EZ_CreateWidget` with the `EZ_NAME` and `EZ_CLASS` attributes set.

### 2.5.3 Default Widget Class and Instance Names

The default widget class and instance names are listed in the following table.

WidgetType | ClassName | instanceName
`EZ_WIDGET_FRAME` | `Frame` | `frame`
`EZ_WIDGET_LABEL` | `Label` | `label`
`EZ_WIDGET_NORMAL_BUTTON` | `Button` | `button`
`EZ_WIDGET_CHECK_BUTTON` | `CheckButton` | `checkButton`
`EZ_WIDGET_RADIO_BUTTON` | `RadioButton` | `radioButton`
`EZ_WIDGET_MENU_BUTTON` | `MenuButton` | `menuButton`
`EZ_WIDGET_MENU_SEPARATOR` | `MenuSeparatorItem` | `menuSeparatorItem`
`EZ_WIDGET_MENU_SUBMENU` | `MenuSubmenuItem` | `menuSubmenuItem`
`EZ_WIDGET_MENU_NORMAL_BUTTON` | `MenuButtonItem` | `menuButtonItem`
`EZ_WIDGET_MENU_CHECK_BUTTON` | `MenuCheckButton` | `menuCheckButton`
`EZ_WIDGET_MENU_RADIO_BUTTON` | `MenuRadioButton` | `menuRadioButton`
`EZ_WIDGET_VERTICAL_SLIDER` | `VerticalSlider` | `verticalSlider`
`EZ_WIDGET_HORIZONTAL_SLIDER` | `HorizontalSlider` | `horizontalSlider`
`EZ_WIDGET_ENTRY` | `Entry` | `entry`
`EZ_WIDGET_3D_CANVAS` | `ThreeDCanvas` | `threeDCanvas`
`EZ_WIDGET_VERTICAL_SCROLLBAR` | `VerticalScrollbar` | `verticalScrollbar`
`EZ_WIDGET_HORIZONTAL_SCROLLBAR` | `HorizontalScrollbar` | `horizontalScrollbar`
`EZ_WIDGET_ILIST_BOX` | `IListBox` | `iListBox`
`EZ_WIDGET_LIST_BOX` | `ListBox` | `listBox`
`EZ_WIDGET_ITEXT` | `IText` | `iText`
`EZ_WIDGET_TEXT` | `Text` | `text`
`EZ_WIDGET_NOTE_BOOK` | `NoteBook` | `noteBook`
`EZ_WIDGET_NB_PAGE` | `NoteBookPage` | `noteBookPage`
`EZ_WIDGET_NW_LABEL` | `NWLabel` | `nWLabel`
`EZ_WIDGET_PANE_HANDLE` | `PaneHandle` | `paneHandle`
`EZ_WIDGET_ARROW_BUTTON` | `ArrowButton` | `arrowButton`
`EZ_WIDGET_EXECUTOR` | `Executor` | `executor`
`EZ_WIDGET_OPTIONAL_ENTRY` | `OptionalEntry` | `optionalEntry`
`EZ_WIDGET_FILE_SELECTOR` | `FileSelector` | `fileSelector`
`EZ_WIDGET_ITREE` | `ITree` | `iTree`
`EZ_WIDGET_LIST_TREE` | `Tree` | `tree`
`EZ_WIDGET_IFANCY_LIST_BOX` | `IFancyListBox` | `iFancyListBox`
`EZ_WIDGET_FANCY_LIST_BOX` | `FancyListBox` | `fancyListBox`
`EZ_WIDGET_IWORK_AREA` | `IWorkArea` | `iWorkArea`
`EZ_WIDGET_WORK_AREA` | `WorkArea` | `workArea`
`EZ_WIDGET_RAW_XWINDOW` | `RawXWindow` | `rawXWindow`
`EZ_WIDGET_MENU_TEAR_OFF_BAR` | `TearOffBar` | `tearOffBar`
`EZ_WIDGET_LCD` | `Lcd` | `lcd`
`EZ_WIDGET_LED` | `Led` | `led`
`EZ_WIDGET_MENU` | `Menu` | `menu`
`EZ_WIDGET_FREE_LABEL` | `FreeLabel` | `freeLabel`
`EZ_WIDGET_EMBEDER` | `Embeder` | `embeder`
`EZ_WIDGET_STATUS_METER` | `StatusMeter` | `statusMeter`
`EZ_WIDGET_MENU_BAR` | `MenuBar` | `menuBar`
`EZ_WIDGET_TERM` | `Term` | `term`
`EZ_WIDGET_ITERM` | `ITerm` | `iTerm`
`EZ_WIDGET_HORIZONTAL_RULER` | `HorizontalRuler` | `horizontalRuler`
`EZ_WIDGET_VERTICAL_RULER` | `VerticalRuler` | `verticalRuler`
`EZ_WIDGET_DIAL` | `Dial` | `dial`
`EZ_WIDGET_GRADIENT_BAR` | `GradientBar` | `gradientBar`
`EZ_WIDGET_HISTOGRAM` | `Histogram` | `histogram`
`EZ_WIDGET_SPREAD_SHEET` | `SpreadSheet` | `spreadSheet`
`EZ_WIDGET_THUMB_WHEEL` | `ThumbWheel` | `thumbWheel`

### 2.5.4 Resource Files

When the application statrs up, `EZ_InitializeXrm` reads and mergs resource files from the following sources, in this order:

- The fallback resource string passed to `EZ_InitializeXrm`.

- The file `/usr/lib/X11/app-defaults/`ClassName.

- The file `XAPPLRESDIR/`ClassName and the file `XUSERFILESEARCHPATH/`ClassName.

- Resources set by the string `RESOURCE_MANAGER`.

- Resources set by the string `SCREEN_RESOURCE`.

- The file `HOME/.Xdefaults`

- The file `XENVIRONMENT/.Xdefaults` or `HOME/.Xdefaults-`HOST.

- Resource file specified by the `-xrmfile` command line option.

- Resources set on the command line.

### 2.5.5 Forms of Resource Specifications

Resources are specified by name/value pairs. There are two type of resources: application resources and widget resources. The syntax for specifying an application resource is like:

`application_name.resource_name: value`

The next table lists the set of internally defined application resource names and their values.

    -----------------------------------------------------------
     Resource Name                  Default value
    -----------------------------------------------------------
    "labelFont"                "-Adobe-Helvetica-Bold-R-Normal--*-120-*-*-*-*-*-*",
    "textFont"                 "-*-Courier-Medium-R-Normal--*-120-*-*-*-*-*-*",
    "menuTitleFont"            "-Adobe-Times-Bold-I-Normal--*-120-*-*-*-*-*-*",
    "highlight"                true
    "sliderDepression"         true
    "labelOffset"              true
    "ditherImage"              false
    "bubbleHelp"               off
    "initialState"             normalState
    "visual"
    "name"                     argv[0]
    "noBackingStore"           false
    "privateColormap"          false
    "readWriteColormap"        false
    "focusHighlightColor"      "black"
    "foreground"               "black"
    "background"               "gray74"

Specifying a widget resource is a bit more complicated, since there may be several instances of the same widget in one application. Consequently, one must use the whole pathname of a widget, starting with the application name, to specify a widget resource. For example, the line

`example1.box.label.labelString: Welcome!`

sets the lable of a widget named label, which is a child of a widget named box which is a toplevel widget in an application called example1, to the string "Welcome!".

There is a wildcard syntax which may be used to simplify resources specifications. One may use an asterisk instead of a dot and omitting one or more terms of the full pathname. For example, the above line may be simplified as

`*label.labelString: Welcome!`

For a complete description of resource specification and matching, please consult the "Xlib Programming Manual" by Adrian Nye.

### 2.5.6 Widget Resource Names

Each configuration options has a corresponding resource name. Some resources apply to all widgets while others are relevent only to some widgets. Please consult the relevent sections in this manual for a complete list of resources available for each widget.

### 2.5.7 Standard Command Line Options

All EZwgl applications accept the set of standard command line options listed in the next table. At startup time, the command line is parsed first in search of the standard options first, matching options are removed. The altered command line is then send to `XrmParseCommand` to match against the command line option table passed to `EZ_InitializeXrm`.

    static XrmOptionDescRec EZ_StandardCommandLineOptions[] = {
      {"-display",          ".display",           XrmoptionSepArg,  NULL},
      {"-visual",           ".visual",            XrmoptionSepArg,  NULL},
      {"-geometry",         ".geometry",          XrmoptionSepArg,  NULL},
      {"-background",       ".background",        XrmoptionSepArg,  NULL},
      {"-bg",               ".background",        XrmoptionSepArg,  NULL},
      {"-foreground",       ".foreground",        XrmoptionSepArg,  NULL},
      {"-fg",               ".foreground",        XrmoptionSepArg,  NULL},
      {"-iconic",           ".initialState",      XrmoptionNoArg,  "IconicState"},
      {"-dualLabel",        ".dualLabel",         XrmoptionNoArg,  "True"},
      {"-noBackingstore",   ".noBackingStore",    XrmoptionNoArg,  "True"},
      {"-privateColormap",  ".privateColormap",   XrmoptionNoArg,  "True"},
      {"-readWriteColormap",".readWriteColormap", XrmoptionNoArg,  "True"},

      /* the next five options are for debugging only */
      {"-xrm",             NOTHING,            XrmoptionSepArg,  NULL},
      {"-xrmfile",         NOTHING,            XrmoptionSepArg,  NULL},
      {"-className",       NOTHING,            XrmoptionSepArg,  NULL},
      {"-name",            NOTHING,            XrmoptionSepArg,  NULL},
      {"-sychnronous",     NOTHING,            XrmoptionNoArg,   NULL},
    };

### 2.5.8 Application Resources

EZwgl provides a limited support for application resources. In particular, there is no automatic type conversion facility as seen in Xt. EZwgl can only convert application resources to one of the four basic data types, namely `int,float,ulong` and `string`. Consequently, if you need to convert resources to other data types, you must provide ways to convert resource values (strings) to the desired data types.

Only global variables can be set via application resources.

### Automatic Resource Value Convertion

To convert resource values to one of the four basic data types. One first define a list of resource specifications and a procedure specifies how the resource values will be used, then call `EZ_RegisterApplicationResources` to register the resources. This function must be called right after the library has been initialized.

A resource specification is a special data structure of type

    typedef struct {
      int     option;     /* reference id. must > 1024 */
      char    *iname;     /* instance name */
      char    *cname;     /* class name, may be NULL */
      char    *vtypes;    /* value type, e.g  "float, float" */
    } EZ_ResourceSpec;

Here is an example.

    static int   int1 = 0,   int2 = 0; /* var set by resources */
    static float float2 = 0;
    static  EZ_ResourceSpec exampleResources[] =
    {
       { 1234, "aPairOfInt",  "APairOfInt", "int,int"   },
       { 1235, "intFloat",    "IntFloat",   "int,float" },
    };

The configure procedure looks like

    int configure(EZ_Widget *notused, int option, EZ_Value *values)
    {
      switch(option)
       {
         case 1234:  int1 = values[0].value.i; int2 = values[1].value.i; break;
         case 1235:  int1 = values[0].value.i; float2 = values[1].value.f; break;
         default:  break;
       }
    }

And here is how the resources above should be used.

    #include "EZ.h";
    main(int ac, char **av)
    {
      EZ_Initialize(ac, av, 1);
      EZ_RegisterApplicationResources(2, exampleResources, configure);
      printf("int1=%d, int2=%d, float2=%f\n", int1, int2, float2);
      /* more stuff ... */
    }

### Using Symbolic Constants

EZwgl includes a few functions that may be helpful for manipulating symbolic names.

One special data type is introduced for associating symbolic names with numerical values.

    typedef struct EZ_Value_ {
      int  type;    /* value type: EZ_INT, EZ_FLOAT, EZ_POINTER, EZ_ULONG */
      union {
        char    c;    unsigned char  uc;
        short   s;    unsigned short us;
        int     i;    unsigned int   ui;
        float   f;
        void    *p;
        void    *function;
        char    *str;
        unsigned long l;
      } value;
    } EZ_Value;

The few relevent functions are:

`void EZ_InstallSymbol(char *name, EZ_Value value);`

install the `name-value` pair in an internal table for later lookup.

`EZ_Value *EZ_RetrieveSymbol(char *name);`

retrieve the value assigned to `name`. Return a pointer or NULL.

`int EZ_GetApplicationResource(char *rname, char **value_ret);`

retrieve the resource value assigned to `rname`. Return True or False.

`int EZ_GetWidgetResource(EZ_Widget *wgt, char *rname, char **v_ret);`

retrieve the widget resource value for `rname`. Return True or False.

`char *EZ_GetInstanceName();`

`char *EZ_GetClassName();`

retrieve the instanceName and className.

There are also four pairs of convenience routines for `EZ_InstallSymbol`, then are

    int   EZ_InstallSymbolicInt       (char *name, int value);
    int   EZ_RetrieveSymbolicInt      (char *name, int *value_ret);

    int   EZ_InstallSymbolicFloat     (char *name, float value);
    int   EZ_RetrieveSymbolicFloat    (char *name, float *value_ret);

    int   EZ_InstallSymbolicPointer   (char *name, void *value);
    int   EZ_RetrieveSymbolicPointer  (char *name, void **value_ret);

    int   EZ_InstallSymbolicULong     (char *name, unsigned long value);
    int   EZ_RetrieveSymbolicULong    (char *name, unsigned long *value_ret);

### An Example

Suppose that in a hypothetical application we need to get the variable `shape` from the application resource named shape. The variable `shape` takes only 4 different values: `triangle`, `square`, `pentagon` and `hexagon`. These values are represented by, say, `0, 1, 2` and `3`. We can specify these values in the resource file, but it is more readable if we use the names instead. The following code segement does the trick.

    #include
    #define TRIANGLE       0
    #define SQUARE         1
    #define PETAGON        2
    #define HEXAGON        3

    static  int   shape = TRIANGLE;

    static EZ_ResourceSpec testResources[] =
    {
      {1236,  "shape", "Shape", "int"},
    };

    static int configShape(EZ_Widget *notused, int option, EZ_Value *values)
    {
      if(option == 1236)
        {
          int tmp = values[0].value;
          if(tmp >= 0 && tmp <= 3) shape = tmp;
        }
    }

    main(int argc, char **argv)
    {
       char  *value_ret;

       EZ_InitializeXrm("Test", NULL, 0, &argc, argv, NULL, 0);
       /* install 4 name-value pairs */
       if( EZ_InstallSymbolicInt("triangle", TRIANGLE) < 0 ||
           EZ_InstallSymbolicInt("square",   SQUARE) < 0   ||
           EZ_InstallSymbolicInt("petagon",  PETAGON)< 0   ||
           EZ_InstallSymbolicInt("hexagon",  HEXAGON)< 0 )
       fprintf(stderr,"InstallSymbol Failed");  /* symbol is already in use */

       EZ_RegisterApplicationResources(1, testResources, configShape);

       ... ...

    }

This code will set the value of `shape` to `2` if the resource file contains a specification

`Test.shape: pentagon`

### 2.5.9 Internally Defined Symbolic Names

The following (integer) symbols are defined internally.

     no                  0 	                                 bottom              4
     yes                 1 	                                 topLeft             5
     No                  0 	                                 topRight            6
     Yes                 1 	                                 bottomLeft          7
     null                0 	                                 bottomRight         8
     Null                0 	                                 empty               0
     false               0 	                                 square              1
     true                1 	                                 sunkenSquare        2
     False               0 	                                 diamond             3
     True                1 	                                 sunkenDiamond       4
     on                  1 	                                 circle              5
     off                 0 	                                 check               6
     On                  1 	                                 rectangle           7
     Off                 0 	                                 mbutton             8
     none                0 	                                 tick                9
     None                0 	                                 row                 1
     nil                 0 	                                 column              2
     horizontal          1	                                  allRows             4
     horizontalLeft      2	                                  allColumns          8
     horizontalRight     3	                                  flat                1
     horizontalCenter    4	                                  ridge               2
     vertical            5	                                  groove              3
     verticalTop         6	                                  raised              4
     verticalBottom      7	                                  sunken              5
     verticalCenter      8 	                                 embossed            8
     fillNone            0 	                                 engraved            9
     fillHorizontally    1                                   shadow              22
     fillVertically      2 	                                 shadow              23
     fillBoth            3 	                                 normalState         1
     center              0 	                                 iconicState         3
     left                1 	                                 up                  10
     right               2 	                                 down                11
     top                 3 	                                 leftRight           12
     upDown              13

### 2.5.10 When Are Widget Resources Set

When you create a widget using `EZ_CreateWidgetXrm`, the arguments are processed first, then the resource database is searched for widget resources and relevent resource values are set.

In other words, attributes set by the arguments of `EZ_CreateWidgetXrm` may be thought as the fallback values for the corresponding resources.

To hardcode an widget attribute, use `EZ_ConfigureWidget`. Attributes set by this function overrides the corresponding attributes set by resources (unless you rescan the resource database).

### 2.5.11 Resources and Composite Widgets

Setting resources for a composite widget is a little more involved, since there is no way to set the instance/class names for its components at the creation time. After `EZ_CreateWidget***` returns, the resource database has already been scaned with relevent resources applied.

There are two ways to set resources for components of a composite widget.

### Scan Resource Database At a Later Time

In EZwgl, one can scan the resource database anytime after initialization. The procedures responsible for searching the database for widget resources are

    void EZ_GetAndUseWidgetResources(EZ_Widget *widget);
    void EZ_GetAndUseWidgetResources1(EZ_Widget *widget);

When invoked, they scans the resource database for resources relevent to widget and set the resource (attribute) values accordingly. The first function scans and sets resources for descendants widgets recursively.

To set resources for components of a composite widget, one first extract the components of the composite widget using `EZ_Get***Components`, then invoke `EZ_ConfigureWidget` on the components to give them an instanceName or ClassName, then call `EZ_GetAndUseWidgetResources` on the composite widget to rescan and set the resources values.

### Use the Builtin instance/Class Names

Except fileSelector and optionalEntry, the components of all other composite widgets has the default widget instanceName and ClassName. These default names are explicit enough to specify all subwidgets. For example, a text widget consists of three components: an internal-text-widget, a h-scrollbar and a v-scrollbar. The path names for these components are:

    text_widget_name.iText
    text_widget_name.horizontalScrollbar
    text_widget_name.verticalScrollbar

### Components of an OptionalEntry

OptionalEntry presents a unique problem, it contains a toplevel popup listbox, which is not a descendant of the the optionalEntry. The builtin name for the popup listbox is `popup` (ClassName `Popup`). EZwgl provides a configuration option for optionalEntry, namely, `EZ_POPUP_NAME`, to override this name. The componet names are listed below.

                     ( entry
                     (
     optionalEntry-->( arrowButton
                     (         ( iListBox
               ....... popup-->( horizontalScrollbar
                               ( verticalScrollbar

### Components of a FileSelector

Since there are repetitions of buttons and entries on a fileSelector widget, using the default widget instanceName is not sufficient in distinguishing components. The builtin instanceNames for all components of a fileSelector is listed below.

                    (           ( filterLabel
                    (           (                         ( iListBox
                    (  frameA-->( filterEntry ...popupA-->( horizontalScrollbar
                    (                                     ( verticalScrollbar
                    (          (           ( directoryLabel
                    (          (           (                    ( iListBox
                    (          ( frameB1-->( directoryListBox-->( horizontalScrollbar
                    (          (                                ( verticalScrollbar
                    (          (           ( fileLabel
                    (          (           (               ( iListBox
     fileSelector-->( frameB-->( frameB2-->( fileListBox-->( horizontalScrollbar
                    (          (           (               ( verticalScrollbar
                    (
                    (          ( selectionLabel
                    (          (                            ( iListBox
                    ( frameC-->( selectionEntry ...popupB-->( horizontalScrollbar
                    (                                       ( verticalScrollbar
                    (          ( okButton
                    ( frameD-->( filterButton
                    (          ( hideButton

The instance names for the popup listboxes can be oriverriden by the configuration option `EZ_POPUP_NAME`. EZwgl appends the letter `A` and `B` at the end of the configured name and assign them to the two popups.

### Components of Notebook and NoteBookPage

The notebook widget is made from three frames. The outermost frame is the notebook. The two inner frames are named `topFrame` and `bottomFrame`. `topFrame` is the container for page tabs.

The notebook page widget can only be the child of a notebook widget. A notebook page consists of two widgets, a button and a frame. They frame is called `notebookPage`. The two subwidgets are actually descendants of the notebook widget.

                 ( topFrame--> notebookPageTab
      notebook-->(
                 ( bottomFrame--> notebookPage

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`