Volume 7A: XView Programming Manual

defaults_get_boolean() looks up the name-class pair in the resource database and

returns TRUE if the value is one of the following:

• True

• Yes

• On

• Enabled

• Set

• Activated

• 1

It returns FALSE if the value is one of the following:

• False

• No

• Off

• Disabled

• Reset

• Cleared

• Deactivated

• 0

If the value is none of the above, a warning message will be displayed and the default value

will be returned. If the resource is not found, no error message is printed but the default

value is still returned.

defaults_set_boolean() sets the resource to the value specified.

17.2.2 Integer Resources

int

defaults_get_integer(name, class, default_value)

char *name;

char *class;

int default_value;

int

defaults_get_integer_check(name, class, default_value,

minimum, maximum)

char *name;

char *class;

int default_value;

int minimum;

int maximum;

386 XView Programming Manual

void

defaults_set_integer(resource, value)

char *resource;

int value;

defaults_get_integer() looks up the name-class pair in the resource database and

returns the resulting integer value. If the database does not contain the resource, the default

value is returned.

defaults_get_integer_check() looks up the name-class pair in the resource data-

base and returns the resulting integer value. If the value in the database is not between the

values minimum and maximum (inclusive), an error message is printed and the default value

is returned. If the resource is not found, no error message is printed but the default value is

returned.

defaults_set_integer() sets the resource to the value specified.

17.2.3 Character Resources

char

defaults_get_character(name, class, default_char)

char *name;

char *class;

char default_char;

void

defaults_set_character(resource, character)

char *resource;

char character;

defaults_get_character() looks up the name-class pair in the resource database and

returns the resulting character value. If the resource is not found, then the default character

value is returned.

defaults_set_character() sets the resource to the character value.

17.2.4 String Resources

char *

defaults_get_string(name, class, default_str)

char *name;

char *class;

char *default_str;

void

defaults_set_string(resource, string)

char *resource;

char *string;

defaults_get_string() returns the string value associated with the specified name-

class pair in the resource database. If the resource is not found, the default string value is

returned. The procedure defauts_get_string() returns a pointer into a static buffer

maintained by the defaults package. The application should not attempt to free this pointer.

Resources

Resources 387

This buffer will be overwritten by the next call to the defaults package, so the application

should maintain a copy if necessary.

defaults_set_string() sets the resource to the specified string.

17.2.5 Enumerated Resources

Enumerated resources are those whose values are string values, but the legal values for the

resource are restricted to a predefined list. For example, say you want to allow the user to

specify the font scale for the font lucidasans. The legal scale values are: small,

medium, large, and extra large. You could use defaults_get_string() and deter-

mine, using strcmp(), whether the value returned is one of the legal scale values. Or you

could use defaults_get_enum() and pass in a table describing the legal values. The

table is an array of elements of the type:

typedef struct _default_pairs {

char *name; /* Name of pair */

int value; /* Value of pair */

} Defaults_pairs;

The name is a string, and the value is the returned value associated with the name. This value

may be your own value and need not be sequential, but it must be an int.

int

defaults_get_enum(name, class, pairs)

char *name;

char *class;

Defaults_pairs *pairs;

defaults_get_enum() looks up the value associated with name and class and scans the

pairs table and returns the associated value. If no match is found, an error is generated and

the value associated with the last entry is returned. defaults_get_enum() calls

defaults_get_string() and determines the value returned by calling

defaults_lookup() (below), passing the returned string as the name parameter.

int

defaults_lookup(name, pairs)

char *name;

Defaults_pairs *pairs;

defaults_lookup() linearly scans the pairs array looking for name. The value asso-

ciated with name is returned. The pairs array must contain a last element with a NULL

name and a legal value associated with it. This value is returned if name does not match

the name field of any of the elements in the pairs parameter.

Example 17-2 shows a program that implements the idea discussed earlier for allowing the

user to specify a scale for a font.

Example 17-2. The default_size.c program

/*

* default_scale.c -- demonstrate the use of defaults_get_enum().

* Specify a table of font scales and query the resource database

388 XView Programming Manual

Example 17-2. The default_size.c program (continued)

* for legal values. For example, you may have the following in

* your .Xdefaults (which must be loaded into the resource database):

* font.scale: large

*/

#include <xview/xview.h>

#include <xview/font.h>

#include <xview/defaults.h>

#include <xview/textsw.h>

Defaults_pairs size_pairs[ ] = {

"small", WIN_SCALE_SMALL,

"medium", WIN_SCALE_MEDIUM,

"large", WIN_SCALE_LARGE,

"extralarge", WIN_SCALE_EXTRALARGE,

/* the NULL entry is the default if Resource not found */

NULL, WIN_SCALE_MEDIUM,

};

main(argc, argv)

char *argv[ ];

{

Frame frame;

Xv_Font font;

int scale;

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

frame = (Frame)xv_create(NULL, FRAME, NULL);

scale = defaults_get_enum("font.scale", "Font.Scale", size_pairs);

/* get the default font for the frame, scaled to resource */

font = xv_find(frame, FONT,

FONT_RESCALE_OF, xv_find(frame, FONT, NULL), scale,

NULL);

xv_create(frame, TEXTSW,

XV_FONT, font,

WIN_COLUMNS, 80,

WIN_ROWS, 10,

NULL);

window_fit(frame);

xv_main_loop(frame);

}

In default_size.c, the pairs table describes an association between string constants and

scaling factors. The resource database may specify the resource font.scale that

describes a scaling factor. If the value in the resource is not one of the legal values included

in the table, an error message is printed to inform the user that s/he has specified the resource

incorrectly. In this case, or in the case where the resource is not specified, the default

resource (associated with the

NULL entry) is returned, namely, WIN_SCALE_MEDIUM.

Resources

Resources 389

NOTE

The value field in the Defaults_pair data structure is an int, so do not

attempt to assign pointers, functions or attributes to this field. You can assign

enumerated types since they are interpreted as int.

17.3 Creating Resource Instances

The attribute XV_INSTANCE_NAME is used to associate an instance name with an XView

object. The instance name is used to construct the resource name used by the Resource Man-

ager to perform lookups. The resource name is constructed by concatenating the instance

names of all objects in the current object’s lineage, starting with the name of the application

or whatever was passed in with the –name command-line option, ending with the XView

attribute name. The XView attribute name remains in lowercase.

XV_INSTANCE_NAME is nor-

mally used with XV_USE_DB. Assume the name of an application is app:

Frame frame;

Panel panel;

frame = (Frame)xv_create(NULL, FRAME,

XV_INSTANCE_NAME, "base_frame",

NULL);

panel = (Panel)xv_create(frame, PANEL,

XV_INSTANCE_NAME, "panel",

XV_USE_DB,

XV_WIDTH, 100,

XV_HEIGHT, 200,

NULL,

NULL);

For this code fragment, assuming the name of the application is “app,” the resource names

constructed for lookup of the width and height of the panel are:

app.base_frame.panel.xv_width

app.base_frame.panel.xv_height

Entries in the Resource Manager could look like:

app.base_frame.panel.xv_width:400

app.base_frame.panel.xv_height:500

If these entries were not present in the Resource Manager, the width and height of the panel

would take the default values of 100 and 200 respectively.

The attribute

XV_USE_DB specifies a set of attributes that are to be searched in the X11

Resource Manager database. XV_USE_DB takes a NULL-terminated list of attribute value pairs

as its values. During program execution, each attribute in this NULL-terminated list of attri-

butes is looked up in the X11 Resource manager database. If the attribute is not found in the

database, then the value specified in the attribute-value pair is used as the default value.

The list of customizable attributes can be found in the XView Reference Manual.

390 XView Programming Manual