EZ
Up Prev Next Contents


1.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.

1.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.

1.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 to use Xlib's resources manager. They otherwise have nothing to do with the structure of the library. For example, there is no concept of "widget class" in EZwgl. As a result, one can use class 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.

1.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

1.5.4 Resource Files

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

1.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] "backingStore" false "privateColormap" false "readWriteColormap" false "focusHighlightColor" black

Specifying a widget resource is a bit more complicated, since there may be several instances of the same widget in one application. As a result, 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.

1.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.

1.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"},
  {"-backingstore",     ".backingStore",      XrmoptionNoArg,  "True"},
  {"-privateColormap",  ".privateColormap",   XrmoptionNoArg,  "True"},
  {"-readWriteColormap",".readWriteColormap", XrmoptionNoArg,  "True"},

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

EZwgl also support the -name command-line option. It sets the instance name of the application to the specified name.

1.5.8 Application Resources

EZwgl provides a very limited support for application resources. In particular, there is no automatic type conversion facility as seen in Xt. Thus, in order to set application variables from resources, the application writer must provide ways to convert resource values (strings) to the desired data types.

Nevertheless, EZwgl includes a few functions that may be helpful for those who wants to use application resources.

One special data type is introduced for the purpose of doing simple type conversions.

typedef struct EZ_Value_ int type; /* value type: EZ_INT, EZ_FLOAT, EZ_POINTER, EZ_ULONG */ union int i; float f; void *p; 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.

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

retrieve the resource value assigned to rname.

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

retrieve the widget resource value corresponding to rname.

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

main(int argc, char **argv)
{
   int   shape;
   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 */

   ... ...

   shape = TRIANGLE; /* default value for shape */
   /* get application resource "shape" */
   if( EZ_GetApplicationResource("shape", &value_return))
     {                       /* found the resource */
       int ivalue;
       if(EZ_RetrieveSymbolicInt(value_ret, &ivalue) >= 0)
         {
            /* has to verify if ivalue is out of range */
           if(ivalue >= TRIANGLE && ivalue <= HEXAGON)
               shape = ivalue;
         }
    }

  ... ...
}

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

Test.shape: pentagon

1.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 right 2 top 3

The following symbols are also defined. They refer to the corresponding X cursors.

XC_X_cursor XC_gobbler XC_sb_h_double_arrow XC_arrow XC_gumby XC_sb_left_arrow XC_based_arrow_down XC_hand1 XC_sb_right_arrow XC_based_arrow_up XC_hand2 XC_sb_up_arrow XC_boat XC_heart XC_sb_v_double_arrow XC_bogosity XC_icon XC_shuttle XC_bottom_left_corner XC_iron_cross XC_sizing XC_bottom_right_corner XC_left_ptr XC_spider XC_bottom_side XC_left_side XC_spraycan XC_bottom_tee XC_left_tee XC_star XC_box_spiral XC_leftbutton XC_target XC_center_ptr XC_ll_angle XC_tcross XC_circle XC_lr_angle XC_top_left_arrow XC_clock XC_man XC_top_left_corner XC_coffee_mug XC_middlebutton XC_top_right_corner XC_cross XC_mouse XC_top_side XC_cross_reverse XC_pencil XC_top_tee XC_crosshair XC_pirate XC_trek XC_diamond_cross XC_plus XC_ul_angle XC_dot XC_question_arrow XC_umbrella XC_dotbox XC_right_ptr XC_ur_angle XC_double_arrow XC_right_side XC_watch XC_draft_large XC_right_tee XC_xterm XC_draft_small XC_rightbutton XC_draped_box XC_rtl_logo XC_exchange XC_sailboat XC_fleur XC_sb_down_arrow

1.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).

1.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 enought 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 stacked vertically, the top one is named topFrame and the bottom one is named bottomFrame.

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


Up Prev Next Contents

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