ScrollingList(3W) UNIX System V ScrollingList(3W)
NAME
ScrollingList - a pane containing a scrollable list of text items
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <ScrollingL.h>
static Widget scrollinglist, textfield;
Args args[1];
scrollinglist = XtCreateWidget(name, scrollingListWidgetClass, ...);
XtSetArg(args[0], XtNtextField, &textfield);
XtGetValues(scrollinglist, args, 1);
DESCRIPTION
ScrollingList Components
Each ScrollingList widget has the following parts:
- Border
- Current Item
- Current Item Border
- Items
- Scrollbar
- View
Figure 1. Common Scrolling List Components
If the application allows the list to be edited in place (in the View),
the ScrollingList widget uses the following components:
- Editable Text Field
Figure 2. Editable Scrolling List Additional Components
Editable Scrolling List
The application can choose whether to allow the end user to add, change,
and/or delete the items in a scrolling list. The Editable Text Field is
the interface for entering, or changing the 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.
10/89 Page 1
ScrollingList(3W) UNIX System V ScrollingList(3W)
Editing Directly in the List-the Editable Text Field
The application can request that the ScrollingList widget manage part of
the visual aspect of changing an existing Item in the View. The
ScrollingList widget automatically creates a widget of class TextField
that implements the Editable Text Field. The ScrollingList widget
manages the Editable Text Field widget as follows:
⊕ The application asks the ScrollingList 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.
⊕ The ScrollingList widget maps and unmaps the Editable Text Field widget;
the application does not.
⊕ If the end user scrolls the list while the Editable Text Field is still
open, the ScrollingList 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.
⊕ If the end user attempts to make a selection or set a Current Item, the
Editable Text Field is automatically closed.
The application is responsible for handling the verification callbacks of
the Editable Text Field and for telling the ScrollingList widget to add a
new Item or change an existing Item as a result of the user input.
Selectable Scrolling List
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.
Deleting Selected Items
The end user can delete selected Items. The ScrollingList 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 ScrollingList widget updates the View to
remove any deleted Items.
Page 2 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
Virtual List
The ScrollingList widget "virtualizes" the list to allow the application
to use list data structures best suited to its needs. The ScrollingList
widget provides routines the application uses to build and maintain a
version of the list for the ScrollingList widget to use. With these
routines, the application:
- adds new Items to the list;
- deletes Items from the list;
- edit items and mark them as changed;
- shifts the View to show a particular Item;
- and opens and closes the Editable Text Field for a new or changed Item.
The application is responsible for defining callbacks that the
ScrollingList 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 ScrollingList widget that uniquely identifies the Item,
and an attributes bit-vector that identifies if the Item is a Current
Item.
Order of Items in the Virtual List
The list is assumed to have an order defined by the application. As it
adds Items, the application tells the ScrollingList widget where to
insert them: either before or after an Item already in the list.
Changeable List
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
ScrollingList widget to avoid updates until the changes are finished.
Setting a Current Item
The end user can make one or more of the Items a Current Item, as
determined by the application, by
- clicking or pressing SELECT over it,
- or moving the input focus inside the Border and typing the first letter
of the Item's name.
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.
10/89 Page 3
ScrollingList(3W) UNIX System V ScrollingList(3W)
Clicking or pressing SELECT also starts a selection, as described below.
Selecting and Operating on the Items
The ScrollingList 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.
selecting a single Item
Clicking SELECT on an Item selects it and deselects any other
active selection on the screen.
selecting other Items
Clicking ADJUST on an Item toggles its state, making an
unselected Item selected and a selected Item unselected.
wipe-through selection, with SELECT
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.
wipe-through selection, with ADJUST
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.)
copying Items
Pressing COPY copies any selected Items to the clipboard and
deselects them.
cutting Items
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.
Coloration
On a monochrome display, the ScrollingList widget indicates that it has
input focus by inverting foreground and background colors. When an
editable Text Field has input focus, it shows that it has input focus by
showing an active caret.
On color displays, the ScrollingList widget shows that the Current Item
has input focus by filling the background of the Current Item with the
input focus color set in the XtNinputFocusColor resource. When a
Page 4 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
selected item has input focus, the label is drawn with the input focus
color. When an item is both Selected and Current, it shows that it has
input focus by drawing the text of the label in the input focus color.
When an editable Text Field has input focus, it shows that it has input
focus by showing an active caret in the input focus color.
EXCEPTIONS:
If the input focus color is the same as either the background,
foreground, or font color, then revert to the monochrome coloration
scheme.
Figures 3 and 4 illustrate the resources that affect the coloration of
the ScrollingList widget.
Figure 3. Scrolling List Coloration
Figure 4. Selected Item and Unselected Item Coloration
Keyboard Traversal
The default value of the XtNtraversalOn resource is True.
The ScrollingList widget responds to the following keyboard navigation
keys:
- NEXT_FIELD moves to the next traversable widget in the window
- PREV_FIELD moves to the previous traversable widget in the window
- NEXTWINDOW moves to the next window in the application
- PREVWINDOW moves to the previous window in the application
- NEXTAPP moves to the first window in the next application
- PREVAPP moves to the first window in the previous application
- MOVEUP moves the input focus up one line
- MOVEDOWN moves the input focus down one line
- PANESTART moves the input focus to the first item in the pane
- PANEEND moves the input focus to the last item in the pane
- SCROLLUP scrolls up one item in the list
- SCROLLDOWN scrolls down one item in the list
- SCROLLTOP scrolls to the first item in the list
10/89 Page 5
ScrollingList(3W) UNIX System V ScrollingList(3W)
- SCROLLBOTTOM scrolls to the last item in the list
- PAGEUP scrolls up one page so that the first item visible is the last
item visible in the pane
- PAGEDOWN scrolls down one page so that the last item visible is the
first item visible in the pane
When an Editable Text Field is in the ScrollingList, the keyboard
traversal keys defined for TextField widgets apply.
The SELECTKEY selects the Current Item and unselects any other active
selection on the screen. The ADJUSTKEY toggles the Current Item's state,
making an unselected Item selected and a selected Item unselected.
Note that the scrolling keys of interest are defined with in the
ScrollingList and traversal to the Scrollbar is not necessary to
manipulate the ScrollingList.
_________________________________________________________________________
| Scrolling List Activation Types |
|____________________________|___________________________________________|
| Activation Type | Expected Results |
|____________________________|___________________________________________|
| OL_MENUKEY | Popup scrolling List menu |
|____________________________|___________________________________________|
Display of Keyboard Mnemonic
The ScrollingList widget displays the mnemonic accelerator for each item
as part of its label. If the mnemonic character is in the label, then
that character is displayed/highlighted according to the value returned
by OlQueryMnemonicDisplay(). If the mnemonic character is not in the
label, it is displayed to the right of the label in parenthesis and
highlighted according to the value returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parenthesis is
truncated as a unit.
Page 6 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
SUBSTRUCTURE
Scrollbar component
Name: scrollbar
Class: Scrollbar
Editable Text Field component
Name: textfield
Class: TextField
_____________________________________________________________________
| Application Resources |
|________________|_______________|________________|_________|________|
| Name | Class | Type | Default| Access|
|________________|_______________|________________|_________|________|
|________________|_______________|________________|_________|________|
| XtNfont | XtCFont | XFontStruct * | ‡ | SI |
|________________|_______________|________________|_________|________|
| XtNfontColor | XtCFontColor | Pixel | ‡ | I |
|________________|_______________|________________|_________|________|
| XtNforeground | XtCForeground| Pixel | ‡ | I |
|________________|_______________|________________|_________|________|
| XtNmaximumSize | XtCLength | int | (none) | I |
|________________|_______________|________________|_________|________|
| XtNstring | XtCString | String | NULL | I |
|________________|_______________|________________|_________|________|
| XtNverification| XtCCallback | XtCallbackList| NULL | I |
|________________|_______________|________________|_________|________|
‡ The defaults are set to agree with the values of these resources for
the ScrollingList widget itself.
RESOURCES
____________________________________________________________________________________________
| ScrollingList Resource Set |
|_____________________|______________________|__________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|__________________|__________________|________|
____________________________________________________________________________________________
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
10/89 Page 7
ScrollingList(3W) UNIX System V ScrollingList(3W)
____________________________________________________________________________________________
| ScrollingList Resource Set (cont'd) |
|_____________________|______________________|__________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|__________________|__________________|________|
____________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
____________________________________________________________________________________________
XtNbackgroundPixmap XtCPixmap Pixmap (n/a) SGI†
____________________________________________________________________________________________
XtNborderColor XtCBorderColor Pixel Black SGI†
____________________________________________________________________________________________
XtNborderPixmap XtCPixmap Pixmap (n/a) SGI†
____________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SG
____________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
____________________________________________________________________________________________
XtNfont XtCFont XFontStruct * (OPEN LOOK font) SI
____________________________________________________________________________________________
XtNfontColor XtCFontColor Pixel Black* SGI
____________________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI†
____________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
____________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
____________________________________________________________________________________________
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
____________________________________________________________________________________________
XtNrecomputeWidth XtCRecomputeWidth Boolean TRUE SGI
____________________________________________________________________________________________
XtNreferenceName XtCReferenceName String NULL GI
____________________________________________________________________________________________
XtNreferenceWidget XtCReferenceWidget Widget NULL GI
____________________________________________________________________________________________
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 Cardinal (none) SI
____________________________________________________________________________________________
Page 8 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
____________________________________________________________________________________________
| ScrollingList Resource Set (cont'd) |
|_____________________|______________________|__________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|__________________|__________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|__________________|__________________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|__________________|__________________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|__________________|__________________|________|
OlListItem Structure
Several of the resources defined below use the following OlListItem
structure:
typedef struct _OlListItem {
OlDefine label_type;
XtPointer label;
XImage *glyph;
OlBitMask attr;
XtPointer user_data;
unsigned char mnemonic;
} OlListItem;
labeltype
identifies the type of label to display for the Item in the View.
It can have one of the values
OLSTRING
for a text label;
OLIMAGE
for an image label.
Note:
Only text labels are supported in this version of the ScrollingList
widget, so the only value allowed is OLSTRING. 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.
label is what to display for the Item in the View. The type of the
value of this member depends on the value of the labeltype
member:
OLSTRING
String
10/89 Page 9
ScrollingList(3W) UNIX System V ScrollingList(3W)
OLIMAGE
XImage*
glyph is currently unused.
attr defines attributes of the Item. It is a bit vector with the bit
references:
OLLISTATTRIBAPPL
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.
OLLISTATTRIBCURRENT
if the Item is a Current Item.
Other bit values are undefined but should not be used by the
application.
mnemonic
is a single character that is used as a mnemonic accelerator for
keyboard traversal.
OlListToken Structure
The ScrollingList widget identifies each Item with a "token" of type
OlListToken. The ScrollingList 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 OlListToken is expected, as a way to refer to no Item.
As a convenience to the application, the function
OlListItemPointer(token) converts an OlListToken value into a pointer to
the corresponding OlListItem. The application can change the values of
the OlListItem members, but should let the ScrollingList widget know that
they have changed, using the XtNapplTouchItem routine. No checking is
done for incorrect OlListToken arguments to the OlListItemPointer()
function.
The OlListToken value can be coerced into the type XtPointer and back
without loss of precision.
XtNapplAddItem
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.
Synopsis:
Page 10 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
OlListToken (*applAddItem)(), token;
static Arg query[] = {
{ XtNapplAddItem, (XtArgVal)&applAddItem }
};
XtGetValues(widget, query, XtNumber(query));
token = (*applAddItem)(widget, parent, reference, item)
Widget widget;
OlListToken parent, reference;
OlListItem item;
widget identifies the ScrollingList widget instance.
parent should be set to 0, for compatibility with future changes.
reference
identifies an Item before which to insert the new Item. This
value can be zero to append the new Item to the list.
item describes the new Item. The content of the OlListItem structure
is copied by the ScrollingList widget into space that it
maintains; however, the data pointed to by the label and glyph
members are not copied. The application can access the copied
data directly, using the OlListItemPointer() function to get a
pointer to the OlListItem structure for the Item. If it changes
the data, the application should use the XtNapplTouchItem routine
to let the ScrollingList widget know the data has changed.
If mapped and if allowed by the application (see XtNapplUpdateView), the
ScrollingList 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.
XtNapplDeleteItem
This resource gives a pointer to a routine the application can call when
it deletes an Item from the list.
Synopsis:
void (*applDeleteItem)();
static Arg query[] = {
{ XtNapplDeleteItem, (XtArgVal)&applDeleteItem }
};
XtGetValues(widget, query, XtNumber(query));
(*applDeleteItem)(widget, token)
Widget widget;
OlListToken token;
10/89 Page 11
ScrollingList(3W) UNIX System V ScrollingList(3W)
widget identifies the ScrollingList widget instance.
token identifies the deleted Item.
If mapped and if allowed by the application (see XtNapplUpdateView), the
ScrollingList 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.
XtNapplEditClose
This resource gives a pointer to a routine the application can call when
the user has finished editing an Item in the View.
Synopsis:
void (*applEditClose)();
static Arg query[] = {
{ XtNapplEditClose, (XtArgVal)&applEditClose }
};
XtGetValues(widget, query, XtNumber(query));
(*applEditClose)(widget)
Widget widget;
widget identifies the ScrollingList widget instance.
When this routine is called, the ScrollingList 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 XtNapplAddItem routine to add the new Item, or calling the
XtNapplTouchItem routine to mark the Item as changed. To avoid
unnecessary updates to the View, the application should add the new Item
(XtNapplAddItem) or mark the changed Item (XtNapplTouchItem) before
closing the Editable Text Field.
A later call to the XtNapplEditClose routine without an intervening call
to the XtNapplEditOpen routine is ignored.
If mapped, the ScrollingList widget updates the View, even if the
application had halted updates (see XtNapplUpdateView). If the
application had halted updates, they will continue to be halted
afterwards.
XtNapplEditOpen
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.
Page 12 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
Synopsis:
void (*applEditOpen)();
static Arg query[] = {
{ XtNapplEditOpen, (XtArgVal)&applEditOpen }
};
XtGetValues(widget, query, XtNumber(query));
(*applEditOpen)(widget, insert, reference)
Widget widget;
Boolean insert;
OlListToken reference;
widget identifies the ScrollingList widget instance.
insert tells whether Items should be scrolled down to make room for
inserting a new Item. A value of FALSE implies that an Item is
being edited in place and no Items are to be scrolled.
reference
identifies an Item before which a new Item is to be inserted
(insert is TRUE) or identifies the Item that is being changed
(insert is FALSE). If insert is TRUE, this value can be zero to
append a new Item at the end of the list. If insert is FALSE,
this value must refer to an existing Item. The referenced Item
does not have to be in the View-see below.
If a new Item is being inserted, the ScrollingList 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
XtNapplViewItem routine first.
The XtNapplEditOpen routine can be called again before an intervening
call to the XtNapplEditClose routine. The effect is as if the
XtNapplEditClose 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.
If mapped, the ScrollingList widget updates the View, even if the
application had halted updates (see XtNapplUpdateView). If the
application had halted updates, they will continue to be halted
afterwards.
XtNapplTouchItem
This resource gives a pointer to a routine the application can call when
it changes an Item in the list.
10/89 Page 13
ScrollingList(3W) UNIX System V ScrollingList(3W)
Synopsis:
void (*applTouchItem)();
static Arg query[] = {
{ XtNapplTouchItem, (XtArgVal)&applTouchItem }
};
XtGetValues(widget, query, XtNumber(query));
(*applTouchItem)(widget, token)
Widget widget;
OlListToken token;
widget identifies the ScrollingList widget instance.
token identifies the Item that has changed.
If mapped and if allowed by the application (see XtNapplUpdateView), the
ScrollingList widget updates the View if the changed Item is visible.
XtNapplUpdateView
This resource gives a pointer to a routine the application can call to
keep the ScrollingList widget from updating the View, or to let it update
the View again.
Synopsis:
void (*applUpdateView)();
static Arg query[] = {
{ XtNapplUpdateView, (XtArgVal)&applUpdateView }
};
XtGetValues(widget, query, XtNumber(query));
(*applUpdateView)(widget, ok)
Widget widget;
Boolean ok;
ok is either TRUE or FALSE, depending on whether the ScrollingList
can update the View as it changes, or not, respectively.
From the time the XtNapplUpdateView routine is called with a FALSE
argument until it is called with a TRUE argument, the ScrollingList does
not update the View in response to application-made changes, except:
- if the application opens or closes the Editable Text Field (cf
XtNapplEditOpen and XtNapplEditClose);
- if the end user manipulates the list by scrolling it, selecting an Item,
cutting, etc.
The ScrollingList widget updates the View once for each of these
exceptions, each time an exception occurs.
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
Page 14 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
one change is made to the list. The following example illustrates the
use of the XtNapplUpdateView routine.
/*
* Stop View updates.
*/
(*applUpdateView)(widget, FALSE);
/*
* Make some changes.
*/
(*applDeleteItem)(widget, ...);
(*applDeleteItem)(widget, ...);
(*applDeleteItem)(widget, ...);
(*applAddItem)(widget, ...);
(*applTouchItem)(widget, ...);
/*
* Allow the View to be updated again.
*/
(*applUpdateView)(widget, TRUE);
XtNapplViewItem
This resource gives a pointer to a routine the application can call when
it wants a particular Item placed in the View.
Synopsis:
void (*applViewItem)();
static Arg query[] = {
{ XtNapplViewItem, (XtArgVal)&applViewItem }
};
XtGetValues(widget, query, XtNumber(query));
(*applViewItem)(widget, token)
Widget widget;
OlListToken token;
widget identifies the ScrollingList widget instance.
token identifies the Item to move into the View.
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.
If mapped and if allowed by the application (see XtNapplUpdateView), the
ScrollingList widget updates the View.
10/89 Page 15
ScrollingList(3W) UNIX System V ScrollingList(3W)
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
This resource identifies the font to be used to display the Items in the
View.
The default value points to a cached font structure; an application
should not expect to get this value with a call to XtGetValues() and use
it reliably thereafter.
XtNfontColor
Range of Values:
(any Pixel value valid for the current display)/(any name from the
rgb.txt file)
This resource specifies the color for the font. If not set, the color
from the XtNforeground resource, if available, is used for the font.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNforeground
This resource defines the foreground color for the widget.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNrecomputeWidth
Range of Values:
TRUE
FALSE
This resource controls how the ScrollingList widget should respond to
requests to resize itself. If this resource is TRUE, the ScrollingList
shrinks the View of the Content in the corresponding direction to absorb
the change in the ScrollingList widget's size. If this resource is
FALSE, the ScrollingList does not shrink the View in that direction.
This resource, together with the XtNviewHeight resource, are typically
used to set a preferred dimension in a direction that should not be
scrolled.
Page 16 10/89
ScrollingList(3W) UNIX System V ScrollingList(3W)
XtNselectable
Range of Values:
TRUE
FALSE
This resource controls whether the end user can select Items in the
scrolling list. If set to TRUE, 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 FALSE, then Items cannot be selected and
the COPY and CUT keys have no effect.
XtNtextField
This is the widget ID of the Editable Text Field widget; its value is
available once the ScrollingList widget has been created.
The ScrollingList widget resets the following values before returning
from each invocation of the XtNapplEditOpen routine:
______________________________________________________
| Editable Text Field Reset Values |
|__________|___________|______________________________|
| Name | Class | Value |
|__________|___________|______________________________|
|__________|___________|______________________________|
| XtNwidth | XtCWidth | (width available in View) |
|__________|___________|______________________________|
| XtNstring| XtCString| (name of Item to be changed)|
|__________|___________|______________________________|
XtNtraversalOn
This resource specifies whether this widget is selectable during
traversal.
XtNuserDeleteItems
This resource defines the callbacks issued when the end user tries to
delete Items from the list. (Currently, the only way the ScrollingList
widget handles deletions is through a cut operation.)
The calldata parameter points to a structure OlListDelete that looks
like this:
typedef struct OlListDelete {
OlListToken *tokens
Cardinal numtokens;
} OlListDelete;
10/89 Page 17
ScrollingList(3W) UNIX System V ScrollingList(3W)
tokens is a list identifying the Items to be deleted. The application
is expected to act on each Item separately, calling the
XtNapplDeleteItem 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.
numtokens
is the number of Items to delete.
XtNuserMakeCurrent
This resource defines the callbacks issued when the end user presses
SELECT over an Item.
The calldata parameter is the OlListToken value that identifies the
Item. The application is expected to decide if the Current Item status
of this Item should change. The attributes member of the OlListItem
structure for this Item is not automatically changed by the ScrollingList
widget.
XtNviewHeight
Range of Values:
0 < XtNviewHeight
This resource gives the preferred height of the View as the number of
Items to show. If a nonzero value is given, the corresponding XtNheight
resource is computed by converting this number to pixels and adding any
padding or border thickness. In this case, any value given in the
XtNheight resource is overwritten.
If a zero value is given in the XtNviewHeight resource, the XtNheight
resource is used as an estimate. The View is sized to show an integral
number of Items, such that the overall height of the ScrollingList widget
is less than or equal to XtNheight, if possible. However, the View is
always large enough to show at least one Item, and is no shorter than the
minimum scrollbar size.
If neither the XtNviewHeight resource nor the XtNheight resource is set,
or both are set to zero, the View is made as small as possible, limited
as described above.
Page 18 10/89