X11ListPane

X11ListlPane Class

The X11ListPane class displays a scrolling list of items. Clicking the left pointer buttons selects an item, which is available to the program for as long as the X11ListPane object is available.

The list may be larger than the pane can display at one time, and the list may be scrolled using the scrollbar on the left edge of the pane, or the up and down arrow keys, or the C-p and C-n keys.

Here is a program that displays a X11ListPane object, and prints the selected item on the terminal when the program exits.

Clicking on an item using the left mouse button (or the single button on pointing devices that have only one button) selects that item. Clicking on the item again de-selects the item, or if a different item is clicked, then that item is selected.

If the user presses the Shift key while clicking on an item, it is selected in addition to any items that have already been selected.

Pressing the Ctrl key while clicking selects every item in a range between the first selected item in the list and the last selected item.

/* listpane.ca, a X11ListPane demonstration. -*-c-*- */

#define N_ITEMS 30

#include <ctalk/ctalkdefs.h>

int main (int argv, char **argc) {
  X11Pane new xPane;
  X11PaneDispatcher new dispatcher;
  X11ListPane new listPane;
  X11LabelPane new label;
  X11ButtonPane new button;
  InputEvent new e;
  Integer new nEvents;
  Integer new verbose;
  Integer new i;
  X11Cursor new cursor;
  String new itemText, itemN;
  List new itemTextOut, itemNOut;

  xPane ftFontVar initFontLib;
  listPane selectFont;
  label selectFont;

  xPane resources atPut "backgroundColor", "blue";
  label resources replaceAt "backgroundColor", "blue";
  label resources replaceAt "foregroundColor", "blue";
  label resources replaceAt "highlightForegroundColor", "blue";
  label resources replaceAt "textColor", "white";
  label resources replaceAt "highlightTextColor", "white";
  label border = false;

  xPane inputStream eventMask = EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY| \
    KEYPRESS|KEYRELEASE|WINDELETE|BUTTONPRESS|BUTTONRELEASE|MOTIONNOTIFY| \
    SELECTIONCLEAR|SELECTIONREQUEST;
  xPane initialize 300, 400;
  dispatcher attachTo xPane;
  label attachTo dispatcher, "100x70+10+30%";
  button attachTo dispatcher, "60x45+50%+-75";
  listPane attachTo dispatcher, "-15x-90+100+24";

  for (i = 1; i < N_ITEMS; ++i) {
    listPane add "item " + i asString;
  }
  
  xPane map;
  xPane raiseWindow;

  xPane openEventStream;

  xPane setWMTitle "X11TextListPane Demo";
  label multiLine "Select\nan\nItem";
  button label text "Done";

  listPane draw;
  listPane refresh;

  while (TRUE) {
    xPane inputStream queueInput;
    if (xPane inputStream eventPending) {
      e become xPane inputStream inputQueue unshift;

      xPane subPaneNotify e;

      switch (e eventClass value)
        {
        case WINDELETE:
          xPane deleteAndClose;
          exit (0);
          break;
        default:
          if (button haveClick) {
            button clearClick;
            xPane deleteAndClose;
	    if (listPane nItemsSelected > 1) {
	      i = 0;
	      listPane selectedItems itemTextOut;
	      listPane selectedItemsN itemNOut;
	      itemNOut map {
		itemN = self;
		/* This is a convenient way to retrieve
		   the i'th item in the itemTextOut list. */
		itemText = *(itemTextOut + i);
		printf ("%d: %s\n", itemN, itemText);
		++i;
	      }
	    } else {
	      printf ("%d: %s\n",
		      listPane selectedItemN,
		      listPane selectedItemText);
	    }
            exit (0);
          }
        break;
        }
    }
  }
}

Retrieving Selected Items

The method nItemsSelected returns the number of list items that are currently selected. If only one item is selected, a program use the selectedItemN and selectedItem methods to retrieve the selected item’s position in the list, and its text. This example shows how to print the list’s selection when only one item is selected.

if (myListPane nItemsSelected == 1) {
   printf ("%d: %s.\n", myListPane selectedItemN,
     myListPane selectedItemText);
}

If there are multiple items selected (i.e., nItemsSelected returns an Integer greater than 1), a program can retrieve and display all of the results the selectedItems and selectedItemsN methods, and display all of the results using an expression like this (although this example doesn’t print both sets of results at once).

List new itemTextOut, itemNOut;

...

if (myListPane nItemsSelected > 1) {
   myListPane selectedItems itemTextOut;
   myListPane selectedItemsN itemNOut;
   itemNOut map {
     printf ("%d\n", self) 
   }
   itemTextOut map {
     printf ("%s\n", self) 
   }
}

Resources

borderColor

A String that contains the named color of the pane’s border. The default is ‘gray’.

borderWidth

An Integer that defines the width in pixels of the pane’s border The default is ‘2’ pixels.

font

A String that contains the Fontconfig descriptor of the font used to display the list items. The default is ‘sans serif-12’.

keyScrollIncrement

The distance in pixels the list should scroll up or down when the user scrolls the list. The default is 4 pixels.

leftMargin

An Integer that defines the width in pixels of between the left edge of pane’s list area and the left margin of the item text. The default is 4 pixels.

scrollBorderColor

A String that contains the color for the edges of the scroll channel. The default is ‘darkgray’.

scrollBorderWidth

An Integer that contains the width in pixels of the scroll channel’s border. The default is 1 pixel.

selectColor

A String that contains the background color of selected items. The default is ‘lightblue’.

selectStyle

An Integer that defines whether a select bar extends to the right edge of an item’s text, or to the right margin of the pane. The class recognizes the #defines ‘LIST_SELECT_PANE’ and ‘LIST_SELECT_ITEM’, which are defined in ctalkdefs.h. The default is ‘LIST_SELECT_PANE’, so to change it to only highlight an item’s text, a program should contain the line,

myListPane resources replaceAt "selectStyle", LIST_SELECT_ITEM;

textColor

A String that contains the color of the list text. The default is ‘black’.

thumbColor

A String that defines the color of the scroll bar’s thumb. The default is ‘darkgray’.

thumbMargin

An Integer that defines the distance in pixels between the thumb and its channel. The default is 2 pixels.

vAlignHint

An Integer that helps display items vertically centered in their layout boxes. While X11ListPane objects generally can approximate how font renderers align text within their layout boxes, fonts and even different library versions may vary this. Increasing this number shifts the item’s text downward within the box when it is displayed. Smaller numbers (including negative numbers) shift the text upward. The default is 2px.

Instance Variables

borderPen

A Pen object that contains the color and width of the border. Its values are defined by the ‘borderColor’ and ‘borderWidth’ resources.

buttonState

An Integer that records whether any of the pointer buttons are pressed. The possible values may be any combination of the following definitions, or none (‘0’).

BUTTON1MASK     (1 << 0)
BUTTON2MASK     (1 << 1)
BUTTON3MASK     (1 << 2)

items

A List that contains the pane’s list items. Each item uses an ItemBox object to store its information. The definition of the ItemBox class (which is also defined in the X11ListPane class library) is:

String class ItemBox;

ItemBox instanceVariable org Point 0;
ItemBox instanceVariable ext Point 0;
ItemBox instanceVariable size Point 0;

iInit

An Integer that simply causes the drawItemList method to wait for class to initialize the fonts it needs.

scrollBorderPen

A Pen object that contains the width and the color of the scroll channel’s borders. Its values are set by the ‘scrollBorderColor’ and ‘scrollBorderWidth’ resources.

selectionPen

A Pen object that defines the color used to fill list selections. Its value is set by the ‘selectColor’ resources. The pen’s width is not used.

scrollWidth

An Integer that defines the width in pixels of the scroll bar. It is initialized from the value of the scrollWidth resource when the X11ListPane object is attached to its parent window by the attachTo method. The default is 10 pixels.

scrollWidth

An Integer that records whether a Shift or Ctrl key is currently being pressed. The state is used when selecting multiple items, and may be either or both of the following, or none.

shiftStateShift     (1 << 0)
shiftStateCtrl      (1 << 1)

thumbExt

thumbOrg

These are Integers that define the position and height of the scroll thumb in pixels. The value of thumbExt is calculated from the percentage of the list contents that are visible in the window at any one time. The value of thumbOrg records the vertical position of the thumb where the user moved it using the pointer.

viewStartY

An Integer that contains the distance from the top edge of the first list item (which is stored in the item’s org instance variable) to the top of the portion of the list that is visible in the pane’s window.

Instance Methods

add (String itemText)

Addes a list item using itemText as its contents. New items are added sequentially to the end of the item list. The method also calculates the item’s width and height in pixels, and the position of the top and bottom edges relative to the top edge of the zero’eth item in the list. Each item is stored in the pane’s items list using an ItemBox object, which stores each item’s dimensions as well as the item’s contents. The ItemBox class is defined in the X11ListPane class library.

attachTo (Object parentPane, String geomspect)

Attaches the X11ListPane object to parentPane, with the dimensions given by geomspect. Also initializes the object’s drawing surfaces and the actual window within the parent window.

The geomspec argument defines the width, height and position of the pane within the parent window. For a description of its contents, refer to the X11PaneDispatcher class See X11PaneDispatcher.

calcThumb (void)

Calculates the height of the scroll thumb as a proportion of the percentage of the list contents that can be displayed on the pane at any one time, and stores the value in the pane’s thumbExt instance variable (which is itself a Point object, so a program would retrieve the thumb’s height like this).

thumbHeight = myListPane thumbExt y;

draw (void)

This method draws the the pane’s scroll frame and borders, and calls the drawItemList and drawThumb methods to display the list contents.

drawItemList (void)

This method is called by the draw method to display the visible items on the pane’s window.

drawThumb (void)

Another method that is called by the draw method, this method draws the scroll thumb within the scroll bar.

new (String paneName)

The X11ListPane constructor. This method creates a X11ListPane object with the name given by paneName, and initializes the object’s resources and event handlers.

nItemsSelected (void)

Returns an Integer with the number of items that are currently selected.

onClick (Object subPane, InputEvent event)

onEnter (Object subPane, InputEvent event)

onExpose (Object subPane, InputEvent event)

onKey (Object subPane, InputEvent event)

onLeave (Object subPane, InputEvent event)

onMotion (Object subPane, InputEvent event)

onResize (Object subPane, InputEvent event)

These are the X11ListPane object’s event handlers, which receive events from the display server. They are initialized by the new method.

selectedItemN (void)

This method returns an Integer with the index of the selected item.

The indexes are numbered from zero, which is the index of the first item.

If no item is selected, this method returns ‘-1’.

selectedItems (List itemsOut)

Pushes a String object with the text of each currently selected item onto the itemsOut list.

selectedItemsN (List itemsOut)

Pushes an Integer with the numerical position of each selected item onto itemsOut. The indexes start with 0 reprsenting the first item, 1 representing the second item, and so on.

selectedItemText (void)

Returns a String with the text of the selected item. If no item is selected, the method returns and empty String.

selectFont (void)

Selects the font to display the list items, and saves the font parameters in the object’s ftFontVar instance variable, which is inherited from X11Pane class.