WIDGET CLASS NAME

ScrollingList

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

If the application allows the list to be edited in place (in the View), the ScrollingList widget uses the following components:

—Editable Text Field
Editable Scrolling List

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

—marks Items 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 an Item already in the list or at the end of 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

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

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.

ScrollingList Coloration The following diagram illustrates the resources that affect the coloration of the ScrollingList widget. 

SUBSTRUCTURE

Scrollbar component

Name: scrollbar
Class: Scrollbar

Editable Text Field component

Name: textfield
Class: TextField

Application Resources
           Name            Type   Default  Access
        XtNfont   XFontStruct ∗      ‡      SI
   XtNfontColor           Pixel      ‡       I
  XtNforeground           Pixel      ‡       I
 XtNmaximumSize             int    (none)       I
      XtNstring          String      NULL       I XtNverification  XtCallbackList      NULL       I

‡The defaults are set to agree with the values of these resources for the ScrollingList widget itself.

RESOURCES

ScrollingList Resource Set\\∗(cO
                Name              Type       Default   Access XtNancestorSensitive           Boolean          TRUE       G∗
      XtNapplAddItem  OlListToken(∗)()         (n/a)        G
   XtNapplDeleteItem         void(∗)()         (n/a)        G
    XtNapplEditClose         void(∗)()         (n/a)        G
     XtNapplEditOpen         void(∗)()         (n/a)        G
    XtNapplTouchItem         void(∗)()         (n/a)        G
   XtNapplUpdateView         void(∗)()         (n/a)        G
     XtNapplViewItem         void(∗)()         (n/a)        G
       XtNbackground             Pixel         White  SGI†
 XtNbackgroundPixmap            Pixmap         (n/a)  SGI†
      XtNborderColor             Pixel         Black  SGI†
     XtNborderPixmap            Pixmap         (n/a)  SGI†
            XtNdepth               int    (parent’s)       GI
  XtNdestroyCallback    XtCallbackList          NULL       SI
             XtNfont     XFontStruct ∗  (OPEN LOOK font)       SI
        XtNfontColor             Pixel        Black∗      SGI
       XtNforeground             Pixel         Black  SGI†
           XtNheight         Dimension  (calculated)      SGI XtNmappedWhenManaged           Boolean          TRUE      SGI
   XtNrecomputeWidth           Boolean          TRUE      SGI
       XtNselectable           Boolean          TRUE      SGI
        XtNsensitive           Boolean          TRUE      GI∗
        XtNtextField            Widget        (none)        G
      XtNtraversalOn           Boolean          TRUE      SGI
         XtNuserData         XtPointer          NULL      SGI
  XtNuserDeleteItems    XtCallbackList          NULL       SI
  XtNuserMakeCurrent    XtCallbackList          NULL       SI
       XtNviewHeight         Dimension        (none)       SI
            XtNwidth         Dimension  (calculated)      SGI
                XtNx          Position             0      SGI
                XtNy          Position             0      SGI

OlListItem Structure

Several of the resources defined below use the following OlListItem structure:

typedef struct _OlListItem {
        int label_type;
        XtPointer label;
        XImage ∗glyph;
        OlBitMask attr;
} OlListItem;

label_type
identifies the type of label to display for the Item in the View. It can have one of the values

OL_STRING
for a text label;

OL_IMAGE
for an image label.

Note:
Only text labels are supported in this version of the ScrollingList widget, so the only value allowed is OL_STRING.  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. 

labelis what to display for the Item in the View.  The type of the value of this member depends on the value of the label_type member:

OL_STRING
String

OL_IMAGE
XImage∗

glyphis currently unused. 

attrdefines attributes of the Item.  It is a bit vector with the bit references:

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

OL_LIST_ATTRIB_CURRENT
if the Item is a Current Item.

Other bit values are undefined but should not be used by the application. 

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 macro 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() macro. 

The OlListToken value can be coerced into the type caddr_t 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:

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;

widgetidentifies the ScrollingList widget instance. 

parentshould be set to 0, for compatibility with future changes. 

referenceidentifies an Item before which to insert the new Item.  This value can be zero to append the new Item to the list. 

itemdescribes 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() macro 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;

widgetidentifies the ScrollingList widget instance. 

tokenidentifies 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;

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

Synopsis:

void (∗applEditOpen)();
static Arg query[] = {
        { XtNapplEditOpen, (XtArgVal)&applEditOpen }
};
XtGetValues(widget, query, XtNumber(query));
(∗applEditOpen)(widget, insert, reference)
Widget widget;
Boolean insert;
OlListToken reference;

widgetidentifies the ScrollingList widget instance. 

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

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

Synopsis:

void (∗applTouchItem)();
static Arg query[] = {
        { XtNapplTouchItem, (XtArgVal)&applTouchItem }
};
XtGetValues(widget, query, XtNumber(query));
(∗applTouchItem)(widget, token)
Widget widget;
OlListToken token;

widgetidentifies the ScrollingList widget instance. 

tokenidentifies 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 again update the View. 

Synopsis:

void (∗applUpdateView)();
static Arg query[] = {
        { XtNapplUpdateView, (XtArgVal)&applUpdateView }
};
XtGetValues(widget, query, XtNumber(query));
(∗applUpdateView)(widget, ok)
Widget widget;
Boolean ok;

okis 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 one change is made to the list.  The following example illustrates the use of the XtNapplUpdateView routine. 

/∗
 ∗ Stop View updates.
 ∗/
(∗applViewUpdate)(widget, FALSE);
/∗
 ∗ Make some changes.
 ∗/
(∗applDeleteItem)(widget, ...);
(∗applDeleteItem)(widget, ...);
(∗applDeleteItem)(widget, ...);
(∗applAddItem)(widget, ...);
(∗applTouchItem)(widget, ...);
/∗
 ∗ Allow the View to be updated again.
 ∗/
(∗applViewUpdate)(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;

widgetidentifies the ScrollingList widget instance. 

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

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(3W).  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(3W).  XtNrecomputeWidth

Range of Values:

TRUE
FALSE

These resources control how the ScrollingList widget should respond to requests to resize itself.  Where one of these resources is TRUE, the ScrollingList shrinks the View of the Content in the corresponding direction to absorb the change in the ScrollingList widget’s size.  Where one of these resources is FALSE, the ScrollingList does not shrink the View in that direction. 

These resources, together with the XtNviewWidth and XtNviewHeight resources, are typically used to set a preferred dimension in a direction that should not be scrolled.  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 TextField class 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   Value
 XtNwidth  (width available in View) XtNstring  (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 call_data parameter points to a structure OlListDelete that looks like this:

typedef struct _OlListDelete {
        OlListToken ∗tokens
        Cardinal num_tokens;
} OlListDelete;

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

num_tokens
is the number of Items to delete.

XtNuserMakeCurrent

This resource defines the callbacks issued when the end user presses SELECT over an Item. 

The call_data 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 scroll bar 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. 

Sun Release 4.0  —  Last change: 1/8/90