home *** CD-ROM | disk | FTP | other *** search
Text File | 1993-06-18 | 9.8 KB | 203 lines | [ TEXT/MPS ]
***** ListControl.c usage documentation *****/ Purpose: To simplify List handling within a window. Implementing a List control does the following: 1) Makes using lists in a non-dialog window easier. 2) The List is automatically associated with the window, since it is in the window's control list. 4) Updating of the List is much simpler, since all that is necessary is to draw the control (or all the window's controls with a DrawControls call). 5) What isn't handled automatically by tracking the control can be handled with a direct call. There are simple calls to handle List events. 6) When you close the window, the ListRecord is disposed of. (This automatic disposal can easily be defeated.) To create a List control, you only need a single call. For example: list = CLNew(rViewCtl, /* Resource ID of view control for List control. */ true, /* Initially visible. */ &viewRect, /* View rect of list. */ numRows, /* Number of rows to create List with. */ numCols, /* Number of columns to create List with. */ cellHeight, cellWidth, theLProc, /* Custom List procedure resource ID. */ window, /* Window to hold List control. */ clHScroll | blBrdr | clActive); /* Horizontal scrollbar, active List. */ The various choices for the List control are defined as follows: #define clHScroll 0x0002 #define clVScroll 0x0008 #define clActive 0x0020 #define clShowActive 0x0040 #define clKeyPos 0x0080 #define clTwoStep 0x0100 #define clHasGrow 0x0200 #define clDrawIt 0x8000 clHScroll: Create a list that includes a horizontal scrollbar. clVScroll: Create a list that includes a vertical scrollbar. clActive: Make this the initially active control for the window. clShowActive: When the control is active, show that it is by drawing a selection border around the control. This is the new 7.0 human-interface method of showing which control is active. clKeyPos: Allow list positioning, based on user keypresses. This assumes that the list is alphabetized so that key presses for location make sense. If typing by the user is fast enough, multiple characters will be used for the positioning. clTwoStep: When using IsCtlEvent(), you may want the initial click on a List control to just select the control, or you may wish the click to start tracking in addition to selecting the control. The tracking is considered the second step. By setting this bit, you indicate that you want control selection and item selection to be a 2-step process. Setting this bit means that it will take 2 separate clicks by the user to select an item in the list if the list is inactive. clHasGrow: This makes sure that there is space for the growIcon if the list has a scrollbar. If the list occupies an entire window, then if there is only one scrollbar, the scrollbar has to be shrunk to make room for the growIcon. The List Manager supposedly has this ability, but it doesn't work. The List control manages it correctly. clDrawIt: This is a List manager flag that is needed for the LNew() call. If the CLNew call succeeds, you then have a List control in your window. It will be automatically disposed of when you close the window. If you don't want this to happen, then you can detach it from the view control which owns it. To do this, you would to the following: viewCtl = CLViewFromList(theListHndl); if (viewCtl) SetCRefCon(viewCtl, nil); The view control keeps a reference to the List record in the refCon. If the refCon is cleared, then the view control does nothing. So, all that is needed to detach a List record from a view control is to set the view control's refCon nil. Now if you close the window, you will still have the List record. To remove a List control completely from a window, just dispose of the view control that holds the List record. To do this, just do something like the below: DisposeControl(CLViewFromList(theListHndl)); This completely disposes of the List control. Events for the List record are handled nearly automatically. Just make the following call: CLEvent(window, eventPtr, &action); If the event was handled, true is returned. If the event is false, then the event doesn't belong to a List control, and further processing of the event should be done. Here is a list of the functions and a description as to their purpose: void CLActivate(Boolean active, ListHandle listHndl); /* Activate this List record. Activation is not done by calling LActivate(). ** The active control is indicated by the 2-pixel thick border around the ** List control. This allows all List controls in a window to display which ** cells are selected. This behavior can be overridden by calling LActivate() ** on the List record for List controls. ** Human interface dictates that only at most a single List control has this ** active border. For this reason, this function scans for other List ** controls in the window and removes the border from any other that it finds. */ Boolean CLClick(WindowPtr window, EventRecord *event, short *action); /* This is called when a mouseDown occurs in the content of a window. It ** returns true if the mouseDown caused a List action to occur. Events ** that are handled include if the user clicks on a scrollbar that is ** associated with a List control. */ ControlHandle CLCtlHit(void); /* The List control that was hit by calling FindControl is saved in a ** global variable, since the CDEF has no way of returning what kind it was. ** To determine that it was a List control that was hit, first call this ** function. The first call returns the old value in the global variable, ** plus it resets the global to nil. Then call FindControl(), and then ** call this function again. If it returns nil, then a List control ** wasn't hit. If it returns non-nil, then it was a List control that ** was hit, and specifically the one returned. */ Boolean CLEvent(WindowPtr window, EventRecord *event, short *action); /* Handle the event if it applies to the active List control. If some ** action occured due to the event, return true. */ ListHandle CLFindActive(WindowPtr window); /* Returns the active List control, if any. If nil is passed in, then ** the return value represents whatever List control is active, independent ** of what window it is in. If a window is passed in, then it returns a ** List control only if the active control is in the specified window. ** If the active List control is in some other window, then nil is returned. */ Boolean CLFindCtl(WindowPtr window, EventRecord *event, ListHandle *listHndl, ControlHandle *ctlHit); /* This determines if a List control was clicked on directly. This does ** not determine if a related scrollbar was clicked on. If a List ** control was clicked on, then true is returned, as well as the List ** handle and the handle to the view control. */ ListHandle CLFromScroll(ControlHandle scrollCtl, ControlHandle *retCtl); /* Find the List record that is related to the indicated scrollbar. */ short CLInsert(ListHandle listHndl, char *data, short dataLen, short row, short col); /* Insert a cell alphabetically into the list. Whichever parameter is passed in ** as -1, either row or column, that is the dimension that is determined. */ Boolean CLKey(WindowPtr window, EventRecord *event); /* See if the keypress event applies to the List control, and if it does, ** handle it and return true. */ ListHandle CLNew(short viewID, Boolean vis, Rect *vRect, short numRows, short numCols, short cellHeight, short cellWidth, short theLProc, WindowPtr window, short mode); /* Create a new List control. See the comments at the beginning of this ** file for more information. */ ControlHandle CLNext(WindowPtr window, ListHandle *listHndl, ControlHandle ctl, short dir, Boolean justActive); /* Get the next List control in the window. You pass it a control handle ** for the view control, or nil to start at the beginning of the window. ** It returns both a List handle and the view control handle for that ** List record. If none is found, nil is returned. This allows you to ** repeatedly call this function and walk through all the List controls ** in a window. */ void CLPrint(RgnHandle clipRgn, ListHandle listHndl, short *row, short *col, short leftEdge, Rect *drawRct); /* From the starting for or column, print as many cells as will fit into the ** designated rect. Pass in a starting row and column, and they will be ** adjusted to indicate the first cell that didn't fit into the rect. If all ** remaining cells were printed, the row is returned as -1. The bottom of the ** rect to print in is also adjusted to indicate where the actual cut-off ** point was. */ short CLRowOrColSearch(ListHandle listHndl, char *data, short dataLen, short row, short col); /* Find the location in the list where the data would belong if inserted. The row ** and column are passed in. If either is -1, that is the dimension that will be ** determined and returned. */ void CLUpdate(RgnHandle clipRgn, ListHandle list); /* Draw the List control in the correct form. */ ControlHandle CLViewFromList(ListHandle listHndl); /* Return the control handle for the view control that owns the List ** record. Use this to find the view to do customizations such as changing ** the update procedure for this List control. */ void CLWindActivate(WindowPtr window); /* This window is becoming active or inactive. The borders of the List ** controls need to be redrawn due to this. For each List control in the ** window, redraw the active border. */ void CLSize(ListHandle list, short newH, short newV); /* This resizes the list and it's viewCtl. */ void CLMove(ListHandle list, short newH, short newV); /* This moves the list and it's viewCtl. */ 
