Corrections to the XView Programming Manual

This section contains corrections to the XView Programming Manual (Volume 7), Third Edition, from O'Reilly and Associates. Unless noted, the corrections are for the XView version 3 edition of the manual.

long_seln.c

The long_seln.c program (example A-3) contains an error. The line

char *seln_bufs[3]; /* contents of each of the three selections */

should be replaced by:

char *seln_bufs[6]; /* contents of the three selections, but allow room for all six types of selections*/

The program in $OPENWINHOME/share/src/xview/examples/seln_svc contains the corrected code.

PANEL_EVENT_PROC

The xv_set expression in Section 7.19.8

xv_set(panel, PANEL_EVENT_PROC, my_event_proc, NULL)

incorrectly sets the PANEL_EVENT_PROC on a panel. It can be set only on a Panel_item.

notify_next_event_func

The Third Edition O'Reilly programmer documentation incorrectly states that notify_next_event_func takes the same arguments as my_frame_interposer (see example 20-5). (Note that this error also occurs in the function declaration on page 162 of the reference manual.)

Using the function with these parameters leads to a compiler warning:

line # : warning: improper pointer/integer combination: arg #2

The notify_next_event_func declaration should read:

Notify_value notify_next_event_func(client, event, arg, type) Notify_client client; Notify_event event; Notify_arg arg; Notify_event_typetype;

notice.c

This correction refers to the XView 3.2 Programming Manual.

The notice.c program (example 12.6) incorrectly uses the NOTICE package. To correct this, declare result as type static int (instead of int) in my_notify_proc.

Corrections to the XView Reference Manual

This section contains corrections to the XView Reference Manual for XView Version 3, Companion to Volume 7, from O'Reilly and Associates.

CMS_COLOR_COUNT

You cannot use CMS_COLOR_COUNT to retrieve a subset of the CMS's CMS_COLORS or CMS_X_COLORS array. Page 37 of the reference manual incorrectly states that you can use xv_get to do this. XView ignores CMS_COLOR_COUNT with xv_get.

The first paragraph on page 37 (which describes CMS_COLOR_COUNT) should read:

"Used to specify the number of colors being set with CMS_COLORS or CMS_X_COLORS."

Supplementary XView Documentation

This section contains information regarding the XView toolkit that would normally reside in the O'Reilly documentation, but was not included in O'Reilly's final XView documentation release.

Joining Canvas Views

To join XView canvas views, destroy the view that you do not want by invoking xv_destroy_safe. Here is sample code to do this:

void destroy_last_view(canvas) Canvas canvas; { /* destroy the last View window */ Xv_Window view; int nviews; nviews = (int) xv_get(canvas, OPENWIN_NVIEWS); if (nviews > 1) { view = (Xv_Window) xv_get(canvas, OPENWIN_NTH_VIEW, nviews-1) (void) xv_destroy_safe(view);} }

See the XView Programming Manual for information on how to split canvas views using xv_set.

XV_HELP_DATA

Set XV_HELP_DATA on a text subwindow by setting it on the text subwindow's view. You can obtain the view as follows:

xv_get(textsw, OPENWIN_NTH_VIEW, O);

XV_FOCUS_RANK

XV_FOCUS_RANK specifies the focus client class for XView objects. It takes on values:

typedef enum { XV_FOCUS_SECONDARY = 0, /* default value: Ordinary Focus */ XV_FOCUS_PRIMARY = 1 /* First Class Focus */ } Xv_focus_rank;

The OPEN LOOK Mouseless Specification states that by default, textfields, numeric textfields, and scrolling lists are primary focus clients. Other XView controls default to secondary focus. The Specification also states that an application can choose to specify other controls as primary focus clients if necessary.

Scrollbars

This section discusses three scrollbar attributes:

SCROLLBAR_COMPUTE_SCROLL_PROC, SCROLLBAR_NORMALIZE_PROC, and
SCROLLBAR_MOTION.

See "Managing Your Own Scrollbar," in the XView Programming Manual's Scrollbar chapter, for more information on scrollbars.

SCROLLBAR_COMPUTE_SCROLL_PROC

This attribute has an associated function that converts physical scrollbar information into client object information. An example function call looks like:

scrollbar_compute_scroll_proc(sb, pos, available_cable, motion, &offset, &object_length)

This function should return offset and object_length.

Use default_compute_scroll_proc to perform the normal scrollbar package functionality. If you do not set a normalize_proc, the offset becomes the viewstart (after bounds checking). The scrollbar package then scrolls the object to this offset.

Code Example 2-1 contains sample code for the scrollbar_compute_scroll_proc attribute's function.

Code Example 2-1 scrollbar_compute_scroll_proc attribute function

void scrollbar_compute_scroll_proc(scrollpub, pos, avail_cable, motion, offset, object_len) Scrollbar scrollpub;

Code Example 2-1 scrollbar_compute_scroll_proc attribute function

int pos; int avail_cable; Scroll_motion motion; unsigned long *offset; unsigned long *object_len; { int new_start = TEXTSW_CANNOT_SET; int lines = 0; *obj_length = es_get_length(folio->views->esh); switch(motion) { case SCROLLBAR_ABSOLUTE: if (length == 0) new_start = pos; else new_start = *obj_length * pos / length; break; case SCROLLBAR_POINT_TO_MIN: case SCROLLBAR_MIN_TO_POINT: { if (lines == 0) lines++ /* Always make some progress */ if (motion == SCROLLBAR_MIN_TO_POINT) lines = -lines; } break; case SCROLLBAR_PAGE_FORWARD: lines = line_table.last_plus_one - 2; break; case SCROLLBAR_PAGE_BACKWARD: lines = last_plus_one+ 2; break; case SCROLLBAR_LINE_FORWARD: lines = 1; break; case SCROLLBAR_LINE_BACKWARD: lines = -1; break; case SCROLLBAR_TO_START: new_start = 0; break; case SCROLLBAR_TO_END: new_start = *obj_length;

Code Example 2-1 scrollbar_compute_scroll_proc attribute function

break; default: break; } xv_set(sb, SCROLLBAR_VIEW_LENGTH, last_plus_one - first, 0); *offset = first; return (XV_OK); }

SCROLLBAR_NORMALIZE_PROC

This attribute's function takes the offset that the scrollbar_compute_scroll_proc attribute's function returns, and adjusts it. The scrollbar package then scrolls the object to this offset.

An example function call looks like:

scrollbar_normalize_proc(sb, voffset, motion, &vstart)

This function should return vstart. Code Example 2-2 contains sample code for the scrollbar_normalize_proc attribute's function.

Code Example 2-2 scrollbar_normalize_proc attribute function

scrollbar_normalize_proc(sb, offset, motion, vs) Scrollbar sb; long unsigned offset; Scroll_motion motion; long unsigned *vs; /* new offset == new viewstart */ { line_ht = (int) xv_get(sb, SCROLLBAR_PIXELS_PER_UNIT); /* If everything in the panel is in view, then don't scroll. */ if ((int) xv_get(sb, SCROLLBAR_OBJECT_LENGTH) <= (int) xv_get(sb, SCROLLBAR_VIEW_LENGTH)) return (*vs = offset); switch(motion){ case SCROLLBAR_ABSOLUTE: case SCROLLBAR_LINE_FORWARD: case SCROLLBAR_TO_START: align_to_max = TRUE;

Code Example 2-2 scrollbar_normalize_proc attribute function

scrolling_up = TRUE; break; case SCROLLBAR_PAGE_FORWARD: case SCROLLBAR_TO_END: align_to_max = TRUE; scrolling_up = TRUE; break; case SCROLLBAR_POINT_TO_MIN: align_to_max = TRUE; scrolling_up = TRUE; break; case SCROLLBAR_MIN_TO_POINT: align_to_max = TRUE; scrolling_up = TRUE; break; case SCROLLBAR_PAGE_BACKWARD: case SCROLLBAR_LINE_BACKWARDS: align_to_max = FALSE; scrolling_up = FALSE; break; } *vs = offset; return(XV_OK); }

SCROLLBAR_MOTION

The SCROLLBAR_MOTION attribute provides the scrolling motion resulting from a scrollbar_request event. The xv_get call:

xv_get(sb, SCROLLBAR_MOTION)

returns motion, which is one of:

• ABSOLUTE
• POINT_TO_MIN (from here_to_top on menu)
• PAGE_FORWARD
• LINE_FORWARD
• MIN_TO_POINT (from top_to_here on menu)

• PAGE_BACKWARD
• LINE_BACKWARD
• TO_END
• TO_START
• PAGE_ALIGNED

XView Panel Architecture

The XView Panel class architecture, inherited from SunView, does not sufficiently deal with container classes (numeric text fields, scrolling lists, and sliders) in a backward-compatible manner. This section discusses changes that address this issue.

XV_KEY_DATA and PANEL_CLIENT_DATA Attributes

Clients use xv_set along with XV_KEY_DATA or PANEL_CLIENT_DATA and an object handle to associate a key with a piece of data for the object. When an event occurs, the client can retrieve an object handle from the event proc. The client can then use the object handle (and XV_KEY_DATA or PANEL_CLIENT_DATA) to xv_get the data.

For numeric text fields, when an event occurs inside the text field, PANEL_EVENT_PROC is called with the handle to the text field as an argument. If the client retrieves data as described above, xv_get uses the text field's handle. This can cause problems, because the event is a numeric text field event. To eliminate any problems arising from this situation, whenever clients xv_set data for the numeric text field, it is automatically xv_set (using the same key and data) for the text field. Then xv_get will always retrieve the data associated with the numeric text field.

PANEL_ITEM_OWNER Attribute

The PANEL_ITEM_OWNER attribute is now public, so the client can obtain the parent container object from the child. If PANEL_ITEM_OWNER returns a non-NULL value, the client has obtained the handle to the parent object.

For example, for numeric text fields, PANEL_ITEM_OWNER called with the associated text field as an argument returns the numeric text field. PANEL_ITEM_OWNER returns NULL when called using the numeric text field as an argument.

XV_FOCUS_RANK Attribute

The XV_FOCUS_RANK attribute has been in the public header files since the XView 3.0 release. XV_FOCUS_RANK can be used with xv_set or xv_get. XV_FOCUS_RANK should only be used on panel items that accept keyboard input in full mouseless mode. For example, any panel item affected by the mouse or the keyboard: buttons, sliders, text items, etc.

XV_FOCUS_RANK can have one of these two values: XV_FOCUS_PRIMARY or XV_FOCUS_SECONDARY. Panel items with an XV_FOCUS_RANK or XV_FOCUS_PRIMARY accept keyboard input without full mouseless mode, such as panel text items and scrolling lists. Panel items with an XV_FOCUS_RANK of XV_FOCUS_SECONDARY only accept keyboard input if full mosueless mode is turned on, such as buttons and check boxes. If keyboard focus is moved into a panel, the upper leftmost XV_FOCUS_PRIMARY panel item is given the keyboard focus.

Using the Child Handle

Retrieve and set values using the child handle through the parent container object's API. Otherwise, your applications will not be forward-compatible beyond this release. Although you can obtain the child's handle, its API is private, so is subject to change.

Panel Drop Targets

The panel drop target has a new attribute, PANEL_DROP_DELETE. The default for PANEL_DROP_DELETE is TRUE. If you set it to FALSE, all drag and drop operations dropped on the PANEL_DROP_TARGET_ITEM behave as if the user presses the Control key (resulting in a copy operation). The attribute can be set in the panel notify procedure that is called when a drop occurs. This allows you to decide, while each drop is happening, whether to allow a drag move or only a drag copy. This is a boolean attribute, and can be used with xv_create(), xv_get(), and xv_set().

Compiling XView Programs

Use the following command line to compile your XView application:

cc -I$OPENWINHOME/include file.c -L$OPENWINHOME/lib -lxview -lolgx -lX11

You must specify the following libraries when statically linking an XView application:

• -lxview
• -lolgx
• -lX11
• -lXext
• -lX11 (this is needed again by libXext)
• -lsocket
• -lnsl
• -lintl
• -lw
• -Bdynamic -ldl

You must always link the dl library in dynamically. For example:

cc -I$OPENWINHOME/include foo.c -o foo -L$OPENWINHOME/lib -Bstatic -lxview -lolgx -lX11 -lXext -lX11 -lnsl -lintl -lw -Bdynamic -ldl