Resources | Resources |



List, pick, and grid widgets

This section covers three widgets used to implement either a vertical list, horizontal list, or grid.

The list widget displays multiple items as a vertical list. For example, an application that manages baseball statistics might choose to present to the user a list of player names in alphabetic order. This list could be implemented using a list widget that displays each item as static text.

The figure below shows a list widget.

The pick widget displays multiple items as a horizontal row. For example, a painting application that offers a palette of editing tools might choose to implement the presentation of these tools as a pick widget, with each item in the pick list representing a particular tool.

The grid widget also lays out its items horizontally, but wraps once it is out of horizontal space. The net result is a widget that lays out its items in a grid with the appearance of a table (though the widget does not, technically, behave as a table). The items are laid out left to right, with the wrapped item left justified under the row above. By default, the grid widget is set to contain three rows and three columns.

The grid widget is ideal for implementations that call for the user to select from a long list of similarly shaped items -- for example, a virtual art gallery application might choose to display thumbnail images of great works of art laid out in a grid, allowing the user to scroll through this list to locate an image to view at full screen size.

Each widget appears to be composed of multiple items; however, there is only a single object. The list widget is a decorator that wraps around a single object that is used to draw each item. The list, pick, and grid widgets alter the draw location and model data of the child widget. The list widget uses the services of the child widget (through the model/widget relationship of the widget framework) to draw each individual item in the list. See the following diagram, which illustrates this relationship.

Two models are associated with the list widget: the list model and the value model of the list item:

  • List widget's model

    The list widget is attached to a list model, which -- as an abstract class -- could be realized as a vector model, an array model, or any model that manages indexed collections of data. This model will contain all the data to be presented in the list. It could be a simple list of strings, or it could be a complex data structure containing strings, icons or anything else an application may need to render items in a list.

  • Item's value model

    When attached to the list widget, the item widget should already have a value model attached to it, presumably with no corresponding data. Some widgets, such as the static widget, have a value model that is created at the time the widget is created. At draw time, or certain other times such as when the preferred extent is requested, the list widget will loop through its list model and apply each data element in succession to the Item widget's value model.

Variable-sized list items

A special feature of both the list widget and pick widget is the ability to have list items that vary in size from one index to another, or change size when the item is selected. For list widgets, the height can vary, and for pick widgets the width can vary. There are two types of variable-sized lists. In the first type, every item in the list could be set to a unique size. In the second type, all items are of equal size except the currently selected item.
  • All Items of variable size

    For the first type of variable-sized list, the flag LWF_VARIABLEITEMSIZE must be set on the widget, and an indexer callback function must be installed (see IWidget_SetIndexer). In the indexer callback, the application can control the height (or width) by calling IWidget_SetVarItemSize() to set the new size of the item. This size may be based on the original size of the item, which may be retrieved by calling IWidget_GetVarItemSize().

    For example, to create a list widget which sizes the list item based on the content of the item, the indexer callback might look like this:

    static void
    ListIndexer(IWidget *piw, int nIndex, boolean bSelected)
          // calculate the size based on the content 
          int size = CalcNewHeight(piw, nIndex);
          IWidget_SetVarItemSize(piw, size); 

  • Selected item variable size

    For the second type, the size of the currently selected item can be different from all other items (as focus moves, the focused item may need to look bigger compared to other items). For such cases, the application can call IWidget_SetSelItemSize().

For additional information, refer to the

The following table shows the include files and ClassIDs for the list, pick, and grid widgets.

Required Files





Class IDs