'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olScrollist @(#)olScrollist	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified 10/18/89 by lmh
..
.ds cW SCROLLINGLIST
.ds rW ScrollingList
.ds nW ScrollingL
.ds wW scrollingList
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.tr ~
.nr X
.if \nX=0 .ds x} ""SCROLLINGLIST WIDGET" 3W "\&"
.if \nX=1 .ds x} ""SCROLLINGLIST WIDGET" 3W
.if \nX=2 .ds x} ""SCROLLINGLIST WIDGET" "" "\&"
.if \nX=3 .ds x} ""SCROLLINGLIST "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f4static Widget scrollinglist, textfield;
.P
\s-1\f4Args args[1];
.P
\s-1\f4scrollinglist = XtCreateWidget(\f2name\f4, \*(wWWidgetClass, ...);
XtSetArg(args[0], XtNtextField, &textfield);
XtGetValues(scrollinglist, args, 1);\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3\*(rW Components\f1
.P
Each \*(bW widget has the following parts:
.IP \(em 1.5P
Border
.IX "
.IP \(em 1.5P
Current Item
.IP \(em 1.5P
Current Item Border
.IP \(em 1.5P
Items
.IP \(em 1.5P
Scrollbar
.IP \(em 1.5P
View
.br
.ne3.5i
.BP PSART/ps.scroll1
.P
.ce
\f3Figure 1.\f1  Common Scrolling List Components
.P
If the application allows the list to be edited in place
(in the View),
the \*(bW widget uses the following components:
.IP \(em 1.5P
Editable Text Field
.br
.ne 3.5i
.BP PSART/ps.scroll2
.P
.ce
\f3Figure 2.\f1  Editable Scrolling List Additional Components
.sp
\f3Editable Scrolling List\f1
.P
The application can choose whether to allow the end user to
change the items in a scrolling list.
The Editable Text Field is the interface for entering the new
Item,
and is described later.
Other aspects of the user interface for editing are controlled
by the application.
For example,
the application can attach a menu to the scrolling list
to allow the end user to select where a new Item is to be inserted,
and can employ pop-up windows
to gather additional information about a new Item.
.sp
\f3Editing Directly in the List\(emthe Editable Text Field\f1
.P
The application can request that the \*(bW widget manage part
of the visual aspect of 
.ig
inserting a new Item or 
..
changing an
existing Item in the View.
The \*(bW widget automatically creates a widget of class
\f3TextField\f1
that implements the Editable Text Field.
The \*(bW widget manages the Editable Text Field widget as
follows:
.IP \(bu 1.5P
The application asks the \*(bW widget to "open" and "close"
the Editable Text Field.
Opening the Editable Text Field widget maps it and positions it
so that,
as the end user types in the name of a new or changed Item,
the name lines up with the existing Item names.
Closing the Editable Text Field widget unmaps it.
(As described below,
there may be times when the widget is unmapped yet still open.)
If an existing Item is being edited,
the application requests the Editable Text Field to overlay the
Item.
If a new Item is being inserted,
the application requests Items to be scrolled down in the View to
accommodate the Editable Text Field.
.IP \(bu 1.5P
The \*(bW widget maps and unmaps the Editable Text Field
widget; the application does not.
.IP \(bu 1.5P
If the end user scrolls the list while the Editable Text Field is
still open,
the \*(bW widget scrolls it with the rest of the Items.
If it has to be scrolled out of the View,
it is scrolled out entirely,
causing it to be unmapped but not closed.
The application should not try to remap the child since it will be
remapped when the list is scrolled back again.
.IP \(bu 1.5P
If the end user attempts to make a selection or set a Current
Item,
the Editable Text Field is automatically closed.
.P
The application is responsible for handling the verification
callbacks of the Editable Text Field
and for telling the \*(bW widget to add a new Item or change an
existing Item as a result of the user input.
.sp .5
\f3Selectable Scrolling List\f1
.P
The application can choose whether to allow the end user to
select Items from a scrolling list.
If Items can be selected,
they can be copied elsewhere as text,
and may be deletable ("cut");
see below for details.
.sp .5
\f3Deleting Selected Items\f1
.P
The end user can delete selected Items.
The \*(bW widget provides some deletion capabilities through
the selection mechanisms
(see the discussion under "Selecting and Operating on the
Items" below),
and the application can provide other capabilities,
such as with a pop-up menu choice.
The application verifies that each selected Item can be
deleted;
it is responsible for providing feedback to the end user for
any Items it will not delete.
The \*(bW widget updates the View to remove any deleted Items.
.sp .5
\f3Virtual List\f1
.P
The \*(bW widget "virtualizes" the list to allow the
application to use list data structures best suited to its
needs.
The \*(bW widget provides routines the application uses to
build and maintain a version of the list for the \*(bW widget
to use.
With these routines, the application:
.IP \(em 1.5P
adds new Items to the list;
.IP \(em 1.5P
deletes Items from the list;
.IP \(em 1.5P
marks Items as changed;
.IP \(em 1.5P
shifts the View to show a particular Item;
.IP \(em 1.5P
and opens and closes the Editable Text Field for a new or
changed Item.
.P
The application is responsible for defining callbacks that the
\*(bW widgets invoke when the end user
attempts to change a Current Item,
or cuts Items from the list.
Each Item is identified by the Item name that is shown in the
View for the end user,
a token assigned by the \*(bW widget that uniquely identifies
the Item,
and an attributes
\f2bit-vector\f1
that
identifies
if the Item is a Current Item.
.bp
\f3Order of Items in the Virtual List\f1
.P
The list
is assumed to have an order defined by
the application.
As it adds Items,
the application tells the \*(bW widget where to insert
them:  either before an Item already in the list
or at the end of the list.
.sp 0.75
\f3Changeable List\f1
.P
The application may change the content of a list at any time,
including while it is displayed.
The widget updates the View,
if necessary,
to reflect the changed list.
To avoid unnecessary updates to the View when several changes
need to be made,
the application can tell the \*(bW widget to avoid updates
until the changes are finished.
.sp 0.75
\f3Setting a Current Item\f1
.P
The end user can make one or more of the Items
a Current Item,
as determined by the application,
by
.IP \(em 1.5P
pressing SELECT over it,
.IP \(em 1.5P
or moving the input focus inside the Border and typing the
first letter of the Item's name.
.P
Either of these actions causes a callback to the
application,
which can decide if the Item should be made a Current Item,
remain a Current Item,
or be changed to a regular Item,
depending on the current state of the Item and the needs of the
application.
Thus, the application can make the scrolling list behave as a
set of exclusive or nonexclusive Items.
.P
Pressing SELECT also starts a selection,
as described below.
.sp 0.75
\f3Selecting and Operating on the Items\f1
.P
The \*(bW widget allows
selection
operations on the Items.
Items that are moved or copied from the View are treated as a
newline-separated list of text items,
in the order they appear in the scrolling list,
with no leading or trailing blanks on any Item.
.IP "selecting a single Item" 8
Clicking SELECT on an Item selects it and deselects any
other active selection on the screen.
.IP "selecting other Items" 8
Clicking ADJUST on an Item toggles its state,
making an unselected Item selected and a selected Item
unselected.
.IP "wipe-through selection, with SELECT" 8
Pressing and dragging SELECT over Items selects them and
deselects any other active selection on the screen.
The selection starts with the Item where SELECT is pressed
and extends to the Item where SELECT is released.
If the pointer moves above or below the View,
the View scrolls additional Items into the View,
selecting them as well.
The rate at which Items scroll into the View is the same as
when pressing SELECT on the up or down arrows of the Scrollbar.
The pointer can move out of the View to the left or right
without interrupting the selection.
.IP "wipe-through selection, with ADJUST" 8
Pressing and dragging ADJUST marks the bounds of a selection
the same way as
pressing and dragging SELECT,
except that the Items covered are "toggled".  (Previously
selected Items are deselected and previously unselected Items
are selected.)
.IP "copying Items" 8
Pressing COPY copies any selected Items to the clipboard and
deselects them.
.IP "cutting Items" 8
Pressing CUT moves any selected Items to the clipboard and
deletes them from the list.  This operation is allowed only if the
scrolling list is editable.
.P
.sp
\f3\*(rW Coloration\f1
.P
Figures 3 and 4 illustrate the resources that affect
the coloration of the \*(bW widget.
.br
.ne 3.5i
.BP PSART/ps.scroll3
.ce
\f3Figure 3.\f1  Scrolling List Coloration
.br
.ne 3.5i
.BP PSART/ps.scroll4
.P
.ce
\f3Figure 4.\f1  Selected Item and Current Item Coloration
.P
.SH "SUBSTRUCTURE"
.sp
\f3Scrollbar component\f1
.P
.nf
Name: scrollbar
Class: Scrollbar
.fi
.sp
\f3Editable Text Field component\f1
.P
.nf
Name: textfield
Class: TextField
.fi
.ds cO
.TS 
expand, allbox;
cB s s s s.
Application Resources\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNfont	XtCFont	XFontStruct *	\(dd	SI
XtNfontColor	XtCFontColor	Pixel	\(dd	I
XtNforeground	XtCForeground	Pixel	\(dd	I
XtNmaximumSize	XtCLength	int	(none)	I
XtNstring	XtCString	String	NULL	I
XtNverification	XtCCallback	XtCallbackList	NULL	I
.TE
.IP \(dd 4
\s-1The defaults are set to agree with the values of these
resources for the \*(bW widget itself.\s+1
.SH "RESOURCES"
.ds cO
.TS 
allbox;
cB s s s s.
\*(bW Resource Set\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNapplAddItem	XtCApplAddItem	OlListToken(*)()	(n/a)	G
XtNapplDeleteItem	XtCApplDeleteItem	void(*)()	(n/a)	G
XtNapplEditClose	XtCApplEditClose	void(*)()	(n/a)	G
XtNapplEditOpen	XtCApplEditClose	void(*)()	(n/a)	G
XtNapplTouchItem	XtCApplTouchItem	void(*)()	(n/a)	G
XtNapplUpdateView	XtCApplUpdateView	void(*)()	(n/a)	G
XtNapplViewItem	XtCApplViewItem	void(*)()	(n/a)	G
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(n/a)	SGI\(dg
XtNborderColor	XtCBorderColor	Pixel	Black	SGI\(dg
XtNborderPixmap	XtCPixmap	Pixmap	(n/a)	SGI\(dg
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNfont	XtCFont	XFontStruct *	(OPEN LOOK font)	SI
XtNfontColor	XtCFontColor	Pixel	Black*	SGI
XtNforeground	XtCForeground	Pixel	Black	SGI\(dg
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
XtNrecomputeWidth	XtCRecomputeWidth	Boolean	TRUE	SGI
XtNselectable	XtCSelectable	Boolean	TRUE	SGI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNtextField	XtCTextField	Widget	(none)	G
XtNtraversalOn	XtCTraversalOn	Boolean	TRUE	SGI
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNuserDeleteItems	XtCCallback	XtCallbackList	NULL	SI
XtNuserMakeCurrent	XtCCallback	XtCallbackList	NULL	SI
XtNviewHeight	XtCViewHeight	Dimension	(none)	SI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
.P
\f3OlListItem Structure\f1
.P
Several of the resources defined below use the following
\f4OlListItem\f1
structure:
.P
.in +0.5i
.nf
\f4typedef struct _OlListItem {
        int label_type;
        XtPointer label;
        XImage *glyph;
        OlBitMask attr;
} OlListItem;\f1
.fi
.in 0
.sp
.IP \f4label_type\f1 8
identifies the type of label to display for the Item in the
View.
It can have one of the values
.IP \f4OL_STRING\f1 8
for a text label;
.IP \f4OL_IMAGE\f1 8
for an image label.
.P
\f3Note:\f1
.br
\f2Only text labels are supported in this version of the \*(bW
widget, so the only value allowed is
\f4OL_STRING\f1.
Any other legal values generate an error message that tells
the application programmer that the value is not yet supported.
Any illegal values generate a different error message.
.P
.IP \f4label 8
is what to display for the Item in the View.
The type of the value of this member depends on the value of
the
\f4label_type\f1
member:
.RS 8
.IP \f4OL_STRING\f1 8
\f4String\f1
.IP \f4OL_IMAGE\f1 8
\f4XImage\f1*
.RE
.IP \f4glyph\f1 8
is currently unused.
.IP \f4attr\f1 8
defines attributes of the Item.
It is a bit vector with the bit references:
.RS 8
.IP \f4OL_LIST_ATTRIB_APPL\f1 8
for application use.
This is a mask of 16 contiguous bits that can be
subdivided as the application sees fit.
These are the low 16 bits of the value,
so no shifting is necessary to access the bits as an integer
value.
.IP \f4OL_LIST_ATTRIB_CURRENT\f1 8
if the Item is a Current Item.
.P
Other bit values are undefined but should not be used by the
application.
.RE
.sp
\f3OlListToken Structure\f1
.P
The \*(bW widget identifies each Item with a "token" of type
\f4OlListToken\f1.
The \*(bW widget assigns the token when an Item is added by the
application,
and the application uses the token in later references to the
Item.
A zero value is allowed in some contexts where an
\f4OlListToken\f1
is expected,
as a way to refer to no Item.
.P
As a convenience to the application,
the macro
\f4OlListItemPointer(token)\f1
converts an
\f4OlListToken\f1
value into a pointer to the corresponding
\f4OlListItem\f1.
The application can change the values of the
\f4OlListItem\f1
members,
but should let the \*(bW widget know that they have changed,
using the
\f4XtNapplTouchItem\f1
routine.
No checking is done for incorrect
\f4OlListToken\f1
arguments to the
\f4OlListItemPointer()\f1
macro.
.P
The
\f4OlListToken\f1
value can be coerced into the type
\f4caddr_t\f1
and back without loss of precision.
.sp
\f3XtNapplAddItem\f1
.P
This resource gives a pointer to a routine the application can
call when it adds a new Item to the list.
This routine is also used to build the list from scratch.
.P
.bp
\s+1Synopsis:\s-1\f4
.P
.in +0.5i
.nf
\f4OlListToken (*applAddItem)(), token;
.sp 0.5
\f4static Arg query[] = {
        { XtNapplAddItem, (XtArgVal)&applAddItem }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4token = (*applAddItem)(widget, parent, reference, item)
Widget widget;
OlListToken parent, reference;
OlListItem item;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.IP \f4parent\f1 8
should be set to 0, for compatibility with future changes.
.IP \f4reference\f1 8
identifies an Item before which to insert the new Item.
This value can be zero to append the new Item to the list.
.IP \f4item\f1 8
describes the new Item.
The content of the
\f4OlListItem\f1
structure is copied by the \*(bW widget into space that it
maintains;
however,
the data pointed to by the
\f4\&.label\f1
and
\f4\&.glyph\f1
members are not copied.
The application can access the copied data directly,
using the
\f4OlListItemPointer()\f1
macro to get a pointer to the
\f4OlListItem\f1
structure for the Item.
If it changes the data,
the application should use the
\f4XtNapplTouchItem\f1
routine to let the \*(bW widget know the data has changed.
.P
.bp
If mapped and if allowed by the application
(see
\f4XtNapplUpdateView\f1),
the \*(bW widget updates the View if the new Item will be in
the View.
The View is changed as little as possible:
if the new Item is in the upper half of the View, the Items
above it are scrolled up and the top Item is scrolled off;
if the new Item is in the lower half of the View, the Items
below it are scrolled down and the bottom Item is scrolled off.
.sp
.bp
\f3XtNapplDeleteItem\f1
.P
This resource gives a pointer to a routine the application can
call when it deletes an Item from the list.
.sp
.nf
\s+1Synopsis:\s-1\f4
.P
.in +0.5i
\f4void (*applDeleteItem)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplDeleteItem, (XtArgVal)&applDeleteItem }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applDeleteItem)(widget, token)
Widget widget;
OlListToken token;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.IP \f4token\f1 8
identifies the deleted Item.
.P
If mapped and if allowed by the application
(see
\f4XtNapplUpdateView\f1),
the \*(bW widget updates the View if the deleted Item was
visible.
The View is changed as little as possible:
if the deleted Item was in the upper half of the View,
Items above it are scrolled down and an Item is scrolled in
from the top;
if the deleted Item was in the lower half of the View,
Items below it are scrolled up and an Item is scrolled in
from the bottom.
If the View is already at the top or bottom, the additional Item
is scrolled in from the other end,
if possible.
.sp
\f3XtNapplEditClose\f1
.P
This resource gives a pointer to a routine the application can
call when the user has finished editing an Item in the View.
.P
.nf
\s+1Synopsis:\s-1\f4
.P
.in +0.5i
\f4void (*applEditClose)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplEditClose, (XtArgVal)&applEditClose }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applEditClose)(widget)
Widget widget;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.P
When this routine is called,
the \*(bW widget unmaps the Editable Text Field widget,
scrolling up the Items below it if they had been scrolled down
to allow an insert.
The application is responsible for calling the
\f4XtNapplAddItem\f1
routine to add the new Item,
or calling the
\f4XtNapplTouchItem\f1
routine to mark the Item as changed.
To avoid unnecessary updates to the View,
the application should add the new Item
(\f4XtNapplAddItem\f1)
or mark the changed Item
(\f4XtNapplTouchItem\f1)
before closing the Editable Text Field.
.sp
.bp
A later call to the
\f4XtNapplEditClose\f1
routine without an intervening call to the
\f4XtNapplEditOpen\f1
routine is ignored.
.P
If mapped, the \*(bW widget updates the View,
even if the application had halted updates
(see
\f4XtNapplUpdateView\f1).
If the application had halted updates,
they will continue to be halted afterwards.
.sp
\f3XtNapplEditOpen\f1
.P
This resource gives a pointer to a routine the application can
call when it wants to allow the end user to insert a new Item
or change an existing Item in the View.
.P
.nf
\s+1Synopsis:\s-1\f4
.in +0.5i
.sp 0.5
\f4void (*applEditOpen)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplEditOpen, (XtArgVal)&applEditOpen }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applEditOpen)(widget, insert, reference)
Widget widget;
Boolean insert;
OlListToken reference;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.IP \f4insert\f1 8
tells whether Items should be scrolled down to make room for
inserting a new Item.
A value of
\f4FALSE\f1
implies that an Item is being edited in place and no Items are
to be scrolled.
.IP \f4reference\f1 8
identifies an Item before which a new Item is to be inserted
(\f4insert\f1
is
\f4TRUE\f1)
or identifies the Item that is being changed
(\f4insert\f1
is
\f4FALSE\f1).
If
\f4insert\f1
is
\f4TRUE\f1,
this value can be zero to append a new Item at the end of the
list.
If
\f4insert\f1
is
\f4FALSE\f1,
this value must refer to an existing Item.
The referenced Item does not have to be in the View\(emsee below.
.P
If a new Item is being inserted,
the \*(bW widget makes room for the Editable Text Field by scrolling
down the referenced Item and any Items below it.
If the referenced Item is not in the View,
it is automatically made visible just as if the application had
called the
\f4XtNapplViewItem\f1
routine first.
.P
The
\f4XtNapplEditOpen\f1
routine can be called again before an intervening call to the
\f4XtNapplEditClose\f1
routine.
The effect is as if the
\f4XtNapplEditClose\f1
routine was called,
but without multiple updates to the View.
For example, this allows the application to
let the end user insert several new Items in succession:
the Editable Text Field moves down as each Item is inserted,
but is never removed from the View.
.P
If mapped, the \*(bW widget updates the View,
even if the application had halted updates
(see
\f4XtNapplUpdateView\f1).
If the application had halted updates,
they will continue to be halted afterwards.
.sp
.bp
\f3XtNapplTouchItem\f1
.P
This resource gives a pointer to a routine the application can
call when it changes an Item in the list.
.P
.nf
\s+1Synopsis:\s-1\f4
.in +0.5i
.sp 0.5
\f4void (*applTouchItem)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplTouchItem, (XtArgVal)&applTouchItem }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applTouchItem)(widget, token)
Widget widget;
OlListToken token;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.IP \f4token\f1 8
identifies the Item that has changed.
.P
If mapped and if allowed by the application
(see
\f4XtNapplUpdateView\f1),
the \*(bW widget updates the View if the changed Item is
visible.
.sp
\f3XtNapplUpdateView\f1
.P
This resource gives a pointer to a routine the application can
call to keep the \*(bW widget from updating the View,
or to let it again update the View.
.P
.nf
\s+1Synopsis:\s-1\f4
.in +0.5i
.sp 0.5
\f4void (*applUpdateView)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplUpdateView, (XtArgVal)&applUpdateView }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applUpdateView)(widget, ok)
Widget widget;
Boolean ok;\f1
.fi
.in 0
.IP \f4ok\f1 8
is either
\f4TRUE\f1
or
\f4FALSE\f1,
depending on whether the \*(bW can update the View as it
changes,
or not,
respectively.
.P
From the time the
\f4XtNapplUpdateView\f1
routine is called with a
\f4FALSE\f1
argument
until it is called with a
\f4TRUE\f1
argument,
the \*(bW does not update the View in response to 
application-made changes,
except:
.IP \(em 1.5P
if the application opens or closes the Editable Text Field
(cf
\f4XtNapplEditOpen\f1
and
\f4XtNapplEditClose\f1);
.IP \(em 1.5P
if the end user manipulates the list
by scrolling it,
selecting an Item,
cutting,
etc.
.P
.bp
The \*(bW widget updates the View once for each of these
exceptions,
each time an exception occurs.
.P
An application should use this routine to bracket a set of
changes
to avoid spurious changes to the View.
This routine is not needed if only one change is made to the
list.
The following example illustrates the use of the
\f4XtNapplUpdateView\f1
routine.
.P
.in +0.5i
.nf
\f4/*
 * Stop View updates.
 */
(*applViewUpdate)(widget, FALSE);
.sp 0.5
\f4/*
 * Make some changes.
 */
(*applDeleteItem)(widget, ...);
(*applDeleteItem)(widget, ...);
(*applDeleteItem)(widget, ...);
(*applAddItem)(widget, ...);
(*applTouchItem)(widget, ...);
.sp 0.5
\f4/*
 * Allow the View to be updated again.
 */
(*applViewUpdate)(widget, TRUE);\f1
.fi
.in -0.5i
.sp
\f3XtNapplViewItem\f1
.P
This resource gives a pointer to a routine the application can
call when it wants a particular Item placed in the View.
.P
.nf
\s+1Synopsis:\s-1\f4
.in +0.5i
.sp 0.5
\f4void (*applViewItem)();
.sp 0.5
\f4static Arg query[] = {
        { XtNapplViewItem, (XtArgVal)&applViewItem }
};
XtGetValues(widget, query, XtNumber(query));
.sp 0.5
\f4(*applViewItem)(widget, token)
Widget widget;
OlListToken token;\f1
.fi
.in 0
.IP \f4widget\f1 8
identifies the \*(bW widget instance.
.IP \f4token\f1 8
identifies the Item to move into the View.
.P
The Item is moved into the View in a way that minimizes the
change to the View.
If the Item is currently in the View,
nothing is changed.
If scrolling the list up or down brings the Item into the View
while keeping at least one previously viewed Item in
the View,
the list is scrolled.
Otherwise,
the Item is placed at the top of the View,
or as close to the top as possible if there aren't enough Items
in the current Level to fill the View below it.
.P
.bp
If mapped and if allowed by the application
(see
\f4XtNapplUpdateView\f1),
the \*(bW widget updates the View.
.P
.sp
\f3XtNfont\f1
.PP
Range of Values:
.br
.in +5
(any valid return from \f4XLoadQueryFont()\f1)
.in 0
.P
Default:
.P
.in +5
(chosen to match the scale and screen resolution)
.in -5
.PP
This resource identifies the font to be used to display the
Items in the View.
.P
The default value points to a cached font structure;
an application should not expect to get this value with a call to
\f4XtGetValues()\f1
and use it reliably thereafter.
.sp
\f3XtNfontColor\f1
.PP
Range of Values:
.br
.in +5
(any \f4Pixel \f1value valid for the current display)/(any name from the \f4rgb.txt \f1file)
.in -5
.PP
This resource specifies the color for the font.
If not set,
the color from the
\f4XtNforeground\f1
resource,
if available,
is used for the font.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.sp
\f3XtNforeground\f1
.P
This resource defines the foreground color for the widget.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.sp
\f3XtNrecomputeWidth\f1
.P
Range of Values:
.br
.nf
.in +5
\f4TRUE
FALSE\f1
.in -5
.fi
.P
These resources control how the \*(bW widget should respond to
requests to resize itself.  Where one of these resources is
\f4TRUE\f1, the \*(bW shrinks the View of the Content in the
corresponding direction to absorb the change in the \*(bW
widget's size.  Where one of these resources is \f4FALSE\f1,
the \*(bW does not shrink the View in that direction.
.P
.bp
These resources, together with the \f4XtNviewWidth\f1 and
\f4XtNviewHeight\f1 resources, are typically used to set a
preferred dimension in a direction that should not be scrolled.
.bp
\f3XtNselectable\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.P
This resource controls whether the end user can select Items in
the scrolling list.
If set to
\f4TRUE\f1,
then Items can be selected with SELECT and ADJUST and copied
with the COPY key.
Items may be deleted with the CUT key,
although the application can stop some or all selected Items
from being deleted. 
If set to
\f4FALSE\f1,
then Items cannot be selected and the COPY and CUT keys have
no effect.
.P
\f3XtNtextField\f1
.P
This is the widget ID of the
\f3TextField\f1
class Editable Text Field widget;
its value is available once the \*(bW widget has been created.
.P
The \*(bW widget resets the following values before returning
from each invocation of the
\f4XtNapplEditOpen\f1
routine:
.TS
center allbox;
cB s s.
Editable Text Field Reset Values
.T&
lBp-2 lBp-2 lBp-2.
Name	Class	Value
_
.T&
lp-2 lp-2 lp-2.
XtNwidth	XtCWidth	(width available in View)
XtNstring	XtCString	(name of Item to be changed)
.TE
.sp
\f3XtNtraversalOn
.P
This resource specifies whether this widget is selectable during
traversal.
.sp
\f3XtNuserDeleteItems\f1
.P
This resource defines the callbacks issued when the end user
tries to delete Items from the list.
(Currently, the only way the \*(bW widget handles deletions is
through a cut operation.)
.P
The
\f4call_data\f1
parameter points to a structure
\f4OlListDelete\f1
that looks like this:
.nf
.in +0.5i
.sp
\f4typedef struct _OlListDelete {
        OlListToken *tokens
        Cardinal num_tokens;
} OlListDelete;\f1
.fi
.in 0
.IP \f4tokens\f1 8
is a list identifying the Items to be deleted.
The application is expected to act on each Item separately,
calling the
\f4XtNapplDeleteItem\f1
routine to delete each from the list.
The application may refuse to delete some or all of the Items,
and is responsible for providing any feedback to the end-user.
.bp
.IP \f4num_tokens\f1 8
is the number of Items to delete.
.P
.sp
.bp
\f3XtNuserMakeCurrent\f1
.P
This resource defines the callbacks issued when the end user
presses SELECT over an Item.
.P
The
\f4call_data\f1
parameter is the
\f4OlListToken\f1
value that identifies the Item.
The application is expected to decide if the Current Item
status of this Item should change.
The
\f4\&.attributes\f1
member of the
\f4OlListItem\f1
structure for this Item is not automatically changed by the
\*(bW widget.
.sp
\f3XtNviewHeight\f1
.PP
Range of Values:
.br
.in +5
.nf
\f40 \(<= XtNviewHeight\f1
.in -5
.fi
.PP
This resource gives the preferred height of the View
as the number of Items to show.
If a nonzero value is given, the corresponding
\f4XtNheight\f1
resource is computed by converting this number to pixels and
adding any padding or border thickness.
In this case, any value given in the
\f4XtNheight\f1
resource is overwritten.
.P
If a zero value is given in the
\f4XtNviewHeight\f1
resource,
the
\f4XtNheight\f1
resource is used as an estimate.
The View is sized to show an integral number of Items,
such that the overall height of the \*(bW widget is less than
or equal to
\f4XtNheight\f1,
if possible.
However,
the View is always large enough to show at least one Item,
and is no shorter than the minimum scroll bar size.
.P
If neither the
\f4XtNviewHeight\f1
resource nor the
\f4XtNheight\f1
resource is set,
or both are set to zero,
the View is made as small as possible,
limited as described above.
.\" EOF
