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.
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.
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.
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 |
When the application statrs up, EZ_InitializeXrm
reads and
mergs resource files from the following sources, in this order:
EZ_InitializeXrm
.
/usr/lib/X11/app-defaults/
ClassName.
XAPPLRESDIR/
ClassName and the
file XUSERFILESEARCHPATH/
ClassName.
RESOURCE_MANAGER
.
SCREEN_RESOURCE
.
HOME/.Xdefaults
XENVIRONMENT/.Xdefaults
or
HOME/.Xdefaults-
HOST.
-xrmfile
command line option.
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.
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.
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.
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);
There are also four pairs of convenience routines for
Suppose that in a hypothetical application we need to get the
variable
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
When you create a widget using In other words, attributes set by the
arguments of To hardcode an widget attribute, use
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
There are two ways to set resources for components of
a composite widget.
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
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
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
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.
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 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
( topFrame--> notebookPageTab
notebook-->(
( bottomFrame--> notebookPage
name-value
pair in an internal table for later lookup.
EZ_Value *EZ_RetrieveSymbol(char *name);
name
.
int EZ_GetApplicationResource(char *rname, char **value_ret);
rname
.
int EZ_GetWidgetResource(EZ_Widget *wgt, char *rname, char **v_ret);
rname
.
char *EZ_GetInstanceName();
char *EZ_GetClassName();
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
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
shape
to 2
if the resource file contains a specification
Test.shape: pentagon
1.5.9 Internally Defined Symbolic Names
1.5.10 When Are Widget Resources Set
EZ_CreateWidgetXrm
,
the arguments are processed first, then the resource
database is searched for widget resources and relevent
resource values are set.
EZ_CreateWidgetXrm
may be thought
as the fallback values for the corresponding resources.
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
EZ_CreateWidget***
returns, the resource database
has already been scaned with relevent resources applied.
Scan Resource Database At a Later Time
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
Components of an OptionalEntry
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
( ( 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
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
topFrame
and the bottom one
is named bottomFrame
.
notebookPage
. The
two subwidgets are actually descendants of the notebook widget.