Next: , Previous: , Up: Classes   [Index]

X11ListBox

X11ListBox Class

A X11ListBox object pops up a dialog window that contains a label, a listbox, and “Cancel” and “Ok” buttons.

After the listbox has first appeared and all of its subpanes have been initialized, a program can access any of the items selected in the listbox’s list via the listPane instance variable.

A X11ListBox dialog supports multiple selections. Pressing Shift while clicking on a list item adds that item to list’s selections. Pressing Ctrl while clicking on an item selects all of the items in a range between the first selected item and the last selected item of the list.

Component Widgets

A X11ListBox consists of component widgets from the X11LabelPane, X11ListPane, and X11ButtonPane class.

The objects for each component are declared as instance variables, which, except for the list subpane itself, are inherited from the X11YesNoBoxPane superclass. See X11YesNoBoxPane. 


Component Instance       Class                 Inherited 
     Variable                                    From 
------------------       -----               --------------
listPane                 X11ListPane         --
lButton                  X11ButtonPane       X11YesNoBoxPane
rButton                  X11ButtonPane       X11YesNoBoxPane
label                    X11LabelPane        X11YesNoBoxPane

More information about the resources, instance variables, and methods that each component uses is contained in each of the component classes’ individual sections: See X11ListPane, See X11ButtonPane, and See X11LabelPane

Here is an example program that shows how to display a X11ListBox and retrieve the selected list items. 


/* listbox.ca, a X11ListBox demonstration. -*-c-*- */

#include <ctalk/ctalkdefs.h>

#define N_ITEMS 30

int main (void) {
  X11Pane new mainWindow;
  X11PaneDispatcher new dispatcher;
  X11ButtonPane new button;
  X11LabelPane new label;
  X11ListBox new listBox;
  InputEvent new e;
  Integer new i;
  List new itemTextOut, itemNOut;
  String new itemText, itemN;

  label textColor = "white";
  label canFocus = false;
  label borderWidth = 0;

  label ftFontVar initFontLib;
  label ftFontVar notifyLevel XFT_NOTIFY_NONE;

  mainWindow backgroundColor = "blue";
  label resources replaceAt "backgroundColor", "blue";
  button resources replaceAt "backgroundColor", "blue";
  listBox resources replaceAt "backgroundColor", "blue";
  
  mainWindow initialize 255, 200;
  mainWindow inputStream eventMask = 
    EXPOSE|ENTERWINDOWNOTIFY|LEAVEWINDOWNOTIFY|BUTTONPRESS|BUTTONRELEASE|KEYPRESS|KEYRELEASE|WINDELETE|MOVENOTIFY|MOTIONNOTIFY;

  dispatcher attachTo mainWindow;
  label attachTo dispatcher, "177x80+c+15";
  button attachTo dispatcher, "110x85+c+100";
  listBox attachTo dispatcher, "300x400";

  mainWindow map;
  mainWindow raiseWindow;

  mainWindow openEventStream;

  mainWindow setWMTitle "X11ListBox Demo";

  label multiLine "X11ListBox\nDemo";
  label resources replaceAt "textColor", "lightgray";
  label resources replaceAt "foregroundColor", "blue";
  label resources replaceAt "borderColor", "blue";

  button label multiLine "Open\nListBox\nDialog";

  button label resources replaceAt "highlightForegroundColor", "gray80";

  /* The program uses the "replaceAt" method because the key/value
     entry for "backgroundColor" the X11MessageBoxPane : new method
     has alread created an entry for backgroundColor. */
  listBox resources replaceAt "backgroundColor", "blue";
  listBox resources replaceAt "foregroundColor", "blue";
  listBox resources replaceAt "messageColor", "white";
  listBox resources replaceAt "messageText",
    	       "Hello, listBox!\nPlease select an item.";

  for (i = 1; i < N_ITEMS; ++i) {
    listBox items push "item " + i asString;
  }
  
  button draw;
  button refresh;
  label draw;
  label refresh;

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

      mainWindow subPaneNotify e;

      switch (e eventClass value)
	{
	case EXPOSE:
	  button subPaneExpose (button, e);
	  label subPaneExpose (label, e);
	  break;
	case BUTTONRELEASE:
	  listBox showManaged button;
	  if (listBox listPane nItemsSelected > 1) {
	    i = 0;
	    listBox listPane selectedItems itemTextOut;
	    listBox 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",
		    listBox listPane selectedItemN,
		    listBox listPane selectedItemText);
	  }
	  break;
	case WINDELETE:
 	  mainWindow deleteAndClose;
	  exit (0);
	  break;
	}
    } else {
      usleep (1000);
    }
  }

}

Retrieving List Selections

There are several methods that provide information about which item or list items are currently selected. Generally, if a user has selected more than one item, then the results would be in the form of a list, instead of an Integer index of a selection or a String containing the selection’s contents.

The method, nItemsSelected, returns an Integer with the number of items that are currently selected. Programs can use this to determine which method to use to retrieve the list selections.

Depending on whether a user has selected a single item or multiple items, a program can use the selectedItemN or selectedItemsN methods to retrieve selection indexes, and the selectedItemText or selectedItems methods to retrieve the text of the selected item or items.

The example program above uses this method to print either a single selected item or multiple selections. 


if (listBox listPane nItemsSelected > 1) {
  i = 0;
  listBox listPane selectedItems itemTextOut;
  listBox 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",
          listBox listPane selectedItemN,
          listBox listPane selectedItemText);
}

Resources

listFont

A String that contains the name of the font that the X11ListPane subwidget uses to display the list items. The default is ‘sans-serif-12’.

Instance Variables

items

A List that contains all of the items to be added to the list when the dialog is first popped up. Because the dialog box doesn’t construct itself and the list subpane until it first appears, this is a convenient way for programs to define the items that will initially appear in the list before the the dialog first appears.

After the dialog first appears, the list items may be modified by using the list pane’s add method. For example: 


myListDialog listPane add "Extra List Item 1";
listPane

A X11ListPane object that defines the list subpane. It is initialized when the dialog is first popped up. After that, programs can use any of the methods, resources, and instance variables that are defined in X11ListPane class to alter or retrieve the list’s items or the user’s selections See X11ListPane.

Instance Methods

draw (void)

This calls the indivdual subpane’s draw and refresh methods in order to update the dialog’s contents on the display.

initWidgets (void)

Called when the dialog first appears, this initializes each of the component widget objects.

new (String paneName

The X11ListBox constructor. Creates the dialog object with the name given as the argument, and initializes the dialog’s event handlers and resources.

show (String paneName

Displays the dialog window, also calling initWidgets if the dialog is being displayed for the first time.

subPaneEnter (Object subPane, InputEvent event)
subPaneLeave (Object subPane, InputEvent event)

Event handlers for highlighting the dialog’s label or buttons when the pointer is over them.

Next: , Previous: , Up: Classes   [Index]