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 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.

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 SetDataBrowserItemDataIcon routine

    OSStatus SetDataBrowserItemDataIcon (
        DataBrowserItemDataRef itemData,
        IconRef theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - the icon reference for the icon that is to be displayed.

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

The SetDataBrowserItemDataIconTransform routine

    OSStatus SetDataBrowserItemDataIconTransform (
        DataBrowserItemDataRef itemData,
        IconTransformType theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - the icon reference for the icon that is to be displayed.

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

The SetDataBrowserItemDataRGBColor routine

    OSStatus SetDataBrowserItemDataRGBColor (
        DataBrowserItemDataRef itemData,
        RGBColor *theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - an RGB color record.

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

The SetDataBrowserItemDataText routine

    OSStatus SetDataBrowserItemDataText (
        DataBrowserItemDataRef itemData,
        CFStringRef theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a Core Foundation string reference.

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

The GetDataBrowserItemDataText routine

    OSStatus GetDataBrowserItemDataText (
        DataBrowserItemDataRef itemData,
        CFStringRef *theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a pointer to a location where a Core Foundation string reference will be returned. On completion, this parameter will contain a newly created CFStringRef. Your application must release this string reference once it is no longer needed.

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

The SetDataBrowserItemDataDateTime routine

    OSStatus SetDataBrowserItemDataDateTime (
        DataBrowserItemDataRef itemData,
        long theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a 32-bit value representing the number of elapsed seconds elapsed since midnight
  January 1, 1904.

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

The SetDataBrowserItemDataLongDateTime routine

    OSStatus SetDataBrowserItemDataLongDateTime (
        DataBrowserItemDataRef itemData,
        const LongDateTime *theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a pointer to a 64-bit integer representing the number of seconds that have elapsed since midnight January 1, 1904.

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

The SetDataBrowserItemDataButtonValue routine

    OSStatus SetDataBrowserItemDataButtonValue (
        DataBrowserItemDataRef itemData,
        ThemeButtonValue theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a value representing the setting to display for the control.

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

The GetDataBrowserItemDataButtonValue routine

    OSStatus GetDataBrowserItemDataButtonValue (
        DataBrowserItemDataRef itemData,
        ThemeButtonValue *theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a value representing the setting to display for the control.

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

The SetDataBrowserItemDataValue routine

    OSStatus SetDataBrowserItemDataValue (
        DataBrowserItemDataRef itemData,
        SInt32 theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a value representing the setting to display.

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

The SetDataBrowserItemDataMinimum routine

    OSStatus SetDataBrowserItemDataMinimum (
        DataBrowserItemDataRef itemData,
        SInt32 theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a value representing the minimum setting.

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

The SetDataBrowserItemDataMaximum routine

    OSStatus SetDataBrowserItemDataMaximum (
        DataBrowserItemDataRef itemData,
        SInt32 theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a value representing the maximum setting.

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

The SetDataBrowserItemDataMenuRef routine

    OSStatus SetDataBrowserItemDataMenuRef (
        DataBrowserItemDataRef itemData,
        MenuRef theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a menu reference designating the menu to display in the cell.

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

The GetDataBrowserItemDataValue routine

    OSStatus GetDataBrowserItemDataValue (
        DataBrowserItemDataRef itemData,
        SInt32 *theData );

• itemData - the itemData reference number that was passed to your Data Callback Routine.
  
  
• theData - a pointer to a 32-bit integer where the value should be stored.

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

IMPORTANT
Information presented in this section refers to the current state of these APIs. These APIs are currently under review and are subject to change without notice. If you are using these APIs and you have special requirements that they currently do not provide, then please feel free to contact us and let us know about your needs so we may give them consideration when we are looking at these APIs.

The DataBrowserCustomCallbacks Structure

struct DataBrowserCustomCallbacks {

    UInt32 version; /* use kDataBrowserLatestCustomCallbacks */

    union {
        struct {
            DataBrowserDrawItemUPP CustomDrawItemCallback;
            DataBrowserEditItemUPP CustomEditTextCallback;
            DataBrowserHitTestUPP CustomHitTestCallback;
            DataBrowserTrackingUPP CustomTrackingCallback;

            DataBrowserItemDragRgnUPP CustomDragRegionCallback;
            DataBrowserItemAcceptDragUPP CustomAcceptDragCallback;
            DataBrowserItemReceiveDragUPP CustomReceiveDragCallback;
        } v1;
    } u;
};


/* Macro for initializing custom callback structure */
#define InitializeDataBrowserCustomCallbacks(callbacks, version) \
{ callbacks->version = version; \
  InitDataBrowserCustomCallbacks(callbacks); }
and macro for setting version in the callbacks structure.

    typedef void (*CustomDrawItemCallbackPtr)(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property,
        DataBrowserItemState itemState,
        const Rect *theRect,
        SInt16 gdDepth,
        Boolean colorDevice);

        typedef CustomDrawItemCallbackPtr DataBrowserDrawItemUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID number for the item to be drawn.
  
  
• property - the Property ID number for the item to be drawn.
  
  
• itemState - the current state of the item being drawn. Possible values for this parameter are listed in the description of the GetDataBrowserItemState routine. Your application should draw the cell in whatever way is appropriate for the state reflected by the value of this parameter.
  
  
• theRect - the bounding rectangle in local window coordinates where the cell should be drawn.
  
  
• gdDepth - the bit depth of the current QuickDraw GrafPort.
  
  
• colorDevice - true if the current QuickDraw port is a color device.

    typedef Boolean (*CustomEditTextCallbackPtr)(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property,
        CFStringRef theString,
        Rect *maxEditTextRect,
        Boolean *shrinkToFit);

        typedef CustomEditTextCallbackPtr DataBrowserEditItemUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID number for the item to be drawn.
  
  
• property - the Property ID number for the item to be drawn.
  
  
• theString - a reference to the string that is to be edited.
  
  
• maxEditTextRect - if shrinkToFit is turned on, this is the largest size the edit field can grow in size. If the text grows beyond the size of the edit field, it will scroll inside of the field as the user types (according to the Aqua user interface guidelines). If shrinkToFit is false, this is the size of the edit field that will be used.
  
  
• shrinkToFit - if you set this parameter to true, then the DataBrowser will expand and shrink the text editing box to match the width of the text appearing in the edit field. With this version of the DataBrowser, this parameter is ignored and shrinkToFit it always true by default.

If your application returns the value true, then the DataBrowser will go ahead and perform the editing operation. If your application returns the value false, then no editing operation will occur.

Figure 6. Differentiation between a custom cell's content area and its background.

    typedef Boolean (*CustomHitTestCallbackPtr)(
        ControlRef browser,
        DataBrowserItemID itemID,
        DataBrowserPropertyID property,
        const Rect *theRect,
        const Rect *mouseRect);

    typedef CustomHitTestCallbackPtr DataBrowserHitTestUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemID - the Data ID number for the row where the mouse is located.
  
  
• property - the Property ID number for the column where the mouse is located.
  
  
• theRect - the location of the cell's boundary rectangle on the screen in local window coordinates.
  
  
• mouseRect - contains the coordinates of the mouse. If the top left and bottom right coordinates of this rectangle are identical, then a single point is being tested. If they differ, then the DataBrowser is testing to see if your custom item is inside of a marque selection (use SectRect or SectRgn to determine if the selectable content of the custom cell is part of the selection).

Your application should return a true when either the mouse is located over the selectable or draggable content part of the cell or the marque selection rectangle, provided in *mouseRect, intersects with the selectable or draggable content area of the cell.

    typedef SInt16 (*CustomTrackingCallbackPtr)(
        ControlRef browser,
        DataBrowserItemID itemID,
        DataBrowserPropertyID property,
        const Rect *theRect,
        Point startPt,
        EventModifiers modifiers);

    typedef CustomTrackingCallbackPtr DataBrowserTrackingUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemID - the Data ID number for the row where the mouse is located.
  
  
• property - the Property ID number for the column where the mouse is located.
  
  
• theRect - the cell's location in local window coordinates.
  
  
• startPt - the location of the mouse when the drag began.
  
  
• modifiers - the state of the modifier keys as passed in the modifiers parameter to the HandleControlClick routine.

Your CustomTrackingCallback will only be called for mouse-down events and only after your CustomHitTestCallback has returned true. Your tracking procedure should do one of three things:

1. Provide its own custom tracking behavior and animation and return the result -1. A result of -1 tells the DataBrowser that your application performed its own drag processing and no further processing is required.
   
   
2. Return the value zero to indicate that nothing has been hit and no further processing should take place.
   
   
3. Return the value 1 to tell the DataBrowser to continue processing the click in its own way.
   
   

    typedef void (*CustomDragRegionCallbackPtr)(
        ControlRef browser,
        DataBrowserItemID itemID,
        DataBrowserPropertyID property,
        const Rect *theRect,
        RgnHandle dragRgn);

    typedef CustomDragRegionCallbackPtr DataBrowserItemDragRgnUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemID - the Data ID number for the row to be represented in the drag region.
  
  
• property - the Property ID number for the column to be represented in the drag region.
  
  
• theRect - the cell's location in local window coordinates.
  
  
• dragRgn - a reference to the region.

    typedef UInt16 (*CustomAcceptDragCallbackPtr )(
        ControlRef browser,
        DataBrowserItemID itemID,
        DataBrowserPropertyID property,
        const Rect *theRect,
        DragReference theDrag);

    typedef CustomAcceptDragCallbackPtr
        DataBrowserItemAcceptDragUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemID - the Data ID number for the target row.
  
  
• property - the Property ID number for the target column.
  
  
• theRect - the cell's location in local window coordinates.
  
  
• theDrag - a Drag Manager drag reference.

The value returned by this routine is passed through to your application's CustomReceiveDragCallback in the dragFlags parameter. Your application's CustomAcceptDragCallback will be called by the DataBrowser when a drag is moved over your custom cell. If the cell cannot accept the drag, return zero. Otherwise, if the cell is an acceptable drop location for the drag, return a non-zero value.

    typedef Boolean (*CustomReceiveDragCallbackPtr )(
        ControlRef browser,
        DataBrowserItemID itemID,
        DataBrowserPropertyID property,
        UInt16 dragFlags,
        DragReference theDrag);

    typedef CustomReceiveDragCallbackPtr
        DataBrowserItemReceiveDragUPP;

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• itemID - the Data ID number for the row where the drop occurred.
  
  
• property - the Property ID number for the column where the drop occurred.
  
  
• dragFlags - the drag flags provided by the Drag Manager.
  
  
• theDrag - the Drag Manager drag reference.

Your CustomReceiveDragCallback should return true if it successfully received the drag. If it returns false, then the zoom-back animation will occur.

The InitDataBrowserCustomCallbacks routine.

    OSStatus InitDataBrowserCustomCallbacks(
        DataBrowserCustomCallbacks *callbacks);

• callbacks - a pointer to a DataBrowserCustomCallbacks structure. The version field of the DataBrowserCustomCallbacks structure must be set to the value kDataBrowserLatestCustomCallbacks 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 SetDataBrowserCustomCallbacks routine.

    OSStatus SetDataBrowserCustomCallbacks(
        ControlRef browser,
        DataBrowserCustomCallbacks *callbacks);

• control - a Data Browser control created by a call to CreateDataBrowserControl.
  
  
• callbacks - a pointer to a DataBrowserCustomCallbacks 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 GetDataBrowserCustomCallbacks routine.

    OSStatus GetDataBrowserCustomCallbacks(
        ControlRef browser,
        DataBrowserCustomCallbacks* callbacks);

• control - a Data Browser control created by a call to CreateDataBrowserControl.
  
  
• callbacks - a pointer to a DataBrowserCustomCallbacks structure.

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

Figure 7. The general flow of control for mouse-down and update events.

The SetDataBrowserActiveItems routine.

    OSStatus SetDataBrowserActiveItems(
        ControlRef browser,
        Boolean active);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• active - a boolean value containing the new active state for the items displayed in 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 GetDataBrowserActiveItems routine.

    OSStatus GetDataBrowserActiveItems(
        ControlRef browser,
        Boolean *active);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• active - the current active state of the items displayed in the list will be returned in the boolean 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 SetDataBrowserScrollPosition routine.

    OSStatus SetDataBrowserScrollPosition(
        ControlRef browser,
        UInt32 top,
        UInt32 left);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• top - the current vertical scrolling position will be set to the value provided in this parameter.
  
  
• left - the current horizontal scrolling position will be set to the value provided in 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 GetDataBrowserScrollPosition routine.

    OSStatus GetDataBrowserScrollPosition(
        ControlRef browser,
        UInt32 *top,
        UInt32 *left);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• top - the variable pointed to by this parameter will be set to the current vertical scrolling position.
  
  
• left - the variable pointed to by this parameter will be set to the current horizontal scrolling position.

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

The SetDataBrowserHasScrollBars routine.

    OSStatus SetDataBrowserHasScrollBars(
        ControlRef browser,
        Boolean horiz,
        Boolean vert);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• horiz - set this parameter to true if the list should be displayed with a horizontal scroll bar.
  
  
• vert - set this parameter to true if the list should be displayed with a vertical scroll bar.

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

The GetDataBrowserHasScrollBars routine.

    OSStatus GetDataBrowserHasScrollBars(
        ControlRef browser,
        Boolean *horiz,
        Boolean *vert);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• horiz - the variable pointed to by this parameter will be set to true if the browser control is being displayed with a horizontal scroll bar.
  
  
• vert - the variable pointed to by this parameter will be set to true if the browser control is being displayed with a vertical scroll bar.

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

Figure 8. An example of a placard displayed at the bottom left of the list. As shown here, the scroll bar is inset on its right-hand side to provide enough space for the placard.

The SetDataBrowserScrollBarInset routine.

    OSStatus SetDataBrowserScrollBarInset(
        ControlRef browser,
        Rect *insetRect);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• insetRect - the current inset settings your application would like the DataBrowser to use. Your application should modify the inset settings returned by GetDataBrowserScrollBarInset instead of assuming that the DataBrowser will set them to any particular value.

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

Use this to add placards or status panels beside above or below the scroll bars. Call GetDataBrowserScrollBarInset before calling this routine.

The GetDataBrowserScrollBarInset routine.

    OSStatus GetDataBrowserScrollBarInset(
        ControlRef browser,
        Rect *insetRect);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• insetRect - the current inset settings for the browser control's scroll bars will be returned in the rectangle pointed to by this parameter. The left and right fields will contain the horizontal inset values for the horizontal scroll bar, and the top and bottom fields will contain the vertical inset values for the vertical scroll bar.

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

The RevealDataBrowserItem routine.

    OSStatus RevealDataBrowserItem(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID propertyID,
        Boolean centerInView);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the item to display.
  
  
• propertyID - the Property ID of the column to display.
  
  
• centerInView - if true, then the DataBrowser will try to center the item in the display area.

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

The SetDataBrowserSelectionFlags routine.

    OSStatus SetDataBrowserSelectionFlags(
        ControlRef browser,
        DataBrowserSelectionFlags selectionFlags);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• selectionFlags - can be any combination of the following flag values:
  
  
  • kDataBrowserDragSelect - This turns on or off the availability of the selection marque. The marque will show up if the click was not on content, or the Option key is not down and kDataBrowserDragSelect is on kDataBrowserSelectOnlyOne is off and kDataBrowserNoDisjointSelection is off.
    
    
  • kDataBrowserSelectOnlyOne - allow only one item to be selected at once.
    
    
  • kDataBrowserResetSelection - reset list before processing next selection operation.
    
    
  • kDataBrowserCmdTogglesSelection - allow use of command to toggle items in and out of the selection.
    
    
  • kDataBrowserNoDisjointSelection - prevent discontinuous selections.
    
    
  • kDataBrowserAlwaysExtendSelection - enable multiple item selection without holding down any modifier keys.

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

The GetDataBrowserSelectionFlags routine.

    OSStatus GetDataBrowserSelectionFlags(
        ControlRef browser,
        DataBrowserSelectionFlags *selectionFlags);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• selectionFlags - See the description of SetDataBrowserSelectionFlags for more information about the value that can be returned in 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 IsDataBrowserItemSelected routine.

    Boolean IsDataBrowserItemSelected(
        ControlRef browser,
        DataBrowserItemID item);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the item to be tested.

Returns true if the item specified by the Data ID provided in the item parameter is a member of the current selection.

The SetDataBrowserSelectedItems routine.

    OSStatus SetDataBrowserSelectedItems(
        ControlRef browser,
        UInt32 numItems,
        DataBrowserItemID *items,
        DataBrowserSetOption operation);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• numItems - the number of Data ID numbers stored in the array pointed to by the items parameter.
  
  
• items - an array of Data ID numbers.
  
  
• operation - the operation to be performed on the current selection:
  
  
  • kDataBrowserItemsAssign - set the selection to the items specified in the array pointed to by the items parameter. Any previous selection is replaced and the list will be re-drawn appropriately.
    
    
  • kDataBrowserItemsToggle - if any of the items specified in the array pointed to by the items parameter are in the current selection, then remove them from the selection. For those items that are not in the selection, add them to the selection.
    
    
  • kDataBrowserItemsRemove - if any of the items specified in the array pointed to by the items parameter are in the current selection, then remove them from the selection and redraw their cells so they are not highlighted.

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

The UpdateDataBrowserItems routine.

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

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - The ID number of the container for the Data ID numbers referenced by the items parameter.
  
  
• numItems - the number of Data ID numbers referenced by the items parameter.
  
  
• items - a pointer to an array of Data ID numbers. If the value kDataBrowserNoItem appears anywhere in this array, then all of the rows will be updated.
  
  
• preSortProperty - the sort order of the Data ID numbers referenced by the items parameter. If the Data ID numbers referenced by the items parameter are not sorted according to any property, then your application should provide the value kDataBrowserNoProperty in this parameter.
  
  
• propertyID - the Property ID of the column that must be kDataBrowserPropertyIsEditabled. To update all columns for the items referenced by the Data ID numbers referenced by the items parameter, set this parameter to kDataBrowserNoItem.
  
  

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

IMPORTANT
Instead of forcing an update event to redraw the DataBrowser control contents, your application should call the UpdateDataBrowserItems routine as this routine since it will also update any internal caches that may have been allocated by the DataBrowser.

The SetDataBrowserListViewHeaderBtnHeight routine.

    OSStatus SetDataBrowserListViewHeaderBtnHeight(
        ControlRef browser,
        UInt16 height);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• height - 0 turns off header buttons, use a saved value returned by GetDataBrowserListViewHeaderBtnHeight to turn on buttons. No other values are defined at this time.

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

The GetDataBrowserListViewHeaderBtnHeight routine.

    OSStatus GetDataBrowserListViewHeaderBtnHeight(
        ControlRef browser,
        UInt16 *height);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• height - the current height of the header buttons area is 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 AutoSizeDataBrowserListViewColumns routine.

    OSStatus AutoSizeDataBrowserListViewColumns(
        ControlRef browser);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.

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

The GetDataBrowserItemPartBounds routine.

    OSStatus GetDataBrowserItemPartBounds(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property,
        DataBrowserPropertyPart part,
        Rect *bounds);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID identifying the cell's row.
  
  
• property - the Property ID identifying the cell's column.
  
  
• part - a constant value describing the part of the cell you would like to obtain information about. The type of information requested will depend on the type of information being displayed in the column. It is up to your application to ensure it is requesting the appropriate information. The following constants may be provided in this parameter:
  
  
  • kDataBrowserPropertyEnclosingPart - the outer boundary of the cell.
    
    
  • kDataBrowserPropertyContentPart - the content of the cell.
    
    
  • kDataBrowserPropertyDisclosurePart - the location of the disclosure rectangle.
    
    
  • kDataBrowserPropertyTextPart - the location where the text is drawn.
    
    
  • kDataBrowserPropertyIconPart - the location where the icon is displayed.
    
    
  • kDataBrowserPropertyCheckboxPart - the location of the checkbox.
    
    
  • kDataBrowserPropertyProgressBarPart - the location of the progress bar.
    
    
  • kDataBrowserPropertyRelevanceRankPart - the location of the relevance rank.
  
  
• bounds - a pointer to a rectangle where the coordinates will be returned.

Returns an operating system result code describing the success of the operation. The code noErr will be returned if the operation was successful. If the cell is not visible (scrolled off the screen), it will return an ItemNotFound error.

The SetDataBrowserListViewUsePlainBackground routine.

    OSStatus SetDataBrowserListViewUsePlainBackground(
        ControlRef browser,
        Boolean usePlainBackground);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• usePlainBackground - platinum only. Plain background uses all white background. False uses shaded platinum background. Currently Aqua only supports plain white background. Call this only if you do not want to have a shaded sort column.

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

The GetDataBrowserListViewUsePlainBackground routine.

    OSStatus GetDataBrowserListViewUsePlainBackground(
        ControlRef browser,
        Boolean *usePlainBackground);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• usePlainBackground - the variable pointed to by this parameter will be set to true if the control is set to use a plain white background.

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 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 SetDataBrowserEditItem routine.

    OSStatus SetDataBrowserEditItem(
        ControlRef browser,
        DataBrowserItemID item,
        DataBrowserPropertyID property);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• item - the Data ID of the item to be edited.
  
  
• property - the Property ID of the column containing the item.

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

The GetDataBrowserEditItem routine.

    OSStatus GetDataBrowserEditItem(
        ControlRef browser,
        DataBrowserItemID *item,
        DataBrowserPropertyID *property);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
• item - the Data ID of the item that is being edited will be returned in the variable pointed to by this parameter. If there is no cell being edited, this parameter will be set to kDataBrowserNoItem.
  
  
• property - the Property ID of the column containing the item that is being edited will be returned in the variable pointed to by this parameter. If there is no cell being edited, this parameter will be set to zero.

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

The SetDataBrowserEditText routine.

    OSStatus SetDataBrowserEditText(
        ControlRef browser,
        CFStringRef text);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• text - a CFStringRef. The DataBrowser will make its own internal copy of this reference so it is safe to release your own internal reference after you call this routine.

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

The GetDataBrowserEditText routine.

    OSStatus GetDataBrowserEditText(
        ControlRef browser,
        CFMutableStringRef text);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• text - a CFMutableStringRef. Your application must allocate this string and pass it to the DataBrowser. The DataBrowser will set its contents to the current contents of the edit session's text field.

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

The EnableDataBrowserEditCommand routine.

    Boolean EnableDataBrowserEditCommand(
        ControlRef browser,
        DataBrowserEditCommand command);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• command - this parameter must be set to one of the following constant values:
  
  
  • kDataBrowserEditMsgUndo - undo the last operation.
    
    
  • kDataBrowserEditMsgCut - cut the contents of the selection inside of the current edit session to the clipboard.
    
    
  • kDataBrowserEditMsgCopy - copy the contents of the selection inside of the current edit session to the clipboard.
    
    
  • kDataBrowserEditMsgPaste - replace the contents of the selection inside of the current edit session with the contents of the clipboard.
    
    
  • kDataBrowserEditMsgClear - remove the contents of the selection inside of the current edit session.
    
    
  • kDataBrowserEditMsgSelectAll - select all of the text inside of the current edit session.
  
  

Returns true if the requested editing command can be performed by the DataBrowser control at this time.

The ExecuteDataBrowserEditCommand routine.

    OSStatus ExecuteDataBrowserEditCommand(
        ControlRef browser,
        DataBrowserEditCommand command);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• command - a constant indicating what command should be performed. See the description of EnableDataBrowserEditCommand for a list of possible values for 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 SetDataBrowserTarget routine.

    OSStatus SetDataBrowserTarget(
        ControlRef browser,
        DataBrowserItemID target);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• target - the ID that should be assigned as the default target ID for the browser control.

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

The GetDataBrowserTarget routine.

    OSStatus GetDataBrowserTarget(
        ControlRef browser,
        DataBrowserItemID *target);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• target - a pointer to a location where the currently assigned target ID will be returned.

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

The SetDataBrowserListViewDisclosureColumn routine.

    OSStatus SetDataBrowserListViewDisclosureColumn(
        ControlRef browser,
        DataBrowserTableViewColumnID column,
        Boolean expandableRows);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• column - if this is no column or the column doesn't exist, then there will be no disclosure column.
  
  
• expandableRows - if the row itself expands rather than opening up several sub-rows set this parameter to true. Currently this parameter is ignored.

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

The GetDataBrowserListViewDisclosureColumn routine.

    OSStatus GetDataBrowserListViewDisclosureColumn(
        ControlRef browser,
        DataBrowserTableViewColumnID *column,
        Boolean *expandableRows);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• column - the Property ID of the column where the disclosure triangles are being displayed will be returned in the variable pointed to by this parameter.
  
  
• expandableRows - if the row itself expands rather than opening up several sub-rows, then the variable pointed to by this parameter will be set to true.

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

The OpenDataBrowserContainer routine.

    OSStatus OpenDataBrowserContainer(
        ControlRef browser,
        DataBrowserItemID container);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - The Data ID of the container you would like to open.

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

The CloseDataBrowserContainer routine.

    OSStatus CloseDataBrowserContainer(
        ControlRef browser,
        DataBrowserItemID container);

• browser - a DataBrowser control created by a call to CreateDataBrowserControl.
  
  
• container - The Data ID of the container you would like to close.

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