Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / Using the List Manager

Responding to Events Affecting a List

Your application must respond to several different types of events involving a list by calling appropriate List Manager routines. If a mouse-down event occurs in a list, your application should call the LClick function. If your application receives an update event, and some part of the list is within the update region, then it should call the LUpdate procedure. If a window containing a list is activated or deactivated, your application should activate or deactivate the list by calling the LActivate procedure. Finally, if a key-down event occurs, your application may need to call its own internal procedures to scroll the list or select items as necessary. This section explains how to handle mouse-down, update, and activate events; for information on handling key-down events, see "Supporting Keyboard Navigation of Lists" on page 4-36.

The LClick function automatically responds to a mouse-down event by handling user interaction until the user releases the mouse button. The List Manager performs any scrolling as necessary and changes the selection as appropriate. After handling the event, the LClick function returns TRUE if the click was a double click. Listing 4-5 shows an application-defined procedure that uses the LClick function to handle mouse-down events in a list.

Listing 4-5 Responding to a mouse-down event in a list

PROCEDURE MyHandleMouseDownInList (theEvent: EventRecord; 
                                  theList: ListHandle);
BEGIN
   SetPort(theList^^.port);
   GlobalToLocal(theEvent.where);
   IF LClick(theEvent.where, theEvent.modifiers, theList) THEN
      MyDoubleClick(theList);
END;

In response to a double click, your application should simulate the selection of the default button if there is one. If your dialog box does not contain a default button, then your application can respond to a double click with some other appropriate behavior.

Listing 4-6 illustrates an application-defined procedure that responds to an update event affecting a list.

Listing 4-6 Responding to an update event in a list

PROCEDURE MyUpdateList (theList: ListHandle); 
BEGIN
   SetPort(theList^^.port);      {set up the drawing environment}
                                 {update list and scroll bars}
   LUpdate(theList^^.port^.visRgn, theList); 
   MyDrawListBorder(theList);    {draw border around list}
END;

Your list update procedure might also do some other drawing appropriate to a
particular list. For example, if your application supports multiple lists in a window, then your list-updating procedure should redraw an outline around the current list in response to an update event. For more information on outlining the current list, see "Outlining the Current List" on page 4-44.

Note that the call to the LUpdate procedure must be bracketed by calls to the
Window Manager's BeginUpdate and EndUpdate procedures. See the
chapter "Window Manager" in Inside Macintosh: Macintosh Toolbox Essentials for more information.

In response to an activate event, your application should call LActivate for each list in the window. For example, this code deactivates a list:

LActivate (FALSE, myList);

To activate a list, pass TRUE as the first parameter to LActivate.