Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager

This chapter describes how your application can use the List Manager to create scrollable lists that allow the user to select one or more of a group of items. The List Manager lets you create one-column lists or multicolumn lists. By default, it creates lists that contain only unstyled text, but with extra effort, you can use the List Manager to create lists that display items graphically.

Read the information in this chapter if you need to allow users to select one or more items from a group of items. If you only need to allow the user to select one item from a small group of items, a pop-up menu may be more appropriate than a list. If, however, you would like the user to be able to select one of many items or to be able to select multiple items, the List Manager provides a convenient and intuitive interface.

If the contents of a group of items might change, use a list rather than a pop-up menu. Users generally expect the contents of pop-up menus to remain the same, whereas a list provides instant visual feedback when its contents change, thus preventing user confusion. For example, you might use the List Manager to create a list of appointments and allow the user to add or remove appointments to or from the list.

Although the List Manager can handle small, simple lists effectively, it is not suitable for displaying large amounts of data (such as that used by a spreadsheet application). The List Manager cannot maintain lists that occupy more than 32 KB of memory, and performance degrades sharply well before the 32 KB limit. Also, the List Manager expects all cells to be equal in size. Thus, if you are writing a spreadsheet application, you should use the Control Manager and your own internal data structures. However, you should still read the sections of this chapter that concern selection of list items so that your application can have a user interface consistent with the List Manager's.

To use this chapter, you should be familiar with the concepts of the Control Manager, the Event Manager, and the Window Manager, and, if you plan to create a list in a modal or modeless dialog box, with the Dialog Manager. For more information on these topics, see Inside Macintosh: Macintosh Toolbox Essentials.

This chapter begins by describing lists and the user interface for them. The chapter then discusses how you can

• create lists
• respond to events affecting lists
• get information about a list
• get or change the contents of list items
• search through a list for a particular item
• support keyboard navigation of lists
• manage multiple lists within the same window or dialog box
• write your own list definition procedure to handle nonstandard lists, such as lists of pictures

---

Chapter Contents

Introduction to Lists

Appearance of Lists

Selection of List Items

Keyboard Navigation of Lists

Movement of a Selection With Arrow Keys

Extension of a Selection With Arrow Keys

Type Selection in a Text-Only List

Multiple Lists in a Window

About the List Manager

Using the List Manager

Creating a List

Adding Rows and Columns to a List

Responding to Events Affecting a List

Working With List Selections

Customizing Cell Highlighting

Manipulating List Cells

Searching a List for a Particular Item

Supporting Keyboard Navigation of Lists

Supporting Type Selection of List Items

Supporting Arrow-Key Navigation of Lists

Supporting the Anchor Algorithm for Extending Lists With Arrow Keys

Outlining the Current List

Writing Your Own List Definition Procedure

Responding to the Initialization Message

Responding to the Draw Message

Responding to the Highlighting Message

Responding to the Close Message

Using the Pictures List Definition Procedure

List Manager Reference

Data Structures

The Cell Record

The Data Handle

The List Record

List Manager Routines

Creating and Disposing of Lists

Adding and Deleting Columns and Rows To and From a List

Determining or Changing the Selection

Accessing and Manipulating Cell Data

Responding to Events Affecting Lists

Modifying a List's Appearance

Searching a List for a Particular Item

Changing the Size of Cells and Lists

Getting Information About Cells

Application-Defined Routines

List Definition Procedures

Match Functions

Click-Loop Procedures

Summary of the List Manager

Pascal Summary

Constants

Data Types

List Manager Routines

Application-Defined Routines

C Summary

Constants

Data Types

List Manager Routines

Application-Defined Routines

Assembly-Language Summary

Data Structures

Trap Macros