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 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.
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 |
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]
"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.
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"},
{"-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},
};
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.
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 ... */
}
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);
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 up 10
right 2 down 11
top 3 leftRight 12
upDown 13
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 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
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
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
. Return a pointer or NULL.
int EZ_GetApplicationResource(char *rname, char **value_ret);
rname
. Return True or False.
int EZ_GetWidgetResource(EZ_Widget *wgt, char *rname, char **v_ret);
rname
. Return True or False.
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
2.5.9 Internally Defined Symbolic Names
2.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).
2.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 bottomFrame
. topFrame
is the container for page tabs.
notebookPage
. The
two subwidgets are actually descendants of the notebook widget.