Volume 7B: XView Reference Manual

3

Procedures and Macros

This section lists the XView procedures and macros in alphabetical order. For each proce-

dure or macro, an explanation of its use is provided. Following each procedure is a synopsis

that includes the procedure’s parameters, if there are any. The parameters are described after

the synopsis.

attr_create_list( )

Takes an attribute-value list and converts it into an array of Attr_attributes, also

known as an Attr_avlist. ATTRIBUTE_STANDARD_SIZE, defined in <xview/attr.h>,

defines how big an attriubte-value list can get. This is the limit on how big an attri-

bute-value list can be created using the ATTR_LIST or attr_create_list() macros.

Attr_avlist

attr_create_list(attrs)

The return value is used as the value for the attribute ATTR_LIST.

CANVAS_EACH_PAINT_WINDOW( )

Macro providing built-in support for iteration across all the paint windows contained in

a given canvas. Allows you to perform operations on multiple paint windows for

which there are no canvas attributes.

CANVAS_END_EACH

Closes the loop started by CANVAS_EACH_PAINT_WINDOW(). These two macros are

meant to be used together.

cursor_copy()

Creates and returns a copy of src_cursor.

Xv_Cursor

cursor_copy(src_cursor)

Xv_Cursor src_cursor;

Procedures and Macros

Procedures and Macros 175

defaults_exists()

This function returns TRUE if the resource exists in the database via

XrmGetResource().

Bool

defaults_exists(name, class)

char *name;

char *class;

defaults_exists()

defaults_set_boolean() sets the resource to the value specified.

void

defaults_set_boolean(resource, value)

char *resource;

Bool value;

defaults_get_boolean()

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

and returns TRUE if the value is one of:

• True

• Yes

• On

• Enabled

• Set

• Activated

• 1

It returns FALSE if the value is one of:

• False

• No

• Off

• Disabled

• Reset

• Cleared

• Deactivated

• 0

If the value is none of the previous, a warning message will be displayed and the de-

fault value will be returned. If the resource is not found, no error message is printed

but the default value is still returned.

Bool

defaults_get_boolean(name, class, default_value)

char *name, *class;

int default_value;

176 XView Reference Manual

defaults_get_character()

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

base and returns the resulting character value. If the resource is not found, then the de-

fault character value is returned.

char

defaults_get_character(name, class, default_char)

char *name;

char *class;

char default_char;

defaults_get_enum()

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

faults_get_enum() calls defaults_get_string() and determines the val-

ue returned by calling defaults_lookup(), passing the returned string as the

name parameter.

int

defaults_get_enum(name, class, pairs)

char *name;

char *class;

Defaults_pairs *pairs;

defaults_get_integer()

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.

int

defaults_get_integer(name, class, default_value)

char *name;

char *class;

int default_value;

defaults_get_integer_check()

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

database and returns the resulting integer value. If the value in the database is not be-

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

int

defaults_get_integer_check(name, class, default_value,

minimum, maximum)

char *name;

char *class;

int default_value;

int minimum;

int maximum;

Procedures and Macros

Procedures and Macros 177

defaults_get_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. defaults_get_string() returns a pointer into a static buffer

maintained by the defaults package. Applications should not attempt to free this point-

er. This buffer will be overwritten by the next call to the defaults package, so the ap-

plication should maintain a copy if necessary.

char *

defaults_get_string(name, class, default_str)

char *name;

char *class;

char *default_str;

defaults_init_db()

This function is called automatically by xv_init(), so it need not be called by your

application. defaults_init_db() calls XrmInitialize().

void

defaults_init_db()

defaults_load_db()

defaults_load_db() loads the database residing in the specified filename or the

server database if filename is NULL. The database found in filename is loaded via

XrmGetFileDatabase() and is merged into the existing resource database via

XrmMergeDatabases().

void

defaults_load_db(filename)

char *filename;

defaults_lookup()

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

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

int

defaults_lookup(name, pairs)

char *name;

Defaults_pairs *pairs;

defaults_set_character()

defaults_set_character() sets the resource to the character value.

void

defaults_set_character(resource, character)

char *resource;

char character;

178 XView Reference Manual

defaults_set_integer( )

defaults_set_integer() sets the resource to the value specified.

void

defaults_set_integer(resource, value)

char *resource;

int value;

defaults_set_string( )

defaults_set_string() sets the resource to the specified string.

void

defaults_set_string(resource, string)

char *resource;

char *string;

defaults_store_db()

void

defaults_store_db(filename)

char *filename;

This function writes the database to the specified file via XrmPutFileData-

base(). This must be done in order to ensure that the database is accessible the next

time the server is started.

dnd_decode_drop()

This function initiates a drag and drop data transfer using the selection mechanism.

The drop event is decoded in three steps: First, the selection defined within the drop

event is associated with the selection object passed into dnd_decode_drop(); sec-

ond, the function sends an acknowledgement to the source, informing it that the trans-

action has been initiated; finally, if the drop-site is valid, the drop-site item that was

dropped on is returned. Otherwise, if dnd_decode_drop() fails to initiate the drag

and drop transaction, XV_ERROR is returned.

Xv_drop_site

dnd_decode_drop(sel_object, drop_event)

Selection_requestor sel_object;

Event *drop_event;

sel_object is an instantiated selection requestor object. drop_event is a pointer

to the event structure that contains the trigger event. This event is either the semantic

event

ACTION_DRAG_MOVE or ACTION_DRAG_COPY, indicating the type of the drag and

drop: a move or a copy.

Procedures and Macros

Procedures and Macros 179