Figure 1. An illustration of the DataBrowser being used to display a list of files.

Figure 2. An illustration of the object-oriented hierarchy used inside of the browser control.

Figure 3. How Data ID numbers are used together with Property ID numbers to address particular rows in a table.

Figure 4. Information maintained by the DataBrowser for each row displayed in a DataBrowser control.

Definition 1. Data Element ID or Data ID.
Any non-zero, 32-bit value uniquely identifying a data element being displayed in a list. Data ID values map to rows in the tables displayed by the DataBrowser. Data ID values need not be in any particular order, and the values used are entirely up to the application.

The constant kDataBrowserNoItem is a special Data ID value used by the DataBrowser to mean "none of the Data ID numbers currently stored in the browser control." Its usage is analogous to the NULL pointer in C.

Any non-zero, 32-bit unsigned integer value that uniquely identifies a column in a table being displayed by the DataBrowser. Property ID numbers do not need to be ordered or sequential, and the values used are entirely up to the application. Property ID values 0 through 1023 are reserved by Apple for use in the DataBrowser control.

The constant kDataBrowserItemNoProperty is a special Property ID value used by the DataBrowser to mean "none of the Property ID numbers (columns) currently stored in the browser control." Its usage is analogous to the NULL pointer in C.

Figure 5. Information associated with each column.

A Data ID together with a Property ID uniquely identifies a cell in a table displayed by the DataBrowser. A cell corresponds to a location inside of a Data Browser list that is at the intersection of a row and a column.

The CreateDataBrowserControl routine.

    OSStatus CreateDataBrowserControl(
        WindowRef window,
        const Rect *boundsRect,
        DataBrowserViewStyle style,
        ControlRef *outControl);

• window - the window where the control should be placed.
  
  
• boundsRect - location where the control should appear in the window.
  
  
• style - the view style that should be used when the control is drawn. Currently, the only view styles defined are kDataBrowserListView and kDataBrowserColumnView. This document's primary focus is the kDataBrowserListView type.
  
  
• outControl - if the control has been successfully created, then it will be returned in the location referenced by this parameter.

The DataBrowserListViewColumnDesc Structure

enum {
    kDataBrowserListViewLatestHeaderDesc = 0
};

typedef struct DataBrowserListViewHeaderDesc
        DataBrowserListViewHeaderDesc;

typedef struct DataBrowserListViewColumnDesc
        DataBrowserListViewColumnDesc;

typedef struct DataBrowserPropertyDesc
        DataBrowserTableViewColumnDesc;


struct DataBrowserListViewColumnDesc {
    DataBrowserTableViewColumnDesc propertyDesc;
    DataBrowserListViewHeaderDesc headerBtnDesc;
};

struct DataBrowserPropertyDesc {
    DataBrowserPropertyID propertyID;
    DataBrowserPropertyType propertyType;
    DataBrowserPropertyFlags propertyFlags;
};

struct DataBrowserListViewHeaderDesc {
    UInt32 version; /* Use kDataBrowserListViewLatestHeaderDesc */

    UInt16 minimumWidth;
    UInt16 maximumWidth;

    SInt16 titleOffset;
    CFStringRef titleString;
    DataBrowserSortOrder initialOrder;
    ControlFontStyleRec btnFontStyle;
    ControlButtonContentInfo btnContentInfo;
};

• propertyDesc. This field contains information about the property attached to the column. See the description of the DataBrowserPropertyDesc type for more information.
  
  
• headerBtnDesc. This field contains information about the appearance of the column heading. See the description of the DataBrowserListViewHeaderDesc type for more information.

The DataBrowserPropertyDesc Structure

typedef struct DataBrowserPropertyDesc
    DataBrowserTableViewColumnDesc;

struct DataBrowserPropertyDesc {
    DataBrowserPropertyID propertyID;
    DataBrowserPropertyType propertyType;
    DataBrowserPropertyFlags propertyFlags;
};

• propertyID. This field contains a 32-bit integer value that uniquely identifies this column. It is the Property ID that your application uses to identify the column. This Property ID number will also be used by the DataBrowser to identify the column in callbacks to your application. The DataBrowser interfaces use the type DataBrowserPropertyID for Property ID values.
  
  
• propertyType. This field contains a 32-bit OSType value that indicates the type of data that is to be displayed in the column. At the time of this writing, permissible values for use in this field are as follows:
  
  
  • kDataBrowserCustomType - No associated data type; custom callbacks used.
    
    
  • kDataBrowserIconType - IconRef, IconTransformType, and RGBColor.
    
    
  • kDataBrowserTextType - CFStringRef for displaying text.
    
    
  • kDataBrowserDateTimeType - DateTime or LongDateTime.
    
    
  • kDataBrowserCheckboxType - ThemeButtonValue.
    
    
  • kDataBrowserProgressBarType - Min, Max, and Value.
    
    
  • kDataBrowserRelevanceRankType - Min, Max, and Value.
    
    
  • kDataBrowserSliderType - Min, Max, and Value.
    
    
  • kDataBrowserpop-upMenuType - MenuRef displays pop-up menus.
    
    
  • kDataBrowserIconAndTextType - IconRef and CFStringRef together as icons with text.
  
  
  
• propertyFlags. This field contains a 32-bit integer value of type DataBrowserPropertyFlags containing flags controlling the display or interaction provided by this column. The following constants define mask values that can be used to set particular flags in this field. All unused bits in this field are currently reserved for future use.
  
  
  • kDataBrowserDefaultPropertyFlags - this constant contains the default property flags that should be used to initialize the propertyFlags field if no other flags are required.
    
    
  • kDataBrowserRelativeDateTime - this flag is only used if the propertyType field is set to the constant kDataBrowserDateTimeType. When this flag is specified, date values close to the current date will be displayed as relative dates.
    
    
  • kDataBrowserPropertyIsEditable - this flag may be set if the values being displayed in the column can be changed. If an application specifies this flag, then the application must also provide a callbacks that allow the DataBrowser to both retrieve and store data values displayed in this column.

Note:
The DataBrowser requires the kDataBrowserPropertyIsEditable flag to be set in order to enable editing of any changeable display type (namely checkboxes, pop-up menus, etc). Be sure your application is setting the kDataBrowserPropertyIsEditable flag when defining columns containing checkboxes, menus, and so forth.

The DataBrowserListViewHeaderDesc Structure

struct DataBrowserListViewHeaderDesc {
    UInt32 version; /* Use kDataBrowserListViewLatestHeaderDesc */

    UInt16 minimumWidth;
    UInt16 maximumWidth;

    SInt16 titleOffset;
    CFStringRef titleString;
    DataBrowserSortOrder initialOrder;
    ControlFontStyleRec  btnFontStyle;
    ControlButtonContentInfo  btnContentInfo;
};

• version. The version field identifies the format of the structure. You should always set this field to the value kDataBrowserListViewLatestHeaderDesc.
  
  
• minimumWidth. For resizable columns, this field contains the smallest width that the column can be resized to. If the column is not resizable, then minimumWidth should be set to the same value as maximumWidth.
  
  
• maximumWidth. For resizable columns, this field contains the largest width that the column can be resized to. If the column is not resizable, then maximumWidth should be set to the same value as minimumWidth.
  
  
• titleOffset. This field contains an offset in pixels from the left side of the title column where the title text will be drawn. Both the titleAlignment and the titleOffset fields dictate the alignment and offset (inset by default) of the content of the column when displaying one of the pre-defined content types.
  
  
• titleString. This field contains the text that is to be drawn as the column's titled. titleString may be NULL to indicate that no string is to be displayed.
  
  
• initialOrder. This field contains a value of type DataBrowserSortOrder. initialOrder is the initial sort ordering presentation for the column when that column is the current sort column. Once the DataBrowser is visible, the user may change this via direct manipulation. Setting this value to anything other than kDataBrowserOrderDecreasing will map to kDataBrowserOrderIncreasing. initialOrder may be assigned one of the following values:
  
  
  • kDataBrowserOrderUndefined - this value is currently not supported.
    
    
  • kDataBrowserOrderIncreasing - means this column is to be sorted in ascending order.
    
    
  • kDataBrowserOrderDecreasing - means this column is to be sorted in descending order.
    
    
• btnContentInfo. Contains a structure of type ControlButtonContentInfo. This structure describes the contents of the column heading and how it should be drawn. Only text-only and IconRef (& text) are supported.
  
  
• btnFontStyle. This field contains a structure of type ControlFontStyleRec that defines the text style used for the column heading.

The AddDataBrowserListViewColumn routine

    OSStatus AddDataBrowserListViewColumn(
        ControlRef browser,
        DataBrowserListViewColumnDesc *columnDesc,
        UInt32 position);

• browser - a DataBrowser control created by the CreateDataBrowserControl routine.
  
  
• columnDesc - a record of type DataBrowserListViewColumnDesc with all of its fields initialized to their appropriate values.
  
  
• position - refers to the position among the columns that are already installed in the DataBrowser where this column should be inserted. To insert this column to the right of all other columns, provide a very large value such as ULONG_MAX.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful. paramErr will be returned if the columnDesc record is not formatted correctly.

Listing 1. Adding a new column to a DataBrowser control.

DataBrowserListViewColumnDesc columnDesc;

columnDesc.propertyDesc.propertyID = kCheckboxColumn;
columnDesc.propertyDesc.propertyType = kDataBrowserCheckboxType;
columnDesc.propertyDesc.propertyFlags = kDataBrowserDefaultPropertyFlags;

columnDesc.headerBtnDesc.minimumWidth = 30;
columnDesc.headerBtnDesc.maximumWidth = 30;

columnDesc.headerBtnDesc.titleAlignment = teCenter;

columnDesc.headerBtnDesc.titleFontTypeID = kControlFontViewSystemFont;
columnDesc.headerBtnDesc.titleFontStyle = normal;
columnDesc.headerBtnDesc.titleOffset = 0;

columnDesc.titleString = CFStringCreateWithPascalString(
    CFAllocatorGetDefault(), "\p", kCFStringEncodingMacRoman);

AddDataBrowserListViewColumn(a_browser, &columnDesc, ULONG_MAX),

The AddDataBrowserItems routine.

    OSStatus AddDataBrowserItems(
        ControlRef browser,
        DataBrowserItemID container,
        UInt32 numItems,
        const DataBrowserItemID *items,
        DataBrowserPropertyID preSortProperty);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - if the items being installed are sub-items of another data element already installed in the browser control, then this parameter should contain the Data ID of that data element. Otherwise, if the items have no parent data element, then you can provide the constant kDataBrowserNoItem as this argument. The container parameter can be used to construct hierarchical lists for display. NOTE: adding an item to a container item will have the side effect of opening that container item.
  
  
• numItems - the number of items in the array pointed to by the items parameter.
  
  
• items - points to an array of unsigned long integers containing the Data ID numbers of items that are to be added. Note: If items is set to NULL, then the data browser will automatically generate and add the Data ID numbers 1, 2, ..., numItems to the browser control.
  
  
• preSortProperty - If the array of items have been sorted according to the sorting order currently in use in one of the columns in the list being displayed, then you can use this parameter to reference this column. This will allow the DataBrowser to skip the sorting step if the values are already in the correct order.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

IMPORTANT:
Adding items to an existing item (as the parent) means that the specified parent item must be classified as a container. This means that when the DataBrowser asks for the kDataBrowserItemIsContainerProperty of the specified parent item, the answer must be true. If your application does not provide this condition, then the AddDataBrowserItems call will fail.

Listing 2. Adding a sequence of Data IDs (rows) to a browser control.

#define kMyItemCount 22

    DataBrowserItemID newitems[kMyItemCount];
    long i;

        /* add a bunch of generated ID
        numbers to the control */
    for (i = 0; i < kMyItemCount; i++) {
            /* Make some arbitrary ID value.  The only
            requirement is that it be unique. */
        newitems[i] = ( i<<12 ) + (4095 ^ i);
    }
    AddDataBrowserItems(mybrowser, kDataBrowserNoItem,
            kMyItemCount, items, kDataBrowserItemNoProperty);


        /* instead of indexes or codes, let's use
        picture references.  Of course, we're assuming we
        have a resource file set up with picture resources
        128, 129, ... */
    for (i = 0; i < kMyItemCount; i++) {
        newitems[i] = (DataBrowserItemID) GetResource('PICT', i+128);
        if (newitems[i] == NULL) { err = resNotFound; goto bail; }
    }
    AddDataBrowserItems(some_other_browser, kDataBrowserNoItem,
            kMyItemCount, items, kDataBrowserItemNoProperty);


        /* let's just use the numbers 1, 2, ..., kMyItemCount.  We
        only have kMyItemCount items to display, so why not just
        number them from 1 to kMyItemCount.  In this case, we don't
        need to provide an array of ID numbers - the browser will
        generate them the ID numbers for us.  */
    AddDataBrowserItems(yet_another_browser, kDataBrowserNoItem,
            kMyItemCount, NULL, kDataBrowserItemNoProperty);

The RemoveDataBrowserItems routine.

    OSStatus RemoveDataBrowserItems(
        ControlRef browser,
        DataBrowserItemID container,
        UInt32 numItems,
        const DataBrowserItemID *items,
        DataBrowserPropertyID preSortProperty);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - if the items being removed are sub-items of another data element already installed in the browser control, then this parameter should contain the Data ID of that data element. Otherwise, if the items have no parent data element, then you can provide the constant kDataBrowserNoItem as this argument.
  
  
• numItems - the number of items in the array pointed to by the items parameter.
  
  
• items - points to an array of unsigned long integers containing the Data ID numbers of items that are to be removed. If this parameter is set to NULL, then all of the items will be removed. If this parameter is NULL, then all of the items in the container item referenced by the container parameter will be removed. If items is NULL, then the numItems parameter is ignored.
  
  
• preSortProperty - if the array of items has already been sorted, then set this parameter to the Property ID of the column that has the same sorting order.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The GetDataBrowserItems routine.

    OSStatus GetDataBrowserItems(
        ControlRef browser,
        DataBrowserItemID container,
        Boolean recurse,
        DataBrowserItemState state,
        Handle items);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - to obtain a list of items displayed at the top level of the control's display, provide the constant kDataBrowserNoItem. Otherwise, to obtain a list of items that are organized as sub-items of a container item, provide the container item's Data ID.
  
  
• recurse - When this parameter is true, GetDataBrowserItems will return a flattened list of all of the data IDs stored in the DataBrowser as sub-items of container parameter. The list will be created using a in-order traversal of the Data ID hierarchy maintained internally by the DataBrowser.
  
  
• state - When this field is non-zero, only items with this state will be incorporated into the result.
  
  
• items - should contain a new zero-length handle. Upon return, the contents of this handle will be set to contain an array of Data ID numbers for the items that match the criteria provided by other parameters.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

Listing 3. Obtaining a list of all of the selected items in a browser control.

    Handle selectedItems;
    OSStatus err;
    UInt32 selectionCount;
    selectedItems = NewHandle(0);
    if (selectedItems == NULL) { err = memFullErr; goto bail; }
    err = GetDataBrowserItems(browser,
        kDataBrowserNoItem,  /* start searching at the root item */
        true, /* recursively search all subitems */
        kDataBrowserItemIsSelected, /* only return selected items */
        selectedItems);
    if (err != noErr) goto bail;
    selectionCount = (GetHandleSize(selectedItems) /
                             sizeof(DataBrowserItemID));

Note:
When the recurse parameter to the GetDataBrowserItems is set to true, the routine will flatten an entire hierarchy into a single vector of Data ID numbers, but, when it does so, it does not encode any information about that hierarchy into the list of returned Data ID numbers. If your application requires the sort of functionality where it would like to save and restore a hierarchy of Data IDs as they are displayed in a DataBrowser control, then you should build that functionality yourself using combinations of the routines described in this section.

The GetDataBrowserItemCount routine.

    OSStatus GetDataBrowserItemCount(
        ControlRef browser,
        DataBrowserItemID container,
        Boolean recurse,
        DataBrowserItemState state,
        UInt32 *numItems);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - to obtain a list of items displayed at the top level of the control's display, provide the constant kDataBrowserNoItem. Otherwise, to obtain a list of items that are organized as sub-items of a container item, provide the container item's Data ID.
  
  
• recurse - When this parameter is true, GetDataBrowserItemCount will return the number of all of the data IDs stored in the DataBrowser as sub-items of container parameter.
  
  
• state - When this field is non-zero, only items with this state will be counted.
  
  
• numItems - The total number of items found is returned in the unsigned 32-bit integer referenced by this parameter.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

Listing 4. Counting the number of selected rows in a browser control.

    UInt32 selectionCount;
    OSStatus err;
    err = GetDataBrowserItemCount(myBrowserControl,
        kDataBrowserNoItem,  /* start searching at the root item */
        true, /* recursively search all subitems */
        kDataBrowserItemIsSelected, /* only return selected items */
        &selectionCount);
    if (err != noErr) goto bail;
    if (selectionCount > 0) { ...

The ForEachDataBrowserItem routine.

typedef void (*DataBrowserItemProcPtr)(
        DataBrowserItemID item,
        DataBrowserItemState state,
        SInt32 clientData);

    typedef DataBrowserItemProcPtr DataBrowserItemUPP;


    OSStatus ForEachDataBrowserItem(
        ControlRef browser,
        DataBrowserItemID container,
        Boolean recurse,
        DataBrowserItemState state,
        DataBrowserItemUPP callback,
        SInt32 clientData);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - to have your callback called for all of the items displayed at the top level of the control's display, provide the constant kDataBrowserNoItem. Otherwise, to have your callback called for all of the items that are organized as sub-items of a container item, provide the container item's Data ID.
  
  
• recurse - When this parameter is true, ForEachDataBrowserItem will call the callback routine for all of the data IDs stored in the DataBrowser as sub-items of container parameter.
  
  
• state - When this field is non-zero, only items with this state will be counted.
  
  
• callback - a UPP referencing your callback routine. The DataBrowserItemProcPtr declaration above shows how this routine should be defined in your application. This routine will be called for every Data ID currently stored in the browser control matching the criteria you provide in the other ForEachDataBrowserItem parameters.
  
  
• clientData - this is a reference value passed through to your callback routine. Its contents are defined by the application.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

Listing 5. Enumerating and acting on certain items in the selection.

static Handle gCollector = NULL;
OSStatus gCoStatus = noErr;

    /* in our item callback routine, we add any of the items
    that satisfy some interesting criteria to the list of
    data ID numbers we are accumulating in the handle
    referenced by the global variable gCollector. */
static void MyDataBrowserItemProc( DataBrowserItemID item,
     DataBrowserItemState state, SInt32 clientData) {
    if (gCoStatus == noErr && clientData == 'Yeah') {
        if ( SatisfiesSomeInterestingCriteria(item) ) {
            gCoStatus = PtrAndHand(&item, gCollector, sizeof(item));
        }
    }
}

....
    OSStatus err;
    DataBrowserItemUPP myItemProc;
    UInt32 selectionCount;

    gCoStatus = noErr;
    gCollector = NewHandle(0);
    if (gCollector == NULL) { err = memFullErr; goto bail; }

        /* set up our callback's routine descriptor */
    myItemProc = NewDataBrowserItemUPP(MyDataBrowserItemProc);
    if (myItemProc == NULL) { err = memFullErr; goto bail; }

        /* call our callback routine for every item that
        is currently a member of the selection. */
    err = ForEachDataBrowserItem(any_old_browser,
        kDataBrowserNoItem,  /* start searching at the root item */
        true, /* recursively search all subitems */
        kDataBrowserItemIsSelected, /* call it for selected items */
        myItemProc, /* a reference to our callback */
        'Yeah'); /* our arbitrary and private parameter */
    if (err != noErr) goto bail;
    if ((err = gCoStatus) != noErr) goto bail;
    selectionCount = (GetHandleSize(selectedItems) /
                             sizeof(DataBrowserItemID));

The GetDataBrowserItemState routine.

    OSStatus GetDataBrowserItemState(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserItemState *state);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the row you are interested in. NOTE: As discussed later in the Selection Handling section, the DataBrowser provides facilities for selecting and highlighting entire rows of data, but it does not provide any facilities for selecting individual cells within rows.
  
  
• state - various combinations of the following flags:
  
  
  • kDataBrowserItemNoState - has no state associated with it at this time.
    
    
  • kDataBrowserItemIsSelected - is a member of the current selection.
    
    
  • kDataBrowserContainerIsOpen - disclosure open.
    
    
  • kDataBrowserItemIsDragTarget - Only true during a drag operation.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

Note:
The sorting routine used by the DataBrowser is non destructive and it preserves the ordering of elements that are equal across sorts. This means that if the list displayed is sorted based on column 1, and then you sort using column 2 and all of the Data IDs in column 2 map to the same value, then the order of the list will not change.

The SetDataBrowserSortOrder routine.

    OSStatus SetDataBrowserSortOrder(
        ControlRef browser,
        DataBrowserSortOrder order);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• order - this parameter should be set to one of the three following constant values:
  
  
  • kDataBrowserOrderUndefined - not supported.
    
    
  • kDataBrowserOrderIncreasing - ascending order.
    
    
  • kDataBrowserOrderDecreasing - descending order.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The GetDataBrowserSortOrder routine.

    OSStatus GetDataBrowserSortOrder(
        ControlRef browser,
        DataBrowserSortOrder *order);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• order - see the description of SetDataBrowserSortOrder for the different values that can be returned in the variable pointed to by this parameter.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The SetDataBrowserSortProperty routine.

    OSStatus SetDataBrowserSortProperty(
        ControlRef browser,
        DataBrowserPropertyID property);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• property - the Property ID of the column used to sort the list.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The GetDataBrowserSortProperty routine.

    OSStatus GetDataBrowserSortProperty(
        ControlRef browser,
        DataBrowserPropertyID *property);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• property - the Property ID of the column being used to sort the list will be stored in the variable pointed to by this parameter.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The SortDataBrowserContainer routine.

    OSStatus SortDataBrowserContainer(
        ControlRef browser,
        DataBrowserItemID container,
        Boolean sortChildren);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - to sort all of the items displayed at the top level of the control's display, provide the constant kDataBrowserNoItem. Otherwise, sort all of the items that are organized as sub-items of a container item, provide the container item's Data ID.
  
  
• sortChildren - if this parameter is true, then all of the sub-items and sub-containers organized within the container will be sorted.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

struct DataBrowserCallbacks {
    UInt32 version; /* use kDataBrowserLatestCallbacks */
    union {
        struct {
            DataBrowserGetSetItemDataUPP clientDataCallback;
            DataBrowserCompareUPP compareCallback;

            DataBrowserItemNotificationUPP itemNotificationCallback;

            DataBrowserAddDragItemUPP addDragItemCallback;
            DataBrowserAcceptDragUPP acceptDragCallback;
            DataBrowserReceiveDragUPP receiveDragCallback;
            DataBrowserPostProcessDragUPP postProcessDragCallback;

            DataBrowserGetHelpContentUPP getHelpContentCallback;
            DataBrowserGetContextualMenuUPP contextualMenuCallback;
            DataBrowserSelectContextualMenuUPP selectContextMenuCallback;
        } v1;
    } u;
};

DataBrowserGetSetItemDataUPP - the Client Data Callback.

    typedef OSStatus (*DataBrowserGetSetItemDataProcPtr)(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property,
        DataBrowserItemDataRef itemData,
        Boolean setValue);

    typedef DataBrowserGetSetItemDataProcPtr
        DataBrowserGetSetItemDataUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the data row whose data is being requested in this call.
  
  
• property - the Property ID to be used in conjunction with the Data ID to locate the cell whose data is being requested in this call. This value uniquely identifies the column.
  
  
• itemData - a pointer to the data or to a data buffer prepared to receive the data.
  
  
• setValue - if setValue is true, then your callback should replace its current copy of the value associated with (item, property) with the value pointed to by itemData. If setValue to false, then your application should store a copy of the value associated with (item, property) to the buffer pointed to by itemData.

Returns an operating system result code describing the success of the operation. Your callback should return the result code noErr if the operation was successful.

Listing 6. Example data callback routine.

    /* MySimpleDataCallback is a simple data callback routine
    that would be used in a browser control displaying a list
    of generic document icons together with a list of checkboxes.
    The checkbox column is a mutable column. */
OSStatus MySimpleDataCallback(
    ControlRef browser,
    DataBrowserItemID itemID,
    DataBrowserPropertyID property,
    DataBrowserItemDataRef itemData,
    Boolean changeValue) {

    IconRef myIcon;
    OSStatus err;

        /* start with a known state */
    myIcon = NULL;

        /* look at the property ID and decide what to do
        depending on what column we're dealing with... */
    if (property == kMyCheckboxColumn) {
        ThemeButtonValue buttonValue;

            /* are we being asked to change the value
            we have in our own store or are we being
            asked to retried the value?  You'll only
            have ask this question for mutable columns. */
        if (changeValue) {

            err = GetDataBrowserItemDataButtonValue(itemData,
                                 &buttonValue);
            if (err != noErr) goto bail;

                /* NOTE: our internal storage lookup mechanism must
                map itemID numbers to the values stored for each
                button in the list. */
            err = StoreTheValueSomewhere(itemID, buttonValue);
            if (err != noErr) goto bail;

        } else {

            err = GetTheButtonValueFromSomewhere(itemID, &buttonValue);
            if (err != noErr) goto bail;

            err = SetDataBrowserItemDataButtonValue(itemData,
                    buttonValue);
            if (err != noErr) goto bail;
        }

    } else if (property == kMyIconOnlyColumn) {

            /* if the column is not mutable, then we
            can safely assume we are only being asked
            to retrieve the value. */
        err = GetIconRef(kOnSystemDisk, kSystemIconsCreator,
            kGenericDocumentIcon, &myIcon);
        if (err != noErr) goto bail;

        err = SetDataBrowserItemDataIcon(itemData, myIcon);
        if (err != noErr) goto bail;

        ReleaseIconRef(myIcon);
        myIcon = NULL;

    } else {
        err = errDataBrowserPropertyNotSupported
        goto bail;
    }

    return noErr;

bail:
    if (myIcon != NULL) ReleaseIconRef(myIcon);
    return err;
}

    typedef Boolean (*DataBrowserCompareProcPtr)(
        ControlRef browser,
        DataBrowserItemID itemOne,
        DataBrowserItemID itemTwo,
        DataBrowserPropertyID sortProperty);

    typedef DataBrowserCompareProcPtr DataBrowserCompareUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemOne - the Data ID of the first row to be used in the comparison.
  
  
• itemTwo - the Data ID of the second row to be used in the comparison.
  
  
• sortProperty - the Property ID number for the column being sorted.

Your application's callback should return true if the value of the data referenced by itemOne is less than the value of the data referenced by itemTwo, and it should return should return false if the value of the data referenced by itemOne is greater than or equal to the value of the data referenced by itemTwo. The comparison should only consider the values being displayed in the column referenced by the Property ID in sortProperty. Sorting is stable, so you can use secondary and tertiary sorting. Each time a user clicks a column, the column will be sorted, but the sort order of matching items will be preserved.

    typedef void (*DataBrowserItemNotificationProcPtr)(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserItemNotification message);

    typedef DataBrowserItemNotificationProcPtr
        DataBrowserItemNotificationUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the row being identified by this call.
  
  
• message Possible values for this parameter are described in Table 1.

Table 1. Notifications provided by the browser control.

Constant Name

Description

kDataBrowserItemAdded

The specified item has been added to the browser.

kDataBrowserItemRemoved

The specified item has been removed from the browser.

kDataBrowserEditStarted

Starting an EditText session for specified item.

kDataBrowserEditStopped

Stopping an EditText session for specified item.

kDataBrowserItemSelected

Item has just been added to the selection set.

kDataBrowserItemDeselected

Item has just been removed from the selection set.

kDataBrowserItemDoubleClicked

The user double clicked on an item.

kDataBrowserContainerOpened

Container has been opened.

kDataBrowserContainerClosing

Container is about to close.

kDataBrowserContainerClosed

Container has been closed.

kDataBrowserContainerSorting

Container is about to be sorted (lock any volatile properties).

kDataBrowserContainerSorted

Container has been sorted (you may release any property locks).

kDataBrowserTargetChanged

The target has changed to the specified item.

kDataBrowserUserStateChanged

The user has reformatted the view for the target.

kDataBrowserSelectionSetChanged

The selection set has been modified (net result may be the same).

    typedef Boolean (*DataBrowserAddDragItemProcPtr)(
        ControlRef browser,
        DragReference theDrag,
        DataBrowserItemID item,
        ItemReference *itemRef);

    typedef DataBrowserAddDragItemProcPtr DataBrowserAddDragItemUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• theDrag - the drag reference being constructed by the DataBrowser.
  
  
• item - this is the item ID of the item your application should add to the drag.
  
  
• itemRef - this parameter is currently unused. You should set this parameter to point to an ItemReference variable before calling this routine.

If your callback returns true, then the item will be added to the transparent drag image. If it returns false, it will not.

    typedef Boolean (*DataBrowserAcceptDragProcPtr)(
        ControlRef browser,
        DragReference theDrag,
        DataBrowserItemID item);

    typedef DataBrowserAcceptDragProcPtr DataBrowserAcceptDragUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• theDrag - a Drag Manager reference.
  
  
• item - This is the item ID of the item the drag is being held over. If the drag is being held over the list but not over any item, then item will contain the default target item ID for the list. The default target item ID for the list is discussed in the section Setting the Root Container.

Your callback should return true if it is capable of accepting the drag in the location designated by the item parameter.

    Boolean (*DataBrowserReceiveDragProcPtr) (
        ControlRef browser,
        DragReference theDrag,
        DataBrowserItemID item);

    typedef DataBrowserReceiveDragProcPtr
        DataBrowserReceiveDragUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• theDrag - a Drag Manager reference.
  
  
• item - This is the item ID of the item the drag is being held over. If the drag is being held over the list but not over any item, then item will contain the default target item ID for the list. The default target item ID for the list is discussed in the section Setting the Root Container.

Your callback should return true if is successfully completes processing all of the information in the drag. Otherwise, it should return false. If your callback returns false, the zoom-back animation will occur for the drag.

    typedef void (*DataBrowserPostProcessDragProcPtr)(
        ControlRef browser,
        DragReference theDrag,
        OSStatus trackDragResult);

    typedef DataBrowserPostProcessDragProcPtr
        DataBrowserPostProcessDragUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• theDrag - a Drag Manager drag reference.
  
  
• trackDragResult - the result returned by TrackDrag

Returns an operating system result code describing the success of the operation. Your callback should return the result code noErr if the operation was successful.

    typedef void (*DataBrowserGetHelpContentProcPtr)(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property,
        HMContentRequest inRequest,
        HMContentProvidedType *outContentProvided,
        HMHelpContentPtr ioHelpContent);

    typedef DataBrowserGetHelpContentProcPtr
        DataBrowserGetHelpContentUPP;

• browser - a Data Browser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID indentifying the row.
  
  
• property - the Property ID identifying the column.
  
  
• inRequest - either kHMSupplyContent or kHMDisposeContent.
  
  
• outContentProvided - should be set to the content type provided in the record pointed to by ioHelpContent.
  
  
• ioHelpContent - a help content record containing the help information to be displayed.
  
  

Returns an operating system result code describing the success of the operation. Your callback should return the result code noErr if the operation was successful.

    typedef void (*DataBrowserGetContextualMenuProcPtr)(
        ControlRef browser,
        MenuRef *menu,
        UInt32 *helpType,
        CFStringRef *helpItemString,
        AEDesc *selection);

    typedef DataBrowserGetContextualMenuProcPtr
        DataBrowserGetContextualMenuUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• menu - Your callback should provide a MenuRef in this parameter.
  
  
• helpType - set this variable to one of the values kCMHelpItemNoHelp, kCMHelpItemAppleGuide, or kCMHelpItemOtherHelp. This value will be passed to ContextualMenuSelect.
  
  
• helpItemString - The very first item that appears in the contextual menu. If you set this value to Null, then the default "Help" string will be displayed.
  
  
• selection - this will point to an empty AEDesc and your callback should set this to your own internal representation of the selection. This will be passed to ContextualMenuSelect.

Returns an operating system result code describing the success of the operation. Your callback should return the result code noErr if the operation was successful.

    typedef void (*DataBrowserSelectContextualMenuProcPtr)(
        ControlRef browser,
        MenuRef menu,
        UInt32 selectionType,
        SInt16 menuID,
        MenuItemIndex menuItem);

    typedef DataBrowserSelectContextualMenuProcPtr
        DataBrowserSelectContextualMenuUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• menu - the menu reference your application provided in its contextualMenuCallback.
  
  
• selectionType - returned from ContextualMenuSelect.
  
  
• menuID - the menu ID of the menu selected. This field will be zero if no selection was made.
  
  
• menuItem - the menu item number of the item selected.

The InitDataBrowserCallbacks routine.

    OSStatus InitDataBrowserCallbacks(
        DataBrowserCallbacks* callbacks);

• callbacks - a pointer to a DataBrowserCallbacks structure. The version field of the DataBrowserCallbacks structure must be set to the value kDataBrowserLatestCallbacks before this routine is called.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The SetDataBrowserCallbacks routine.

    OSStatus SetDataBrowserCallbacks(
        ControlRef control,
        const DataBrowserCallbacks *callbacks);

• control - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• callbacks - a pointer to a DataBrowserCallbacks structure.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful.

The GetDataBrowserCallbacks routine.

    OSStatus GetDataBrowserCallbacks(
        ControlRef control,
        DataBrowserCallbacks *callbacks);

• control - a DataBrowser contro