Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Data Browser Reference

Framework
Carbon/Carbon.h
Declared in
HIDataBrowser.h

Overview

The data browser application programming interface (API) provides a convenient way to present data for browsing and to create easily customized lists whose columns can be sorted, moved, and resized. It supports two presentation styles, each of which is derived from an abstract table-view base class:

The data browser programming interface has some routines that apply to both views while others are unique to one view. For functions that can be called for either, there may be differences in how the functions operate. Such differences are noted in the documentation for individual functions.

These terms are essential to understanding the reference:

After you’ve created, formatted, and configured a data browser, most of the work of keeping the data browser updated and responsive to user interaction happens through callbacks you provide. For example, all of the functions that get and set item data are called from within an item-data callback provided by your application. Your application has a wide latitude in what it can choose to handle through callbacks and the tasks it lets the system perform. At the very least, your application must provide an item-data callback. Otherwise no data will ever be written to the data browser user interface. Depending on the nature of your application, you may also want to provide callbacks to handle drag-and-drop behavior, to support contextual menus, and to perform custom drawing or some other custom behavior.

The data browser is available with CarbonLib 1.1 and later and in Mac OS X.

For conceptual information and instructions on how to write code that uses a data browser to display data, see Data Browser Programming Guide.

Functions by Task

Creating and Configuring a Data Browser

Manipulating Data Browser Attributes

Setting Up and Installing Callbacks

Formatting Table View

Table view is a base class from which list and column views are derived. Some functions in this group can be used with both list and column views, while others are useful only in list view.

Formatting List View

Formatting Column View

Adding and Removing Data Items

Accessing and Operating on All Items

Accessing and Displaying Individual Items

Selecting and Editing Items

Working With Attributes

Working With Containers

Working With Metrics

Getting and Setting Item Data

The functions in this section are called from within an item-data callback routine (DataBrowserItemDataProcPtr) provided by your application. The data browser invokes your item-data callback each time your application needs to provide data for the display. Your callback responds by calling the appropriate function from this section.

Working With Universal Procedure Pointers

The functions in this section create and dispose of universal procedure pointers (UPPs) to the callbacks you provide to the data browser. For each callback, there is a New, Dispose, and Invoke function. You don’t need to use an Invoke function, because the data browser invokes callbacks for you.

The documentation for the UPP functions in this section is boilerplate text—quite repetitive and you can likely skip over it. The more interesting documentation is for the callbacks themselves, which you can find in the section “Data Browser Callbacks.”

Working With AXUIElement References

Functions

AddDataBrowserItems

Adds one or more items to a data browser. 

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

Parameters
browser

A data browser.

container

An item ID or the constant kDataBrowserNoItem. Pass the item ID that uniquely identifies the container to which you want to add items. Adding one or more items to an existing container opens the container. If you a pass kDataBrowserNoItem, the items are added to the root container.

numItems

The number of items in the array pointed to by the items parameter.

items

A pointer to an array of item ID values for the items you want to add to the data browser. You supply item ID values based on your own identification scheme. If you pass NULL, each time you call AddDataBrowserItems the data browser generates item ID values starting at 1. Calling the function in this way clears whatever items are in the container. Because of this clearing behavior, passing NULL is not recommended unless your application uses a data browser to display a simple list that is populated only once with data.

preSortProperty

The property ID of the column whose sorting order matches the sorting order of the items array. A property ID is a four-character sequence that you assign to represent a column in list view. Pass kDataBrowserItemNoProperty if the items array is not sorted or if you don’t know the sorting order of your data. You’ll get the best performance from this function if you provide a sorting order.

Return Value

A result code. If the item ID specified by the container parameter is not classified as a container, returns errDataBrowserItemNotAdded if you attempt to add subitems to it. See “Data Browser Result Codes.”

Discussion

Hierarchical lists are constructed in a top-down fashion. Your application must install all the top-level, or parent, item IDs in the data browser before it associates a list of item ID values as subitems. You can add items to a parent item only after the parent item is classified as a container. A container is an item for which the property kDataBrowserItemIsContainerProperty is set to true.

Availability
Declared In
HIDataBrowser.h

AddDataBrowserListViewColumn

Adds a column to a data browser that uses list view.

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

Parameters
browser

A data browser.

columnDesc

A pointer to the list view column description data structure that you have filled out with data that specifies the column property and display information for the column heading.

position

The position, among the columns already installed in the data browser, to insert this column. To insert this column to the right of all other columns, pass kDataBrowserListViewAppendColumn. The value 0 means the leftmost column.

Return Value

A result code; paramErr is returned if the columnDesc parameter is not properly initialized. See “Data Browser Result Codes.”

Discussion

Typically you use the function AddDataBrowserListViewColumn in these cases:

Availability
Declared In
HIDataBrowser.h

AutoSizeDataBrowserListViewColumns

Adjusts the size of columns displayed in list view to take best advantage of the available space. 

OSStatus AutoSizeDataBrowserListViewColumns (
   ControlRef browser
);

Parameters
browser

A data browser.

Return Value

A result code. See “Data Browser Result Codes.”

Discussion

When you call the function AutoSizeDataBrowserListViewColumns, it first calculates whether there is extra space or not enough space in the data browser. Then, the columns are resized using the following rules:

The function AutoSizeDataBrowserListViewColumns resizes only if the horizontal scroll bar is turned off. Your application can call the function SetDataBrowserHasScrollBars to turn off the horizontal scroll bar.

Availability
Declared In
HIDataBrowser.h

AXUIElementCreateWithDataBrowserAndItemInfo

Creates an AXUIElementRef that represents some part of a data browser accessibility hierarchy.

AXUIElementRef AXUIElementCreateWithDataBrowserAndItemInfo (
   ControlRef inDataBrowser,
   const DataBrowserAccessibilityItemInfo *inInfo
);

Parameters
inDataBrowser

A data browser.

inInfo

A DataBrowserAccessibilityItemInfo structure describing the part of the data browser for which you want to create an AXUIElementRef.

Return Value

An AXUIElementRef representing the part, or NULL if an AXUIElementRef cannot be created to represent the part you specified.

Availability
Declared In
HIDataBrowser.h

AXUIElementGetDataBrowserItemInfo

Obtains a description of the part of a data browser represented by an AXUIElementRef.

OSStatus AXUIElementGetDataBrowserItemInfo (
   AXUIElementRef inElement,
   ControlRef inDataBrowser,
   UInt32 inDesiredInfoVersion,
   DataBrowserAccessibilityItemInfo *outInfo
);

Parameters
inElement

An AXUIElementRef representing part of a data browser.

inDataBrowser

A data browser.

inDesiredInfoVersion

The version of DataBrowserAccessibilityItemInfo structure you want to get. Currently, the only supported version is zero, so you must pass 0 or 1 as the value of this parameter.

outInfo

On input, a pointer to a DataBrowserAccessibilityItemInfo structure. On return, the structure is filled in with a description of the part of the data browser that the AXUIElementRef specified by inElement represents.

Return Value

A result code. See “Data Browser Result Codes.” The function returns noErr if it was able to generate a description of the AXUIElementRef. If the AXUIElementRef does not represent the data browser you passed in, the function returns paramErr. If the AXUIElementRef represents some non-item part of the data browser, the function returns errDataBrowserItemNotFound.

Availability
Declared In
HIDataBrowser.h

CloseDataBrowserContainer

Closes a data browser container. 

OSStatus CloseDataBrowserContainer (
   ControlRef browser,
   DataBrowserItemID container
);

Parameters
browser

A data browser.

container

The item ID of the container you want to close.

Return Value

A result code. See “Data Browser Result Codes.”

Discussion

Normally the user navigates through a data hierarchy by clicking the disclosure triangle next to a container item in list view, or the container item (such as a folder icon) in column view. In either of these cases, the system automatically opens or closes the container. Under some circumstances your application may need to open or close a container programmatically, such as when you are restoring a display to its last known state. In such cases, you can call the function OpenDataBrowserContainer to disclose items in a container or the function CloseDataBrowserContainer to hide items in a container.

Availability
Declared In
HIDataBrowser.h

CopyDataBrowserEditText

Copies the text being edited by the user. 

OSStatus CopyDataBrowserEditText (
   ControlRef browser,
   CFStringRef *text
);

Parameters
browser

A data browser.

text

On input, a CFStringRef variable initialized to anything other than NULL. See the Special Considerations for details. On return, a CFString object that contains a copy of the text edited by the user. You are responsible for releasing the string when you no longer need it.

Return Value

A result code. See “Data Browser Result Codes.”

Discussion

This function is useful only if an edit session is in progress for an item. You can check whether an edit session is open by calling the function GetDataBrowserEditItem.

Special Considerations

For versions of Mac OS X prior to v10.4, the text parameter must be set to any value other than NULL. Do not allocate the CFStringRef, otherwise your application will leak memory. Instead provide code similar to the following to initialize the variable:

CFStringRef myText = 0XFFFFFFFF;

Availability
Declared In
HIDataBrowser.h

CreateDataBrowserControl

Creates a data browser programmatically.

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

Parameters
window

The window in which to place the data browser.

boundsRect

A pointer to a rectangle that specifies the location where you want the control to appear in the window.

style

The view style to use. Pass the constant kDataBrowserListView to draw the data browser using list view or kDataBrowserColumnView draw the data browser using column view. See “View Styles” for more information on these constants.

outControl

On input, a pointer to a control reference. On return, this is set to the newly created data browser. When you no longer need the data browser, call the Control Manager function DisposeControl to release it. When you dispose of the control, deallocate any universal procedure pointers you allocated for use with the control.

Return Value

A result code. See “Data Browser Result Codes.”

Discussion

This function creates a data browser programmatically. If you create a data browser using Interface Builder, you don’t need to call CreateDataBrowserControl. Instead, you call the function GetControlByID to obtain a control reference that points to your data browser.

After you create a data browser by calling CreateDataBrowserControl, you can set such attributes as sorting order, scroll bars, and scroll position. See “Manipulating Data Browser Attributes” for the functions you can use to set data browser attributes.

You need to set up the display characteristics of the data browser by calling the appropriate functions. See “Formatting Table View,” “Formatting List View,” and “Formatting Column View” for information on the formatting functions you can call.

You need to call the functions InitDataBrowserCallbacks and SetDataBrowserCallbacks to install the callbacks needed for your data browser. At the very least, you must provide an item-data callback to add or change data items; you must do so regardless of the content your data browser displays—noncustom or custom. Otherwise, your data browser will be empty. See DataBrowserItemDataProcPtr for more information. If you present hierarchical data in list view, or use column view for browsing data, you must provide a callback to handle item notifications. See DataBrowserItemNotificationProcPtr and DataBrowserItemNotificationWithItemProcPtr.

You can optionally provide callbacks to:

If your data browser uses a list whose columns require custom drawing or behavior, you must also provide callbacks to handle the custom tasks. See InitDataBrowserCustomCallbacks and SetDataBrowserCustomCallbacks for more information on initializing and installing callbacks for custom behavior. The custom tasks you can handle in list view include: