| Framework | Carbon/Carbon.h |
| Declared in | HIDataBrowser.h |
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:
List view, which lets you present items in multiple columns with the option to create hierarchical lists whose contents can be disclosed by the user
Column view, which provides in-place browsing using fixed navigation columns
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:
An item in a data browser refers to the data displayed at a particular row and column intersection. In list view, two values identify each item—an item ID and a property ID. In column view, one value—the item ID—uniquely identifies an item.
An item ID is a unique 32-bit ID number that your application uses to refer to data. When you ask the data browser to display one or more items, you provide an item ID for each data item. You can store the actual data in memory, on disk, or across a network. Item IDs must be greater than 0, which is used internally by the data browser. Item IDs can be values such as pointer values, data file offsets, and 32-bit TCP/IP host addresses.
A Property ID is a non-zero, 32-bit unsigned integer value that uniquely identifies a list view column. Property IDs do not need to be ordered or sequential, but they cannot be values 0 through 1023 because those values are reserved by Apple. A property ID is typically defined as a four-character sequence. For example, a column that displays dates could be assigned the property ID DATE.
Columns in column view don’t use application-defined property IDs. Instead, columns in column view have the predefined property kDataBrowserItemSelfIdentityProperty.
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.
GetDataBrowserUserState
SetDataBrowserUserState
SetDataBrowserActiveItems
GetDataBrowserActiveItems
SetDataBrowserScrollBarInset
GetDataBrowserScrollBarInset
SetDataBrowserTarget
GetDataBrowserTarget
SetDataBrowserSortOrder
GetDataBrowserSortOrder
SetDataBrowserScrollPosition
GetDataBrowserScrollPosition
SetDataBrowserHasScrollBars
GetDataBrowserHasScrollBars
SetDataBrowserSortProperty
GetDataBrowserSortProperty
SetDataBrowserSelectionFlags
GetDataBrowserSelectionFlags
SetDataBrowserPropertyFlags
GetDataBrowserPropertyFlags
SetDataBrowserEditText
CopyDataBrowserEditText
GetDataBrowserEditText
SetDataBrowserEditItem
GetDataBrowserEditItem
GetDataBrowserItemPartBounds
InitDataBrowserCallbacks
SetDataBrowserCallbacks
GetDataBrowserCallbacks
InitDataBrowserCustomCallbacks
SetDataBrowserCustomCallbacks
GetDataBrowserCustomCallbacks
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.
RemoveDataBrowserTableViewColumn
GetDataBrowserTableViewColumnCount
SetDataBrowserTableViewHiliteStyle
GetDataBrowserTableViewHiliteStyle
SetDataBrowserTableViewRowHeight
GetDataBrowserTableViewRowHeight
SetDataBrowserTableViewColumnWidth
GetDataBrowserTableViewColumnWidth
SetDataBrowserTableViewItemRowHeight
GetDataBrowserTableViewItemRowHeight
SetDataBrowserTableViewNamedColumnWidth
GetDataBrowserTableViewNamedColumnWidth
SetDataBrowserTableViewGeometry
GetDataBrowserTableViewGeometry
GetDataBrowserTableViewItemID
SetDataBrowserTableViewItemRow
GetDataBrowserTableViewItemRow
SetDataBrowserTableViewColumnPosition
GetDataBrowserTableViewColumnPosition
GetDataBrowserTableViewColumnProperty
AutoSizeDataBrowserListViewColumns
AddDataBrowserListViewColumn
GetDataBrowserListViewHeaderDesc
SetDataBrowserListViewHeaderDesc
SetDataBrowserListViewHeaderBtnHeight
GetDataBrowserListViewHeaderBtnHeight
SetDataBrowserListViewUsePlainBackground
GetDataBrowserListViewUsePlainBackground
SetDataBrowserListViewDisclosureColumn
GetDataBrowserListViewDisclosureColumn
SetDataBrowserColumnViewPath
GetDataBrowserColumnViewPath
GetDataBrowserColumnViewPathLength
SetDataBrowserColumnViewDisplayType
GetDataBrowserColumnViewDisplayType
EnableDataBrowserEditCommand
ExecuteDataBrowserEditCommand
GetDataBrowserSelectionAnchor
MoveDataBrowserSelectionAnchor
SetDataBrowserSelectedItems
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.
SetDataBrowserItemDataIcon
GetDataBrowserItemDataIcon
SetDataBrowserItemDataText
GetDataBrowserItemDataText
SetDataBrowserItemDataValue
GetDataBrowserItemDataValue
SetDataBrowserItemDataMinimum
GetDataBrowserItemDataMinimum
SetDataBrowserItemDataMaximum
GetDataBrowserItemDataMaximum
SetDataBrowserItemDataBooleanValue
GetDataBrowserItemDataBooleanValue
SetDataBrowserItemDataMenuRef
GetDataBrowserItemDataMenuRef
SetDataBrowserItemDataRGBColor
GetDataBrowserItemDataRGBColor
SetDataBrowserItemDataDrawState
GetDataBrowserItemDataDrawState
SetDataBrowserItemDataButtonValue
GetDataBrowserItemDataButtonValue
SetDataBrowserItemDataIconTransform
GetDataBrowserItemDataIconTransform
SetDataBrowserItemDataDateTime
GetDataBrowserItemDataDateTime
SetDataBrowserItemDataLongDateTime
GetDataBrowserItemDataLongDateTime
SetDataBrowserItemDataItemID
GetDataBrowserItemDataItemID
GetDataBrowserItemDataProperty
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.”
NewDataBrowserItemUPP
InvokeDataBrowserItemUPP
DisposeDataBrowserItemUPP
NewDataBrowserItemDataUPP
InvokeDataBrowserItemDataUPP
DisposeDataBrowserItemDataUPP
NewDataBrowserItemCompareUPP
InvokeDataBrowserItemCompareUPP
DisposeDataBrowserItemCompareUPP
NewDataBrowserItemNotificationUPP
InvokeDataBrowserItemNotificationUPP
DisposeDataBrowserItemNotificationUPP
NewDataBrowserItemNotificationWithItemUPP
InvokeDataBrowserItemNotificationWithItemUPP
DisposeDataBrowserItemNotificationWithItemUPP
NewDataBrowserAddDragItemUPP
InvokeDataBrowserAddDragItemUPP
DisposeDataBrowserAddDragItemUPP
NewDataBrowserAcceptDragUPP
InvokeDataBrowserAcceptDragUPP
DisposeDataBrowserAcceptDragUPP
NewDataBrowserReceiveDragUPP
InvokeDataBrowserReceiveDragUPP
DisposeDataBrowserReceiveDragUPP
NewDataBrowserPostProcessDragUPP
InvokeDataBrowserPostProcessDragUPP
DisposeDataBrowserPostProcessDragUPP
NewDataBrowserGetContextualMenuUPP
InvokeDataBrowserGetContextualMenuUPP
DisposeDataBrowserGetContextualMenuUPP
NewDataBrowserSelectContextualMenuUPP
InvokeDataBrowserSelectContextualMenuUPP
DisposeDataBrowserSelectContextualMenuUPP
NewDataBrowserItemHelpContentUPP
InvokeDataBrowserItemHelpContentUPP
DisposeDataBrowserItemHelpContentUPP
NewDataBrowserDrawItemUPP
InvokeDataBrowserDrawItemUPP
DisposeDataBrowserDrawItemUPP
NewDataBrowserEditItemUPP
InvokeDataBrowserEditItemUPP
DisposeDataBrowserEditItemUPP
NewDataBrowserHitTestUPP
InvokeDataBrowserHitTestUPP
DisposeDataBrowserHitTestUPP
NewDataBrowserTrackingUPP
InvokeDataBrowserTrackingUPP
DisposeDataBrowserTrackingUPP
NewDataBrowserItemDragRgnUPP
InvokeDataBrowserItemDragRgnUPP
DisposeDataBrowserItemDragRgnUPP
NewDataBrowserItemAcceptDragUPP
InvokeDataBrowserItemAcceptDragUPP
DisposeDataBrowserItemAcceptDragUPP
NewDataBrowserItemReceiveDragUPP
InvokeDataBrowserItemReceiveDragUPP
DisposeDataBrowserItemReceiveDragUPP
Adds one or more items to a data browser.
OSStatus AddDataBrowserItems ( ControlRef browser, DataBrowserItemID container, ItemCount numItems, const DataBrowserItemID *items, DataBrowserPropertyID preSortProperty );
A data browser.
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.
The number of items in the array pointed to by the items parameter.
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.
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.
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.”
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.
HIDataBrowser.h
Adds a column to a data browser that uses list view.
OSStatus AddDataBrowserListViewColumn ( ControlRef browser, DataBrowserListViewColumnDesc *columnDesc, DataBrowserTableViewColumnIndex position );
A data browser.
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.
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.
A result code; paramErr is returned if the columnDesc parameter is not properly initialized. See “Data Browser Result Codes.”
Typically you use the function AddDataBrowserListViewColumn in these cases:
When you create a data browser programmatically. If you use Interface Builder to design and lay out the data browser, you do not need to call the function AddDataBrowserListViewColumn. Interface Builder lets you position a column graphically and then specify the column description in the column pane of the Info window.
When you switch from column view to list view. Regardless of how you first create a data browser, if your application allows the user to switch between views, you need to add list view columns each time the view switches from column to list view.
HIDataBrowser.h
Adjusts the size of columns displayed in list view to take best advantage of the available space.
OSStatus AutoSizeDataBrowserListViewColumns ( ControlRef browser );
A data browser.
A result code. See “Data Browser Result Codes.”
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:
If there is extra space, the data browser gives as much of the extra space as possible to the first column (that is, the leftmost column) without exceeding the maximum width for the column. If there is still space available, the data browser gives as much of the remaining space as possible to the second column without exceeding the maximum width for the column. The data browser continues to disburse space in this manner until there is no more extra space. Thus, it is possible for the first column to get all the extra space.
If space is needed to fit all the columns, the data browser takes as much of the needed space as possible from the rightmost column (that is, the last column) without letting the column width fall below the minimum width for the column. If more space is needed, the data browser takes as much of the needed space as possible from the next-to-the-last column without letting the column width fall below the minimum width for the column. The data browser continues to adjust space in this manner until all the columns fit within the data browser.
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.
HIDataBrowser.hCreates an AXUIElementRef that represents some part of a data browser accessibility hierarchy.
AXUIElementRef AXUIElementCreateWithDataBrowserAndItemInfo ( ControlRef inDataBrowser, const DataBrowserAccessibilityItemInfo *inInfo );
A data browser.
A DataBrowserAccessibilityItemInfo structure describing the part of the data browser for which you want to create an AXUIElementRef.
An AXUIElementRef representing the part, or NULL if an AXUIElementRef cannot be created to represent the part you specified.
HIDataBrowser.hObtains a description of the part of a data browser represented by an AXUIElementRef.
OSStatus AXUIElementGetDataBrowserItemInfo ( AXUIElementRef inElement, ControlRef inDataBrowser, UInt32 inDesiredInfoVersion, DataBrowserAccessibilityItemInfo *outInfo );
An AXUIElementRef representing part of a data browser.
A data browser.
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.
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.
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.
HIDataBrowser.h
Closes a data browser container.
OSStatus CloseDataBrowserContainer ( ControlRef browser, DataBrowserItemID container );
A data browser.
The item ID of the container you want to close.
A result code. See “Data Browser Result Codes.”
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.
HIDataBrowser.h
Copies the text being edited by the user.
OSStatus CopyDataBrowserEditText ( ControlRef browser, CFStringRef *text );
A data browser.
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.
A result code. See “Data Browser Result Codes.”
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.
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;
HIDataBrowser.h
Creates a data browser programmatically.
OSStatus CreateDataBrowserControl ( WindowRef window, const Rect *boundsRect, DataBrowserViewStyle style, ControlRef *outControl );
The window in which to place the data browser.
A pointer to a rectangle that specifies the location where you want the control to appear in the window.
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.
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.
A result code. See “Data Browser Result Codes.”
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:
Perform sorting. See DataBrowserItemCompareProcPtr.
Handle drag-and-drop behavior. See DataBrowserAddDragItemProcPtr, DataBrowserAcceptDragProcPtr, DataBrowserReceiveDragProcPtr, and DataBrowserPostProcessDragProcPtr.
Provide contextual menus. See DataBrowserGetContextualMenuProcPtr and DataBrowserSelectContextualMenuProcPtr.
Display help tags. See DataBrowserItemHelpContentProcPtr.
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:
Drawing custom content. See DataBrowserDrawItemProcPtr.
Supporting editing of custom content. See DataBrowserEditItemProcPtr. Note that editing is built-in for noncustom content.
Performing hit-testing and tracking. See DataBrowserHitTestProcPtr and DataBrowserTrackingProcPtr.
Handling drag-and-drop behavior. See DataBrowserItemDragRgnProcPtr, DataBrowserItemAcceptDragProcPtr, and DataBrowserItemReceiveDragProcPtr.
HIDataBrowser.h
Sets the attributes for a data browser.
OSStatus DataBrowserChangeAttributes ( ControlRef inDataBrowser, OptionBits inAttributesToSet, OptionBits inAttributesToClear );
A data browser.
The attributes to set. For possible values, see “Data Browser Attributes.”
The attributes to clear. For possible values, see “Data Browser Attributes.”
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Gets the attributes of a data browser.
OSStatus DataBrowserGetAttributes ( ControlRef inDataBrowser, OptionBits *outAttributes );
A data browser.
The attributes to get. This parameter cannot be NULL. For possible values, see “Data Browser Attributes.”
A result code. See “Data Browser Result Codes.”
HIDataBrowser.hGets the value of a specified data browser metric.
OSStatus DataBrowserGetMetric ( ControlRef inDataBrowser, DataBrowserMetric inMetric, Boolean *outUsingDefaultValue, CGFloat *outValue );
A data browser.
The data browser metric value to get. For possible values, see“Data Browser Metric Values.”
On return, a Boolean whose value indicates whether the metric’s value is determined by the data browser’s default values. Pass NULL if you don’t want this information.
On return, the value of the metric.
A result code. See “Data Browser Result Codes.” If the inDataBrowser is not an instance of a data browser or if the value specified by inMetric is not known, DataBrowserGetMetric returns paramErr.
HIDataBrowser.hSets the value of a specified data browser metric.
OSStatus DataBrowserSetMetric ( ControlRef inDataBrowser, DataBrowserMetric inMetric, Boolean inUseDefaultValue, CGFloat inValue );
A data browser.
The data browser metric whose value is to be set. For possible values, see “Data Browser Metric Values.”
A Boolean whose value indicates whether you want the data browser to revert to the default value for the metric. If you pass true, inValue is ignored and a suitable default value is used. If you pass false, inValue is set as the value of the metric.
The value to set for the metric (if the value of inUsingDefaultValue is false).
A result code. See “Data Browser Result Codes.” If the inDataBrowser is not an instance of a data browser or if the value specified by inMetric is not known, DataBrowserSetMetric returns paramErr.
HIDataBrowser.h
Disposes of a universal procedure pointer to an accept-drag callback function.
void DisposeDataBrowserAcceptDragUPP ( DataBrowserAcceptDragUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserAcceptDragProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an add-drag-item callback function.
void DisposeDataBrowserAddDragItemUPP ( DataBrowserAddDragItemUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserAddDragItemProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a draw-item callback function.
void DisposeDataBrowserDrawItemUPP ( DataBrowserDrawItemUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserDrawItemProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an edit-item callback function.
void DisposeDataBrowserEditItemUPP ( DataBrowserEditItemUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserEditItemProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a get-contextual-menu callback function.
void DisposeDataBrowserGetContextualMenuUPP ( DataBrowserGetContextualMenuUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserGetContextualMenuProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a hit-test callback function.
void DisposeDataBrowserHitTestUPP ( DataBrowserHitTestUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserHitTestProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-accept-drag callback function.
void DisposeDataBrowserItemAcceptDragUPP ( DataBrowserItemAcceptDragUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemAcceptDragProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-comparison callback function.
void DisposeDataBrowserItemCompareUPP ( DataBrowserItemCompareUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemCompareProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-data callback function.
void DisposeDataBrowserItemDataUPP ( DataBrowserItemDataUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemDataProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-drag-region callback function.
void DisposeDataBrowserItemDragRgnUPP ( DataBrowserItemDragRgnUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemDragRgnProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-help-content callback function.
void DisposeDataBrowserItemHelpContentUPP ( DataBrowserItemHelpContentUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemHelpContentProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-notification callback function.
void DisposeDataBrowserItemNotificationUPP ( DataBrowserItemNotificationUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemNotificationProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-notification-with-data callback function.
void DisposeDataBrowserItemNotificationWithItemUPP ( DataBrowserItemNotificationWithItemUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemNotificationWithItemProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-receive-drag callback function.
void DisposeDataBrowserItemReceiveDragUPP ( DataBrowserItemReceiveDragUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemReceiveDragProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to an item-iterator callback function.
void DisposeDataBrowserItemUPP ( DataBrowserItemUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserItemProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a postprocess-drag callback function.
void DisposeDataBrowserPostProcessDragUPP ( DataBrowserPostProcessDragUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserPostProcessDragProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a receive-drag callback function.
void DisposeDataBrowserReceiveDragUPP ( DataBrowserReceiveDragUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserReceiveDragProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a select-contextual-menu callback function.
void DisposeDataBrowserSelectContextualMenuUPP ( DataBrowserSelectContextualMenuUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserSelectContextualMenuProcPtr callback function.
HIDataBrowser.h
Disposes of a universal procedure pointer to a tracking callback function.
void DisposeDataBrowserTrackingUPP ( DataBrowserTrackingUPP userUPP );
The universal procedure pointer to dispose of.
See the DataBrowserTrackingProcPtr callback function.
HIDataBrowser.h
Determines whether the data browser is currently able to process a given editing command.
Boolean EnableDataBrowserEditCommand ( ControlRef browser, DataBrowserEditCommand command );
A data browser.
The editing command you want to enable. You can pass any of the constants described in “Editing Commands.”
A value of true if the requested editing command can be performed by the data browser at this time.
Editing commands (Cut, Paste, Copy, and so on) can be enabled for an editable text field that is open and selected and for which the data browser is currently able to process the given command. For example, the data browser can process a Paste command only if there is text available on the Clipboard.
Editing commands are also available for a custom display type when the callbacks you install for the custom display indicate editing is available. Your application can call the function EnableDataBrowserEditCommand to discover if a specific editing command can be enabled. To execute an editing command, call the function ExecuteDataBrowserEditCommand.
HIDataBrowser.h
Executes an editing command.
OSStatus ExecuteDataBrowserEditCommand ( ControlRef browser, DataBrowserEditCommand command );
A data browser.
The editing command you want to execute. You can pass any of the constants described in “Editing Commands.”
A result code. See “Data Browser Result Codes.”
Editing commands can be executed for an editable text field that is open and selected. Your application can check to see if the editing command is enabled by first calling the function EnableDataBrowserEditCommand.
HIDataBrowser.h
Applies an item-iterator callback routine to each data item that meets the specified criteria.
OSStatus ForEachDataBrowserItem ( ControlRef browser, DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, DataBrowserItemUPP callback, void *clientData );
A data browser.
An item ID or the constant kDataBrowserNoItem. To iterate through items that are organized as subitems of a container item, pass the item ID for the container. To iterate through all items displayed at the root of the data browser, pass the constant kDataBrowserNoItem.
A value that indicates whether or not to traverse the entire item hierarchy when applying the callback specified by the callback parameter. Pass true to apply the callback to all items in the hierarchy. Pass false if you want to apply the callback only to those items at the top level of the container or data browser.
A value that specifies the state of the items to which to apply the callback. Pass 0 if you want to apply the callback to all items, regardless of state. Otherwise, pass one of the constants described in “Item States.”
A universal procedure pointer to your item-iterator callback routine. This routine is called for every item ID that matches the specified criteria. See DataBrowserItemProcPtr for more information on the callback routine to supply.
A pointer to a buffer, local variable, or other storage location created and disposed of by your application and needed by your callback routine.
A result code. See “Data Browser Result Codes.”
The function ForEachDataBrowserItem is useful for enumerating and performing an operation on a set of item IDs.
HIDataBrowser.h
Obtains what determines the active state of the items in a data browser.
OSStatus GetDataBrowserActiveItems ( ControlRef browser, Boolean *active );
A data browser.
On input, a pointer to a Boolean variable. On return, the variable is set to true if the active state of each item in the list is determined by the item property kDataBrowserItemIsActiveProperty. Otherwise, the variable is set to false to indicate that all items are inactive.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the callback routines installed for notifying your application of changes to a data browser and for providing the data to be displayed by the data browser.
OSStatus GetDataBrowserCallbacks ( ControlRef browser, DataBrowserCallbacks *callbacks );
The data browser whose callback routines you want to obtain.
On input, a pointer to a DataBrowserCallbacks structure. On return, the structure contains universal procedure pointers to the callback routines installed for the data browser.
A result code. See “Data Browser Result Codes.”
When GetDataBrowserCallacks is used in conjunction with the function SetDataBrowserCallbacks, your application can override or replace one or more callbacks used by a data browser to notify your application of changes.
HIDataBrowser.h
Obtains the display type for a column view.
OSStatus GetDataBrowserColumnViewDisplayType ( ControlRef browser, DataBrowserPropertyType *propertyType );
A data browser.
On input, a pointer to a display type variable. On return, the variable is set to the data type or control that is displayed in the data browser. No display types other than kDataBrowserIconAndTextType are currently supported in column view. See “Display Types” for more information.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the current path for a selection in column view.
OSStatus GetDataBrowserColumnViewPath ( ControlRef browser, Handle path );
A data browser.
On input, a handle. On return, the handle contains an array of item ID values that specify the current path. Array element 0 is the root; array element N-1 is the target. You must allocate the handle before calling this function, and you are responsible for disposing of it.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the length of the current path for a column view.
OSStatus GetDataBrowserColumnViewPathLength ( ControlRef browser, UInt32 *pathLength );
A data browser.
On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the number of levels in the path for the currently selected item.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the callbacks installed to implement custom drawing and behavior for the content in a data browser.
OSStatus GetDataBrowserCustomCallbacks ( ControlRef browser, DataBrowserCustomCallbacks *callbacks );
A data browser.
On input, a pointer to a DataBrowserCustomCallbacks structure. On return, the structure contains universal procedure pointers to the custom callback routines installed for the data browser.
A result code. See “Data Browser Result Codes.”
When GetDataBrowserCustomCallbacks is used in conjunction with the function SetDataBrowserCustomCallbacks, your application can temporarily override or replace one or more callbacks used by a data browser to support custom drawing and custom behavior.
HIDataBrowser.h
Obtains the item ID and property ID values of the current editing session.
OSStatus GetDataBrowserEditItem ( ControlRef browser, DataBrowserItemID *item, DataBrowserPropertyID *property );
A data browser.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID of the item that is being edited. If there is no editing session in progress, this parameter is set to kDataBrowserNoItem.
On input, a pointer to a property ID variable. On return, the variable is set to the property ID of the item that is being edited. If there is no editing session in progress, this parameter is set to 0.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the text being edited by the user.
Not Recommended
OSStatus GetDataBrowserEditText ( ControlRef browser, CFMutableStringRef text );
A data browser.
On return, the CFMutableString object is set to the text being edited by the user. Your application must allocate this object and pass it to the data browser. The data browser sets its contents to the current contents of the edit session text field. You must release this object when you no longer need it.
A result code. See “Data Browser Result Codes.”
This function does not work. Instead use CopyDataBrowserEditText.
HIDataBrowser.h
Obtains the display state of horizontal and vertical scroll bars for a list view data browser.
OSStatus GetDataBrowserHasScrollBars ( ControlRef browser, Boolean *horiz, Boolean *vert );
A list view data browser.
On input, a pointer to a Boolean variable. On return, the variable is set to true if the browser control has a horizontal scroll bar.
On input, a pointer to a Boolean variable. On return, the variable is set to true if the browser control has a vertical scroll bar.
A result code. See “Data Browser Result Codes.”
The function GetDataBrowserHasScrollBars is useful for determining if the browser control currently has scroll bars. For example, you would call the function AutoSizeDataBrowserListViewColumns only after you have determined the data browser does not have a horizontal scroll bar.
HIDataBrowser.h
Obtains the number of items whose state matches the specified state.
OSStatus GetDataBrowserItemCount ( ControlRef browser, DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, ItemCount *numItems );
A data browser.
An item ID or the constant kDataBrowserNoItem. To obtain the number of items that are organized as subitems of a container item, pass the item ID for the container. To obtain the number of items displayed at the root of the data browser, provide the constant kDataBrowserNoItem.
A value that indicates whether or not to traverse the entire item hierarchy when counting. Pass true to obtain a count for all items in the hierarchy. Pass false if you want to count only those items at the top level of the container or data browser.
A value that specifies the state of the items to obtain. Only items that have this state are counted. Pass kDataBrowserItemAnyState if you want to count all items regardless of state. Otherwise, pass one of the constants described in “Item States”.
On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the number of items in the container that have the specified state.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the Boolean value for an item.
OSStatus GetDataBrowserItemDataBooleanValue ( DataBrowserItemDataRef itemData, Boolean *theData );
The item data reference for the item whose Boolean value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataBooleanValue.
On input, a pointer to a Boolean variable. On return, the variable is set to the Boolean value.
A result code. See “Data Browser Result Codes.”
You can obtain Boolean values for the following properties:
kDataBrowserItemIsActiveProperty
kDataBrowserItemIsSelectableProperty
kDataBrowserItemIsEditableProperty
kDataBrowserItemIsContainerProperty
kDataBrowserItemIsOpenableProperty
kDataBrowserItemIsClosableProperty
kDataBrowserItemIsSortableProperty
HIDataBrowser.h
Obtains the value for a checkbox.
OSStatus GetDataBrowserItemDataButtonValue ( DataBrowserItemDataRef itemData, ThemeButtonValue *theData );
The item data reference for the item whose checkbox setting you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataButtonValue.
On input, a pointer to a theme button value variable. On return, the variable is set to the checkbox setting. The value can be one of the following theme button value constants defined by the Appearance Manager,:
kThemeButtonOff indicates a checkbox that is not selected.
kThemeButtonOn indicates a checkbox that is selected.
kThemeButtonMixed draws a checkbox that in a mixed state, indicating that a setting is on for some items in a selection and off for others.
See Appearance Manager Reference for more information.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a set-data request for items that have the display type kDataBrowserCheckboxType.
HIDataBrowser.h
Obtains, as a 32-bit value, the date and time value displayed.
OSStatus GetDataBrowserItemDataDateTime ( DataBrowserItemDataRef itemData, SInt32 *theData );
The item data reference for the item whose date and time value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataDateTime.
On input, a 32-bit value. On return, the value is set to the number of elapsed seconds since midnight, January 1, 1904. For more information about date and time encodings used in the Mac OS, see Date, Time, and Measurement Utilities Reference in Carbon Text & International Documentation.
A result code. See “Data Browser Result Codes.”
This function works only with items that have the property kDataBrowserDateTimeType. If the column has the property kDataBrowserRelativeDateTime, the date is displayed relative to the current time for the computer. For example, a time 24 hours prior to the current time is displayed as “Yesterday.” Other examples of relative date and time values are “Today, 1:45 PM” and “Yesterday, 7:30 AM.”
HIDataBrowser.h
Determines whether a checkbox is in the active or inactive state.
OSStatus GetDataBrowserItemDataDrawState ( DataBrowserItemDataRef itemData, ThemeDrawState *theData );
The item data reference for the checkbox whose drawing state you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataDrawState.
On input, a pointer to a theme draw state variable. On return, the variable is set to the drawing state for the item, either kThemeStateInactive or kThemeStateActive. See Appearance Manager Reference for more information on these constants.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a get-data request for items that have display type kDataBrowserCheckboxType.
HIDataBrowser.h
Obtains the icon drawn for an item.
OSStatus GetDataBrowserItemDataIcon ( DataBrowserItemDataRef itemData, IconRef *theData );
The item data reference for the item whose icon you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataIcon.
On input, a pointer to an IconRef variable. On return, the variable is set to the icon that is displayed. You are responsible for disposing of the IconRef.
A result code. See “Data Browser Result Codes.”
You call the function GetDataBrowserItemDataIcon from within a DataBrowserItemDataProcPtr callback routine to obtain the icon drawn in a column that has the kDataBrowserIconType display type or the kDataBrowserIconAndTextType display type.
HIDataBrowser.h
Obtains the transformation currently used to display an icon.
OSStatus GetDataBrowserItemDataIconTransform ( DataBrowserItemDataRef itemData, IconTransformType *theData );
The item data reference for the item whose icon transformation you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataIconTransform.
On input, an icon transformation type variable. On return, the variable is set to an icon transformation type. This value can be any of the icon transformation constants defined by Icon Services and Utilities. See Icon Services and Utilities Reference for more information.
A result code. See “Data Browser Result Codes.”
This function works only with items that have either the property kDataBrowserIconAndTextType or kDataBrowserIconType.
HIDataBrowser.h
Obtains the item ID for an item whose property is another item’s ID.
OSStatus GetDataBrowserItemDataItemID ( DataBrowserItemDataRef itemData, DataBrowserItemID *theData );
The item data reference passed to your item-data callback.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID associated with the itemData parameter.
A result code. See “Data Browser Result Codes.”
Typically you do not need to call this function. This function is used for item properties kDataBrowserParentContainerProperty or kDataBrowserContainerAliasIDProperty.
HIDataBrowser.h
Obtains, as a 64-bit value, the date and time value displayed.
OSStatus GetDataBrowserItemDataLongDateTime ( DataBrowserItemDataRef itemData, LongDateTime *theData );
The item data reference for the item whose long date and time value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataLongDateTime.
On input, a 64-bit value. On return, the value is set to the number of seconds elapsed since midnight, January 1, 1904. For more information about date and time encodings used in the Mac OS, see Date, Time, and Measurement Utilities Reference in Carbon Text & International Documentation.
A result code. See “Data Browser Result Codes.”
This function works only with items that have the property kDataBrowserDateTimeType. If the column has the property kDataBrowserRelativeDateTime, the date is displayed relative to the current time for the computer. For example, a time 24 hours prior to the current time is displayed as “Yesterday.” Other examples of relative date and time values are “Today, 1:45 PM” and “Yesterday, 7:30 AM.”
HIDataBrowser.h
Obtains the maximum integer value that can be displayed; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus GetDataBrowserItemDataMaximum ( DataBrowserItemDataRef itemData, SInt32 *theData );
The item data reference for the item whose maximum value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataMaximum.
On input, a pointer to a signed 32-bit integer. On return, this value is set to the maximum value that can be displayed for the item.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the pop-up menu displayed.
OSStatus GetDataBrowserItemDataMenuRef ( DataBrowserItemDataRef itemData, MenuRef *theData );
The item data reference for the item whose pop-up menu you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataMenuRef.
On input, a pointer to a menu reference. On return, this is set to the currently displayed pop-up menu. The system retains the menu reference that you pass; you must release it when you no longer need it.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a get-data request for items that have the display type kDataBrowserPopupMenuType.
HIDataBrowser.h
Obtains the minimum integer value that can be displayed for an item; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus GetDataBrowserItemDataMinimum ( DataBrowserItemDataRef itemData, SInt32 *theData );
The item data reference for the item whose minimum value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataMinimum.
On input, a pointer to a signed 32-bit integer. On return, this value is set to the minimum value that can be displayed for the item.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the column property ID for the column in which an item resides.
OSStatus GetDataBrowserItemDataProperty ( DataBrowserItemDataRef itemData, DataBrowserPropertyID *theData );
The item data reference for the item whose property ID you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataProperty.
On input, a pointer to a property ID variable. On return, the variable is set to the property ID for the item.
A result code. See “Data Browser Result Codes.”
When your item-data callback is invoked for an item that has the property kDataBrowserItemIsEditableProperty, you call the function GetDataBrowserItemDataProperty to obtain the column property ID. Then, your callback can use the column property ID to determine whether the item is in a column whose data can be edited.
For example, consider a list view data browser whose columns are titled “Name” and “Date Modified.” Let’s say Name can be modified by the user, but the Date Modified column cannot. If the user clicks an item in one of the columns, your item-data callback is called to find out whether the clicked column is editable. Your callback needs to find out which column the “is editable” request is being made for by calling the function GetDataBrowserItemDataProperty. In this example, after you obtain the property ID, you would check whether the column is the Date Modified column or the Name column. You’d allow editing only if the item is in the Name column.
HIDataBrowser.h
Obtains the color used to draw an item.
OSStatus GetDataBrowserItemDataRGBColor ( DataBrowserItemDataRef itemData, RGBColor *theData );
The item data reference for the item whose color you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataRGBColor.
On input, an RGB color variable. On return, the variable is set to the RGB values that specify the color of the item.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a get-data request for items that have the display type kDataBrowserIconType or kDataBrowserIconAndTextType.
As of Mac OS X 10.3, this function does nothing.
HIDataBrowser.h
Obtains the text entered by the user.
OSStatus GetDataBrowserItemDataText ( DataBrowserItemDataRef itemData, CFStringRef *theData );
The item data reference for the item whose text you want to obtain. This value is passed to the callback routine from which you are calling the function GetDataBrowserItemDataText.
On input, a CFStringRef variable. On return, a CFString object that contains the text. Your application must release the CFString object when it is no longer needed.
A result code. See “Data Browser Result Codes.”
You can call the function GetDataBrowserItemDataText from inside an item-data callback routine when the callback’s setValue parameter is true. A value of true indicates that the displayed text has been modified by the user. In that case, your application calls GetDataBrowserItemDataText to retrieve the modified text.
Note that a column is editable only if the kDataBrowserPropertyIsEditable flag is set for the column.
HIDataBrowser.h
Obtains the value of an item; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus GetDataBrowserItemDataValue ( DataBrowserItemDataRef itemData, SInt32 *theData );
The item data reference for the item whose integer value you want to obtain. The item data reference is passed to the callback routine from which you are calling the function GetDataBrowserItemDataValue.
On input, a pointer to a signed 32-bit integer. On return, it is set to the displayed value.
A result code. See “Data Browser Result Codes.”
Your application calls the function GetDataBrowserItemDataValue to obtain a new value for a display type when your item-data callback routine is called with the setValue parameter set to true.
HIDataBrowser.h
Obtains the bounds of a visual part of an item.
OSStatus GetDataBrowserItemPartBounds ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserPropertyPart part, Rect *bounds );
A data browser.
The item ID that identifies the row.
The property ID that identifies the column.
The part for which you want to obtain information. The information requested depends on the type of information displayed in the column. It is up to your application to ensure it requests the appropriate information. See “Property Parts” for a list of the constants you can provide in this parameter.
On input, a pointer to a rectangle. On return, the rectangle contains the bounds for the specified part.
A result code. If the item is not visible (scrolled off the screen), returns the result ItemNotFound. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains a list of the items that match a specified state; operates on items in the root container or traverses items in the data hierarchy.
OSStatus GetDataBrowserItems ( ControlRef browser, DataBrowserItemID container, Boolean recurse, DataBrowserItemState state, Handle items );
A data browser.
An item ID or the constant kDataBrowserNoItem. To obtain a list of items that are organized as subitems of a container, pass the item ID of the container item. To obtain a list of items displayed in the root container, pass the constant kDataBrowserNoItem.
A value that indicates whether or not to traverse the entire item hierarchy when obtaining item IDs. Pass true to obtain item IDs for all items in the hierarchy. Pass false if you want to count only those item IDs at the top level of the container. If you pass true, you obtain a flattened list of item IDs. The list reflects the hierarchy maintained internally by the data browser and might not reflect the order of the items as they appear onscreen to the user.
The state of the items to obtain. Only items that have this state are returned in the items parameter. Pass 0 if you want to obtain all items regardless of state. Otherwise, pass one of the constants described in “Item States.”
On return, the contents of the handle contain an array of item ID values for the matching items. You must allocate and dispose of the handle. To determine the number of items in the array, call the function GetHandleSize and divide by the size of DataBrowserItemID. Note that the handle contents are completely replaced by the returned array.
A result code. See “Data Browser Result Codes.”
The function GetDataBrowserItems is a powerful routine for gathering information about the items displayed in a data browser. For example, to obtain a list of all the items the user has selected in a list, call the function with the state parameter set to kDataBrowserItemIsSelected. If your application is interested only in determining the number of items in a selection (and not the item IDs of those items), call the function GetDataBrowserItemCount.
HIDataBrowser.h
Obtains the state of an item.
OSStatus GetDataBrowserItemState ( ControlRef browser, DataBrowserItemID item, DataBrowserItemState *state );
A data browser.
The item ID of the item whose state you want to check.
On input, a pointer to an item state variable. On return, the variable is set to a value that specifies the state of the item. See “Item States” for a description of the values that can be returned.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the property ID of the column whose items can display a disclosure triangle, and tells whether a disclosed item expands the row or adds rows.
OSStatus GetDataBrowserListViewDisclosureColumn ( ControlRef browser, DataBrowserTableViewColumnID *column, Boolean *expandableRows );
A data browser.
On input, a pointer to a column ID variable. On return, the variable is set to the property ID of the currently selected column. If there is no disclosure column, the variable is set to kDataBrowserItemNoProperty. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
On input, a pointer to a Boolean variable. On return, the variable specifies how a disclosed row behaves. The value true means that a container opens as a single row with an expanded height. The value false means a container opens to expose individual rows. See the Discussion for more details on expandable rows.
A result code. See “Data Browser Result Codes.”
When the expandableRows variable is set to true:
Disclosure triangles are drawn top-justified in the row.
Custom row height, if any, for that row is respected only while the row is disclosed. At other times, the default row height is used.
When the expandableRows variable is set to false:
Disclosure triangles are centered vertically in the row.
Custom row height, if any, for that row is always respected.
HIDataBrowser.h
Obtains the height of the rectangular area where the column title appears.
OSStatus GetDataBrowserListViewHeaderBtnHeight ( ControlRef browser, UInt16 *height );
A data browser.
On input, a pointer to an unsigned 16-bit integer. On return, this value is set to the height of the rectangular area where the column title appears. You can save this value if you plan to call the function SetDataBrowserListViewHeaderBtnHeight to turn off header button display. You can then use the value later to turn on header button display.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains a header description for a column in list view.
OSStatus GetDataBrowserListViewHeaderDesc ( ControlRef browser, DataBrowserTableViewColumnID column, DataBrowserListViewHeaderDesc *desc );
A data browser.
The property ID for the column whose list view header description you want to obtain. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
On input, a pointer to a list view header description data structure. On return, the structure contains the header description for the specified column in list view.
A result code. See “Data Browser Result Codes.”
If your application allows the user to switch between column and list views, you can call this function to obtain the current header description and then save the description before you switch from list to column view. When you switch from column to list view, you can restore the list view header information by calling the function SetDataBrowserListViewHeaderDesc passing the header information you saved.
HIDataBrowser.h
Determines whether list view is set to use a plain white background.
OSStatus GetDataBrowserListViewUsePlainBackground ( ControlRef browser, Boolean *usePlainBackground );
A data browser.
On input, a pointer to a Boolean variable. On return, the variable is true if list view is set to use a plain white background. Regardless of the value that is returned, Mac OS X supports only a plain white background. Mac OS 9 supports a plain white background as well as a shaded background.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the appearance and behavior attributes for a column.
OSStatus GetDataBrowserPropertyFlags ( ControlRef browser, DataBrowserPropertyID property, DataBrowserPropertyFlags *flags );
A data browser.
The property ID of the column whose properties you want to obtain.
On input, a data browser property flags variable. On return, the variable is set to the property flags that specify the appearance and behavior attributes for a column. A DataBrowserPropertyFlags value is a 32-bit value that is divided into four parts as follows:
Bits 0–7 specify properties applied to the data browser as a whole—see “Property Flags: Universal”
Bits 8–15 modify display behavior—see “Property Flags: Modifiers”
Bits 16–23 are properties specific to list view—see “Property Flags: Offset and Mask for List View Properties” and “Property Flags: List View Column Behavior”
Bits 24–31 can be defined by your application—see “Property Flags: Offset and Mask for Client-Defined Properties”
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the inset rectangle used by a data browser to position the scroll bar.
OSStatus GetDataBrowserScrollBarInset ( ControlRef browser, Rect *insetRect );
A data browser.
On input, a pointer to a rectangle structure. On return, the rectangle contains the current inset settings for the data browser scroll bars. The left and right fields contain the horizontal inset values for the horizontal scroll bar, and the top and bottom fields contain the vertical inset values for the vertical scroll bar.
A result code. See “Data Browser Result Codes.”
Your application can call the functions GetDataBrowserScrollBarInset and SetDataBrowserScrollBarInset if you want to place placards or controls beside the horizontal scroll bars or above the vertical ones. To do so, first call GetDataBrowserScrollBarInset to obtain the current settings. After modifying the current inset settings to provide space for the placard or control, call SetDataBrowserScrollBarInset with the new values.
HIDataBrowser.h
Obtains the scrolling position of a list.
OSStatus GetDataBrowserScrollPosition ( ControlRef browser, UInt32 *top, UInt32 *left );
A data browser.
On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the current vertical scrolling position.
On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the current horizontal scrolling position.
A result code. See “Data Browser Result Codes.”
Normally, you use the function GetDataBrowserScrollPosition in conjunction with SetDataBrowserScrollPosition to save and restore the scrolling position of a list to the user’s last scrolling position. These functions should not be used to scroll particular cells into the view. For that, call the function RevealDataBrowserItem.
HIDataBrowser.h
Obtains the first and last items in a selection.
OSStatus GetDataBrowserSelectionAnchor ( ControlRef browser, DataBrowserItemID *first, DataBrowserItemID *last );
A data browser.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID of the first item in the selection.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID of the last item in the selection.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the current selection behavior for a data browser.
OSStatus GetDataBrowserSelectionFlags ( ControlRef browser, DataBrowserSelectionFlags *selectionFlags );
A data browser.
On input, a data browser selection flags variable. On return, the variable is set to the current selection flags. See “User Selection Flags” for a list of the flags that can be returned.
A result code. See “Data Browser Result Codes.”
Selection flags specify the selection behavior available to the user, such as whether the user can select discontinuous items.
HIDataBrowser.h
Gets the sorting order of the list view column that’s currently set for sorting.
OSStatus GetDataBrowserSortOrder ( ControlRef browser, DataBrowserSortOrder *order );
A data browser.
On input, a pointer to a sorting order variable. On return, the variable is set to the sorting order of the current sort column in list view. See “Sorting Orders” for a list of the values that can be returned.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the property ID of the column currently used for sorting in list view.
OSStatus GetDataBrowserSortProperty ( ControlRef browser, DataBrowserPropertyID *property );
A data browser.
On input, a pointer to a property ID variable. On return, the variable is set to the property ID of the column used for sorting.
A result code. See “Data Browser Result Codes.”
You can call the function GetDataBrowserSortProperty to discover the property ID of the column currently used for sorting. To designate another column for the sorting operation, call the function SetDataBrowserSortProperty.
HIDataBrowser.h
Obtains the number of columns in a data browser.
OSStatus GetDataBrowserTableViewColumnCount ( ControlRef browser, UInt32 *numColumns );
A data browser.
On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the number of columns in the data browser.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the column position for an item in a data browser.
OSStatus GetDataBrowserTableViewColumnPosition ( ControlRef browser, DataBrowserTableViewColumnID column, DataBrowserTableViewColumnIndex *position );
A data browser.
The property ID for the list view column for which you want to obtain the position. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
On input, a pointer to a column index variable. On return, the variable is set to the column index for the item; 0 is the leftmost column.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the property ID for a column in a data browser.
OSStatus GetDataBrowserTableViewColumnProperty ( ControlRef browser, DataBrowserTableViewColumnIndex column, DataBrowserTableViewColumnID *property );
A data browser.
The column index of the column whose property ID you want to obtain.
On input, a pointer to a column ID variable. On return, the variable is set to the property ID for the column. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the default column width used for all columns in a data browser.
OSStatus GetDataBrowserTableViewColumnWidth ( ControlRef browser, UInt16 *width );
A data browser.
On input, a pointer to an unsigned 16-bit integer. On return, this value is set to the column width, in pixels.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Determines whether columns and rows are set to have variable widths.
OSStatus GetDataBrowserTableViewGeometry ( ControlRef browser, Boolean *variableWidthColumns, Boolean *variableHeightRows );
A data browser.
On input, a pointer to a Boolean variable. On return, the variable is set to true if column widths can be changed or false if they cannot be changed.
On input, a pointer to a Boolean variable. On return, the variable is set to true if row heights can be changed or false if they cannot be changed.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the highlighting style used for a list view data browser.
OSStatus GetDataBrowserTableViewHiliteStyle ( ControlRef browser, DataBrowserTableViewHiliteStyle *hiliteStyle );
A list view data browser.
On input, a pointer to a highlighting style variable. On return, the variable is set to the highlighting style in use. See “Table View Highlighting Styles” for a description of the values that can be returned.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the item ID for the item displayed in the specified row.
OSStatus GetDataBrowserTableViewItemID ( ControlRef browser, DataBrowserTableViewRowIndex row, DataBrowserItemID *item );
A data browser.
The row index for the item. The row index is the visual order of rows in the table onscreen. Rows are numbered starting at the top of the table, with the value 0, and proceeding sequentially to the bottom of the table.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID of the data displayed in the row.
A result code. See “Data Browser Result Codes.”
This function is useful only in edge case situations for which you need to know what item ID is displayed in a particular row. For example, if you are performing some fairly involved and complex custom hit-testing, you might need to call this function.
HIDataBrowser.h
Obtains the visual position for the specified item in list view.
OSStatus GetDataBrowserTableViewItemRow ( ControlRef browser, DataBrowserItemID item, DataBrowserTableViewRowIndex *row );
A data browser.
The item ID for the item whose row index you want to obtain.
On input, a pointer to a row index variable. On return, the variable is set to the row index for the item.
A result code. See “Data Browser Result Codes.”
You can use this function for items in list view. It is the inverse of the function GetDataBrowserTableViewItemID.
HIDataBrowser.h
Obtains the row height for a single row in a list view data browser.
OSStatus GetDataBrowserTableViewItemRowHeight ( ControlRef browser, DataBrowserItemID item, UInt16 *height );
A data browser.
The item ID of the item whose row height you want to obtain.
On input, a pointer to an unsigned 16-bit integer. On return, this value is set to the row height, in pixels.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the column width for a single column in a data browser.
OSStatus GetDataBrowserTableViewNamedColumnWidth ( ControlRef browser, DataBrowserTableViewColumnID column, UInt16 *width );
A data browser.
The property ID for the list view column whose width you want to obtain. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
On input, a pointer to an unsigned 16-bit integer. On return, this value is set to the width of the column, in pixels.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the default row height used for all rows in a data browser.
OSStatus GetDataBrowserTableViewRowHeight ( ControlRef browser, UInt16 *height );
A data browser.
On input, a pointer to an unsigned 16-bit integer. On return, this value is set to the row height, in pixels.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Obtains the target for the data browser
OSStatus GetDataBrowserTarget ( ControlRef browser, DataBrowserItemID *target );
A data browser.
On input, a pointer to an item ID variable. On return, the variable is set to the item ID for the currently assigned target.
A result code. See “Data Browser Result Codes.”
In column view, the target is the rightmost column. In list view, the target can be thought of as the root container.
Your application can call the function SetDataBrowserTarget to set an item ID to use as a target if you do not want to use the default target set by the data browser.
HIDataBrowser.h
Obtains the current view style settings for a list view.
OSStatus GetDataBrowserUserState ( ControlRef browser, CFDictionaryRef *stateInfo );
A data browser.
On input, a pointer to a CFDictionaryRef. On return, a CFDictionary object that contains the current view style settings. You must release the object when you no longer need it by calling the function CFRelease. Note that although this parameter is typed as a CFData object, you must treat the result as a CFDictionary object because that is what the system fills out and returns to you.
A result code. See “Data Browser Result Codes.”
You typically use this function to obtain the current user settings for the data browser so that you can save the settings to a preferences file. User settings include data such as sorting order, sorting column, and column widths. Later, you can restore the settings by calling the function SetDataBrowserUserState.
If you want to save the user settings to disk, you need to determine the length of the user-settings data in bytes. The following code shows how to calculate this length. First you need to convert the CFDictionary object you obtain from the function GetDataBrowserUserState to a property list. Then you can call the function CFDataGetLength to obtain the length, in bytes, of the property list.
CFDataRef myUserState = NULL; |
OSStatus status; |
ControlRef browser = GetDataBrowserFromWindow (window); |
status = GetDataBrowserUserState (browser, &myUserState); |
if (noErr == status) |
{ |
CFDataRef myTempDataRef = NULL; |
CFIndex index; |
if (myUserState != NULL) |
{ |
// Convert the user state dictionary to a property list. |
myTempDataRef = CFPropertyListCreateXMLData (NULL, |
(CFPropertyListRef) myUserState); |
if (myTempDataRef != NULL) |
{ |
// Get the length, in bytes |
index = CFDataGetLength (myTempDataRef); |
// Call your function to save the data |
// You need to release the CFDataRef you created |
CFRelease (myTempDataRef); |
} |
} |
CFRelease (myUserState); |
} |
HIDataBrowser.h
Obtains the current view style for the specified data browser.
OSStatus GetDataBrowserViewStyle ( ControlRef browser, DataBrowserViewStyle *style );
A data browser.
On input, a pointer to a view style variable. On return, the variable is set to the current view style for the specified data browser; can be either list view (kDataBrowserListView) or column view (kDataBrowserColumnView). See “View Styles” for more information on these constants.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Initializes a data browser callback structure in preparation for adding your own callbacks to the structure.
OSStatus InitDataBrowserCallbacks ( DataBrowserCallbacks *callbacks );
A pointer to a DataBrowserCallbacks structure. Before calling the function InitDataBrowserCallbacks, set the version field of this structure to kDataBrowserLatestCallbacks. On return, the fields in this structure are set to NULL.
A result code. See “Data Browser Result Codes.”
After you call this function, set the appropriate fields in the DataBrowserCallbacks structure to your callbacks. The DataBrowserCallbacks structure contains fields for the following:
DataBrowserItemNotificationProcPtr or DataBrowserItemNotificationWithItemProcPtr (Mac OS X only)
After you assign your callbacks to the appropriate field, call the function SetDataBrowserCallbacks.
Note that this is a different set of callbacks from those that are assigned to fields in the DataBrowserCustomCallbacks data structure.
HIDataBrowser.h
Initializes the data browser custom callback structure in preparation for adding your own callbacks for custom drawing or custom behavior to the structure.
OSStatus InitDataBrowserCustomCallbacks ( DataBrowserCustomCallbacks *callbacks );
A pointer to a DataBrowserCustomCallbacks structure. Before calling the function InitDataBrowserCustomCallbacks, set the version field of this structure to kDataBrowserLatestCustomCallbacks. On return, the fields in this structure are set to NULL.
A result code. See “Data Browser Result Codes.”
Custom callbacks refer to those callback routines that are used to implement custom drawing or custom behavior in your data browser. The data browser API supports a limited set of built-in display types: text, icon and text, checkboxes, and so forth. If you want to display something else, you install custom callbacks to perform drawing and handle user interaction.
After you call the function InitDataBrowserCustomCallbacks, set the appropriate fields in the DataBrowserCustomCallbacks structure to your callbacks. The DataBrowserCustomCallbacks structure contains fields for the following:
After you assign your custom callbacks to the appropriate field, call the function SetDataBrowserCustomCallbacks.
Note that this is a different set of callbacks from those that are assigned to fields in the DataBrowserCallbacks data structure.
HIDataBrowser.h
Calls an accept-drag callback function.
Boolean InvokeDataBrowserAcceptDragUPP ( ControlRef browser, DragReference theDrag, DataBrowserItemID item, DataBrowserAcceptDragUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserAcceptDragProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an add-drag-item callback function.
Boolean InvokeDataBrowserAddDragItemUPP ( ControlRef browser, DragReference theDrag, DataBrowserItemID item, ItemReference *itemRef, DataBrowserAddDragItemUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserAddDragItemProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a draw-item callback function.
void InvokeDataBrowserDrawItemUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserItemState itemState, const Rect *theRect, SInt16 gdDepth, Boolean colorDevice, DataBrowserDrawItemUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserDrawItemProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an edit-item callback function.
Boolean InvokeDataBrowserEditItemUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, CFStringRef theString, Rect *maxEditTextRect, Boolean *shrinkToFit, DataBrowserEditItemUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserEditItemProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a get-contextual-menu callback function.
void InvokeDataBrowserGetContextualMenuUPP ( ControlRef browser, MenuRef *menu, UInt32 *helpType, CFStringRef *helpItemString, AEDesc *selection, DataBrowserGetContextualMenuUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserGetContextualMenuProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a hit-test callback function.
Boolean InvokeDataBrowserHitTestUPP ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, const Rect *mouseRect, DataBrowserHitTestUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserHitTestProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-accept-drag callback function.
DataBrowserDragFlags InvokeDataBrowserItemAcceptDragUPP ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, DragReference theDrag, DataBrowserItemAcceptDragUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemAcceptDragProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-comparison callback function.
Boolean InvokeDataBrowserItemCompareUPP ( ControlRef browser, DataBrowserItemID itemOne, DataBrowserItemID itemTwo, DataBrowserPropertyID sortProperty, DataBrowserItemCompareUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemCompareProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-data callback function.
OSStatus InvokeDataBrowserItemDataUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserItemDataRef itemData, Boolean setValue, DataBrowserItemDataUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemDataProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-drag-region callback function.
void InvokeDataBrowserItemDragRgnUPP ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, RgnHandle dragRgn, DataBrowserItemDragRgnUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemDragRgnProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-help-content callback function.
void InvokeDataBrowserItemHelpContentUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, HMContentRequest inRequest, HMContentProvidedType *outContentProvided, HMHelpContentRec *ioHelpContent, DataBrowserItemHelpContentUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemHelpContentProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-notification callback function.
void InvokeDataBrowserItemNotificationUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserItemNotification message, DataBrowserItemNotificationUPP userUPP );
In most cases you don’t need to use this function, because the system invokes your callback function for you. See the DataBrowserItemNotificationProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-notification-with-data callback function.
void InvokeDataBrowserItemNotificationWithItemUPP ( ControlRef browser, DataBrowserItemID item, DataBrowserItemNotification message, DataBrowserItemDataRef itemData, DataBrowserItemNotificationWithItemUPP userUPP );
In most cases you don’t need to use this function, because the system invokes your callback function for you. See the DataBrowserItemNotificationWithItemProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-receive-drag callback function.
Boolean InvokeDataBrowserItemReceiveDragUPP ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, DataBrowserDragFlags dragFlags, DragReference theDrag, DataBrowserItemReceiveDragUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemReceiveDragProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls an item-iterator callback function.
void InvokeDataBrowserItemUPP ( DataBrowserItemID item, DataBrowserItemState state, void *clientData, DataBrowserItemUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserItemProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a postprocess-drag callback function.
void InvokeDataBrowserPostProcessDragUPP ( ControlRef browser, DragReference theDrag, OSStatus trackDragResult, DataBrowserPostProcessDragUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserPostProcessDragProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a receive-drag callback function.
Boolean InvokeDataBrowserReceiveDragUPP ( ControlRef browser, DragReference theDrag, DataBrowserItemID item, DataBrowserReceiveDragUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserReceiveDragProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a select-contextual-menu callback function.
void InvokeDataBrowserSelectContextualMenuUPP ( ControlRef browser, MenuRef menu, UInt32 selectionType, SInt16 menuID, MenuItemIndex menuItem, DataBrowserSelectContextualMenuUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserSelectContextualMenuProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Calls a tracking callback function.
DataBrowserTrackingResult InvokeDataBrowserTrackingUPP ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, Point startPt, EventModifiers modifiers, DataBrowserTrackingUPP userUPP );
In most cases you do not need to use this function, because the system invokes your callback function for you. See the DataBrowserTrackingProcPtr callback function for more information and for a description of the parameters.
HIDataBrowser.h
Checks to see if a data item is selected.
Boolean IsDataBrowserItemSelected ( ControlRef browser, DataBrowserItemID item );
A data browser.
The item ID of the item to check.
A value of true if the item is a member of the current selection.
HIDataBrowser.h
Moves or extends the current selection.
OSStatus MoveDataBrowserSelectionAnchor ( ControlRef browser, DataBrowserSelectionAnchorDirection direction, Boolean extendSelection );
A data browser.
The direction to move or extend the current selection. You can pass any one of the constants described in “Selection Anchor Directions.”
On input, a value that specifies whether to extend the current selection (true) or move the selection (false).
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Creates a universal procedure pointer to an accept-drag callback function.
DataBrowserAcceptDragUPP NewDataBrowserAcceptDragUPP ( DataBrowserAcceptDragProcPtr userRoutine );
A pointer to your accept-drag callback function.
The universal procedure pointer.
See the DataBrowserAcceptDragProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an add-drag-item callback function.
DataBrowserAddDragItemUPP NewDataBrowserAddDragItemUPP ( DataBrowserAddDragItemProcPtr userRoutine );
A pointer to your add-drag-item callback function.
The universal procedure pointer.
See the DataBrowserAddDragItemProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a draw-item callback function.
DataBrowserDrawItemUPP NewDataBrowserDrawItemUPP ( DataBrowserDrawItemProcPtr userRoutine );
A pointer to your draw-item callback function.
The universal procedure pointer.
See the DataBrowserDrawItemProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an edit-item callback function.
DataBrowserEditItemUPP NewDataBrowserEditItemUPP ( DataBrowserEditItemProcPtr userRoutine );
A pointer to your edit-item callback function.
The universal procedure pointer.
See the DataBrowserEditItemProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a get-contextual-menu callback function.
DataBrowserGetContextualMenuUPP NewDataBrowserGetContextualMenuUPP ( DataBrowserGetContextualMenuProcPtr userRoutine );
A pointer to your get-contextual-menu callback function.
The universal procedure pointer.
See the DataBrowserGetContextualMenuProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a hit-test callback function.
DataBrowserHitTestUPP NewDataBrowserHitTestUPP ( DataBrowserHitTestProcPtr userRoutine );
A pointer to your hit-test callback function.
The universal procedure pointer.
See the DataBrowserHitTestProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-accept-drag callback function.
DataBrowserItemAcceptDragUPP NewDataBrowserItemAcceptDragUPP ( DataBrowserItemAcceptDragProcPtr userRoutine );
A pointer to your item-accept-drag callback function.
The universal procedure pointer.
See the DataBrowserItemAcceptDragProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-comparison callback function.
DataBrowserItemCompareUPP NewDataBrowserItemCompareUPP ( DataBrowserItemCompareProcPtr userRoutine );
A pointer to your item-comparison callback function.
The universal procedure pointer.
See the DataBrowserItemCompareProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-data callback function.
DataBrowserItemDataUPP NewDataBrowserItemDataUPP ( DataBrowserItemDataProcPtr userRoutine );
A pointer to your item-data callback function.
The universal procedure pointer.
See the DataBrowserItemDataProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-drag-region callback function.
DataBrowserItemDragRgnUPP NewDataBrowserItemDragRgnUPP ( DataBrowserItemDragRgnProcPtr userRoutine );
A pointer to your item-drag-region callback function.
The universal procedure pointer.
See the DataBrowserItemDragRgnProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-help-content callback function.
DataBrowserItemHelpContentUPP NewDataBrowserItemHelpContentUPP ( DataBrowserItemHelpContentProcPtr userRoutine );
A pointer to your item-help-content callback function.
The universal procedure pointer.
See the DataBrowserItemHelpContentProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-notification callback function.
DataBrowserItemNotificationUPP NewDataBrowserItemNotificationUPP ( DataBrowserItemNotificationProcPtr userRoutine );
A pointer to your item-notification callback function.
The universal procedure pointer.
See the DataBrowserItemNotificationProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-notification-with-data callback function.
DataBrowserItemNotificationWithItemUPP NewDataBrowserItemNotificationWithItemUPP ( DataBrowserItemNotificationWithItemProcPtr userRoutine );
A pointer to your item-notification-with-data callback function.
The universal procedure pointer.
See the DataBrowserItemNotificationWithItemProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-receive-drag callback function.
DataBrowserItemReceiveDragUPP NewDataBrowserItemReceiveDragUPP ( DataBrowserItemReceiveDragProcPtr userRoutine );
A pointer to your item-receive-drag callback function.
The universal procedure pointer.
See the DataBrowserItemReceiveDragProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to an item-iterator callback function.
DataBrowserItemUPP NewDataBrowserItemUPP ( DataBrowserItemProcPtr userRoutine );
A pointer to your item-iterator callback function.
The universal procedure pointer.
See the DataBrowserItemProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a postprocess-drag callback function.
DataBrowserPostProcessDragUPP NewDataBrowserPostProcessDragUPP ( DataBrowserPostProcessDragProcPtr userRoutine );
A pointer to your postprocess-drag callback function.
The universal procedure pointer.
See the DataBrowserPostProcessDragProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a receive-drag callback function.
DataBrowserReceiveDragUPP NewDataBrowserReceiveDragUPP ( DataBrowserReceiveDragProcPtr userRoutine );
A pointer to your receive-drag callback function.
The universal procedure pointer.
See the DataBrowserReceiveDragProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a select-contextual-menu callback function.
DataBrowserSelectContextualMenuUPP NewDataBrowserSelectContextualMenuUPP ( DataBrowserSelectContextualMenuProcPtr userRoutine );
A pointer to your select-contextual-menu callback function.
The universal procedure pointer.
See the DataBrowserSelectContextualMenuProcPtr callback function.
HIDataBrowser.h
Creates a universal procedure pointer to a tracking callback function.
DataBrowserTrackingUPP NewDataBrowserTrackingUPP ( DataBrowserTrackingProcPtr userRoutine );
A pointer to your tracking callback function.
The universal procedure pointer.
See the DataBrowserTrackingProcPtr callback function.
HIDataBrowser.h
Opens a data browser container.
OSStatus OpenDataBrowserContainer ( ControlRef browser, DataBrowserItemID container );
A data browser.
The item ID of the container to open.
A result code. See “Data Browser Result Codes.”
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.
HIDataBrowser.h
Removes one or more items from a data browser.
OSStatus RemoveDataBrowserItems ( ControlRef browser, DataBrowserItemID container, ItemCount numItems, const DataBrowserItemID *items, DataBrowserPropertyID preSortProperty );
A data browser.
An item ID or the constant kDataBrowserNoItem. Pass the item ID that uniquely identifies the container from which you want to remove items. Pass kDataBrowserNoItem to remove items from the root container.
The number of items in the array pointed to by the items parameter. To remove all items pass 0 and also pass NULL in the items parameter.
A pointer to an array of item ID values for the items you want to remove from the data browser. You can delete an arbitrary list of items from a container. To remove all items, pass NULL, and also pass 0 in the numItems parameter.
The property ID of the column whose sorting order is the same as the sorting order of the items array. A property ID is a value that identifies a column independent of its position in a data browser. Pass kDataBrowserItemNoProperty if the items array is not sorted or if you don’t know the sorting order. You’ll get the best performance from this function if you provide a sorting order.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Removes a column from a list view data browser.
OSStatus RemoveDataBrowserTableViewColumn ( ControlRef browser, DataBrowserTableViewColumnID column );
A data browser.
The property ID for the list view column you want to remove. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
A result code. See “Data Browser Result Codes.”
This function works only for list view.
HIDataBrowser.h
Scrolls an item into view, optionally bringing a particular part of that item into view.
OSStatus RevealDataBrowserItem ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID propertyID, DataBrowserRevealOptions options );
A data browser.
The item ID of the item to scroll into view.
The property ID of the column to scroll into view. A property ID is a four-character sequence that you assign to represent a column in list view. For column view, pass kDataBrowserNoItem.
A value that specifies how to position the item in the data browser. See “Reveal Options” for a list of the constants you can supply.
A result code. See “Data Browser Result Codes.”
In most cases the system takes care of scrolling for you. However, this function is useful if your application supports type-select and you want to scroll a matching item into view.
HIDataBrowser.h
Sets what determines the active state of the items in a data browser.
OSStatus SetDataBrowserActiveItems ( ControlRef browser, Boolean active );
A data browser.
A value that specifies the new active state for the items displayed in the list. Pass true to make the active state of each item determined by what your callback reports for each item’s kDataBrowserItemIsActiveProperty property, or false to make all items inactive. Inactive items appear dimmed.
A result code. See “Data Browser Result Codes.”
Passing true for the active parameter does not make all the items active. Instead it sets the active state of each individual item according to the value associated with the kDataBrowserItemIsActiveProperty property for that item. This means if the active property for an item is set to false, and you pass true for the active parameter, then the item is inactive.
HIDataBrowser.h
Sets the callback routines to use with a data browser, replacing any previously installed callbacks.
OSStatus SetDataBrowserCallbacks ( ControlRef browser, const DataBrowserCallbacks *callbacks );
A data browser.
A pointer to a DataBrowserCallbacks structure that is filled out with universal procedure pointers (UPPs) to the callback routines your application provides. At a minimum, you need to provide a UPP to an item-data callback (DataBrowserItemDataProcPtr).
A result code. See “Data Browser Result Codes.”
Before calling the function SetDataBrowserCallbacks you must first call InitDataBrowserCallbacks to initialize the data browser callback structure. Calling SetDataBrowserCallbacks replaces any callback routines you installed previously by calling this function.
You can supply the following callbacks. If you don’t supply callbacks in cases for which it’s optional, you get the default behavior provided by the data browser API.
DataBrowserItemDataProcPtr. You must provide this callback because communicates the text, icons, or other data to display in list view. It also communicates the metadata that defines how data is displayed, such as whether or not an item is a container or has a parent. If you set up your data browser to allow the user to edit, this callback informs your application when the user makes a change.
DataBrowserItemCompareProcPtr. You must provide a sorting callback if you want users to be able to sort the items in a column. If you want containers in a hierarchical list to be sorted independently, then you must provide a sorting callback that handles the hierarchical lists appropriately.
DataBrowserItemNotificationProcPtr. You must provide this (or the next) callback if you have hierarchical data in a list, or if you use column view.
DataBrowserItemNotificationWithItemProcPtr (Mac OS X only)
DataBrowserAddDragItemProcPtr. You can provide this callback to allow dragging out of your data browser.
DataBrowserAcceptDragProcPtr. You can provide this callback to allow dragging into your data browser; use this to accept a drag item.
DataBrowserReceiveDragProcPtr. You can provide this callback to allow dragging into your data browser; use this to receive a drag item.
DataBrowserPostProcessDragProcPtr. If you provide callbacks to allow dragging into your data browser, you can optionally provide a postprocess-drag callback to perform cleanup tasks.
DataBrowserGetContextualMenuProcPtr. You can optionally support a contextual menu. If so, you’ll need to provide the next callback too.
DataBrowserItemHelpContentProcPtr. You can optionally provide help tags.
Note that this function sets a different set of callbacks from those that are set by calling the function SetDataBrowserCustomCallbacks.
To replace a callback, you first need to get the current set of callbacks by calling the function GetDataBrowserCallbacks. Set the appropriate fields in the DataBrowserCallbacks structure to your callback. Then you call the function SetDataBrowserCallbacks. Your application can set as many callbacks as appropriate.
The following code shows how to assign UPPs to the callbacks structure and then call the function SetDataBrowserCallbacks. The code assumes you have already called the function InitDataBrowserCallbacks to initialize the data browser callback structure.
myCallbacks.u.v1.itemNotificationCallback = |
NewDataBrowserItemNotificationUPP (MyItemNotificationCallback); |
myCallbacks.u.v1.acceptDragCallback = |
NewDataBrowserAcceptDragUPP (MyAcceptDragCallback); |
myCallbacks.u.v1.receiveDragCallback = |
NewDataBrowserReceiveDragUPP (MyReceiveDragCallback); |
myCallbacks.u.v1.addDragItemCallback = |
NewDataBrowserAddDragItemUPP (MyAddDragItemCallback); |
myCallbacks.u.v1.itemHelpContentCallback = |
NewDataBrowserItemHelpContentUPP (MyItemHelpContentCallback); |
myCallbacks.u.v1.getContextualMenuCallback = |
NewDataBrowserGetContextualMenuUPP (MyGetContextualMenuCallback); |
myCallbacks.u.v1.selectContextualMenuCallback = |
NewDataBrowserSelectContextualMenuUPP ( |
MySelectContextualMenuCallback); |
SetDataBrowserCallbacks (browser, &myCallbacks); |
HIDataBrowser.h
Sets the display type for a data browser in column view.
OSStatus SetDataBrowserColumnViewDisplayType ( ControlRef browser, DataBrowserPropertyType propertyType );
A data browser.
The data type to be displayed in the data browser. The default is kDataBrowserIconAndTextType. Currently this is the only value you can supply for column view.
A result code. See “Data Browser Result Codes.”
This function is effectively not functional because no display types other than kDataBrowserIconAndTextType are currently supported. Note that the rightmost column can have the attribute kDataBrowserColumnViewPreviewProperty as long as you provide a callback to display the appropriate icon and text information in the preview column.
HIDataBrowser.hSets a path for a column view.
OSStatus SetDataBrowserColumnViewPath ( ControlRef browser, UInt32 length, const DataBrowserItemID *path );
A data browser.
The number of items in the array passed in the path parameter.
The address to the first item in the array of item ID values that specifies the path. Array element 0 is the root; array element N - 1 is the target.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets the custom callback routines to use with a data browser, replacing any previously installed custom callbacks.
OSStatus SetDataBrowserCustomCallbacks ( ControlRef browser, const DataBrowserCustomCallbacks *callbacks );
A data browser.
A pointer to a DataBrowserCustomCallbacks structure that is filled out with universal procedure pointers (UPPs) to the custom callback routines your application provides.
A result code. See “Data Browser Result Codes.”
Before calling the function SetDataBrowserCustomCallbacks you must first call InitDataBrowserCustomCallbacks to initialize the data browser custom callback structure. Calling SetDataBrowserCustomCallbacks replaces any callback routines you installed previously by calling this function.
You can supply the following custom callback routines.
DataBrowserDrawItemProcPtr. This callback is invoked by the data browser whenever your content needs to be drawn. You must supply this callback for data whose display type is kDataBrowserCustomType.
DataBrowserEditItemProcPtr. Supply this callback when you want to support editing of your content.
DataBrowserHitTestProcPtr. You can provide this callback to determine if the pointer is over content that can be selected or dragged.
DataBrowserTrackingProcPtr. This callback implements custom tracking behavior.
DataBrowserItemDragRgnProcPtr. You can supply this callback when you need to determine which part of an item to use to create a transparent image for a dragged item.
DataBrowserItemAcceptDragProcPtr. This callback determines if an item can accept a drag object.
DataBrowserItemReceiveDragProcPtr. This callback receives a drop over an item.
Note that this is a different set of callbacks from those that are installed by calling the function SetDataBrowserCallbacks.
To replace a callback, you first need to set the appropriate fields in the DataBrowserCustomCallbacks structure to your callbacks. Then you call the function SetDataBrowserCustomCallbacks. The following code shows how to set custom callbacks. It assumes you have already called the function InitDataBrowserCustomCallbacks to initialize the data browser custom callback structure. Your application can set as many callbacks as appropriate.
myCustomCallbacks.u.v1.drawItemCallback = |
NewDataBrowserDrawItemUPP (MyDataBrowserDrawItemCallback); |
myCustomCallbacks.u.v1.editItemCallback = |
NewDataBrowserEditItemUPP (MyDataBrowserEditItemCallback); |
SetDataBrowserCustomCallbacks (browser,&myCustomCallbacks); |
HIDataBrowser.h
Programmatically starts or ends an editing session.
OSStatus SetDataBrowserEditItem ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property );
A data browser.
The item ID of the item to make editable.
The property ID of the item to make editable.
A result code. See “Data Browser Result Codes.”
You can call the function SetDataBrowserEditItem to begin or end an editing session programmatically for a text item. To begin an editing session for a text item, specify its item ID and property ID. To end an editing session, provide the constant kDataBrowserNoItem as the item ID number.
HIDataBrowser.h
Modifies the displayed contents of a text item while it is being edited.
OSStatus SetDataBrowserEditText ( ControlRef browser, CFStringRef text );
A data browser.
A CFString object that specifies the text to edit. The data browser makes its own copy of this object so it is safe to release your own reference after you call this function.
A result code. See “Data Browser Result Codes.”
You can use this function to programmatically change the text. For example, to paste data in response to a Paste command. This function is useful only if an edit session is in progress for an item. You can check whether can get session is open by calling the function GetDataBrowserEditItem.
HIDataBrowser.h
Sets the display state of horizontal and vertical scroll bars for a list view data browser.
OSStatus SetDataBrowserHasScrollBars ( ControlRef browser, Boolean horiz, Boolean vert );
A list view data browser.
A value that specifies whether to display the browser control with (true) or without (false) a horizontal scroll bar.
A value that specifies whether to display the browser control with (true) or without (false) a vertical scroll bar.
A result code. See “Data Browser Result Codes.”
If the list your application displays is small and its coordinates do not extend beyond the bounds of the area used to display the list, then you can call SetDataBrowserHasScrollBars to turn off the display of scroll bars.
HIDataBrowser.h
Specifies a Boolean value for an item.
OSStatus SetDataBrowserItemDataBooleanValue ( DataBrowserItemDataRef itemData, Boolean theData );
The item data reference for the item whose Boolean value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataBooleanValue.
The value to display.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to an inquiry for the following properties:
kDataBrowserItemIsActiveProperty
kDataBrowserItemIsSelectableProperty
kDataBrowserItemIsEditableProperty
kDataBrowserItemIsContainerProperty
kDataBrowserItemIsOpenableProperty
kDataBrowserItemIsClosableProperty
kDataBrowserItemIsSortableProperty
HIDataBrowser.h
Specifies a checkbox value.
OSStatus SetDataBrowserItemDataButtonValue ( DataBrowserItemDataRef itemData, ThemeButtonValue theData );
The item data reference for the item whose checkbox value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataButtonValue.
The checkbox setting. You can supply any of the following theme button value constants defined by the Appearance Manager:
kThemeButtonOff draws a checkbox that is not selected.
kThemeButtonOn draws a checkbox that is selected.
kThemeButtonMixed draws a checkbox that in a mixed state, indicating that a setting is on for some items in a selection and off for others.
See Appearance Manager Reference for more information.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a set-data request for items that have the display type kDataBrowserCheckboxType.
HIDataBrowser.h
Specifies, as a 32-bit value, a date and time value to display.
OSStatus SetDataBrowserItemDataDateTime ( DataBrowserItemDataRef itemData, SInt32 theData );
The item data reference for the item whose date and time value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataDateTime.
A 32-bit value that represents the number of elapsed seconds since midnight, January 1, 1904. For more information about date and time encodings used in the Mac OS, see Date, Time, and Measurement Utilities Reference.
A result code. See “Data Browser Result Codes.”
This function works only with items that have the property kDataBrowserDateTimeType. If the column has the property kDataBrowserRelativeDateTime, the date is displayed relative to the current time for the computer. For example, a time 24 hours before the current time is displayed as “Yesterday.” Other examples of relative date and time values are “Today, 1:45 PM” and “Yesterday, 7:30 AM.”
HIDataBrowser.h
Specifies whether to draw a checkbox in the active or inactive state.
OSStatus SetDataBrowserItemDataDrawState ( DataBrowserItemDataRef itemData, ThemeDrawState theData );
The item data reference for the item whose drawing state you want to set. This value is passed to the callback routine from which you are calling the function SetDataBrowserItemDataDrawState.
The drawing state to use for the checkbox item. You can supply the following theme drawing state constants:
kThemeStateInactive draws the item in the inactive state.
kThemeStateActive draws the item in the active state.
See Appearance Manager Reference for more information on these constants.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a set-data request for items that have the display type kDataBrowserCheckboxType.
HIDataBrowser.h
Specifies the icon to draw.
OSStatus SetDataBrowserItemDataIcon ( DataBrowserItemDataRef itemData, IconRef theData );
The item data reference for the item whose icon you want to set. This value is passed to the callback routine from which you are calling the function SetDataBrowserItemDataIcon.
The icon to display. The data browser retains the icon, so you may release the IconRef after the function returns.
A result code. See “Data Browser Result Codes.”
You call the function SetDataBrowserItemDataIcon from within a DataBrowserItemDataProcPtr callback routine to specify an icon to draw. You can specify an icon for any column that has the kDataBrowserIconType display type or the kDataBrowserIconAndTextType display type.
HIDataBrowser.h
Specifies a transformation to apply to an icon when it is drawn.
OSStatus SetDataBrowserItemDataIconTransform ( DataBrowserItemDataRef itemData, IconTransformType theData );
The item data reference for the item whose icon transformation you want to set. This value is passed to the callback routine from which you are calling the function SetDataBrowserItemDataIconTransform.
An icon transformation type that specifies how to modify the appearance of the icon. You can pass any of the icon transformation constants defined by Icon Services and Utilities. See Icon Services and Utilities Reference for more information.
A result code. See “Data Browser Result Codes.”
This function works only with items that either have the property kDataBrowserIconAndTextType or kDataBrowserIconType.
HIDataBrowser.h
Communicates a property of an item when that property is another item’s ID.
OSStatus SetDataBrowserItemDataItemID ( DataBrowserItemDataRef itemData, DataBrowserItemID theData );
The item data reference passed to your item-data callback.
The item ID to set.
A result code. See “Data Browser Result Codes.”
To display hierarchical data correctly the data browser needs to know whether an item is a container and whether the item is in a container (has a parent). So it sends a get-data request for the properties kDataBrowserParentContainerProperty and kDataBrowserContainerAliasIDProperty to your item-data callback.
The property kDataBrowserContainerAliasIDProperty is sent to your item-data callback to provide your application with a chance to follow an alias that the item might represent. If the incoming item is an alias to another item, you can call SetDataBrowserItemDataItemID to inform the data browser which other item the incoming item points to.
The property kDataBrowserParentContainerProperty is sent to your item-data callback to check whether an item has a parent. If it does, you call SetDataBrowserItemDataItemID, supplying the item ID of the parent in the parameter theData. If the item has no parent, set theData to 0.
HIDataBrowser.h
Specifies, as a 64-bit value, a date and time value to display.
OSStatus SetDataBrowserItemDataLongDateTime ( DataBrowserItemDataRef itemData, const LongDateTime *theData );
The item data reference for the item whose long date and time value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataLongDateTime.
A pointer to a 64-bit value that represents the time as the number of elapsed seconds since midnight, January 1, 1904. For more information about date and time encodings used in the Mac OS, see Date, Time, and Measurement Utilities Reference in Carbon Text & International Documentation.
A result code. See “Data Browser Result Codes.”
This function works only with items that have the property kDataBrowserDateTimeType. If the column has the property kDataBrowserRelativeDateTime, the date is displayed relative to the current time for the computer. For example, a time 24 hours before the current time is displayed as “Yesterday.” Other examples of relative date and time values are “Today, 1:45 PM” and “Yesterday, 7:30 AM.”
HIDataBrowser.h
Specifies the maximum integer value that can be displayed for an item; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus SetDataBrowserItemDataMaximum ( DataBrowserItemDataRef itemData, SInt32 theData );
The item data reference for the item whose maximum value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataMaximum.
The maximum setting for content displayed for the item.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets the pop-up menu to display.
OSStatus SetDataBrowserItemDataMenuRef ( DataBrowserItemDataRef itemData, MenuRef theData );
The item data reference for the item whose pop-up menu value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataMenuRef.
The pop-up menu set to the value you want to display. The system retains the menu reference that you pass; you must release it when you no longer need it. Pass NULL if you no longer want a menu.
A result code. See “Data Browser Result Codes.”
Your item-data callback calls this function in response to a set-data request for an item whose display type is kDataBrowserPopupMenuType.
HIDataBrowser.h
Specifies the minimum integer value that can be displayed for an item; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus SetDataBrowserItemDataMinimum ( DataBrowserItemDataRef itemData, SInt32 theData );
The item data reference for the item whose minimum value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataMinimum.
The minimum setting for the displayed content.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Specifies a color to use when drawing an item.
OSStatus SetDataBrowserItemDataRGBColor ( DataBrowserItemDataRef itemData, const RGBColor *theData );
The item data reference for the item whose color you want to set. This value is passed to the callback routine from which you are calling the function SetDataBrowserItemDataRGBColor.
A pointer to the RGB values that specify the color to use.
A result code. See “Data Browser Result Codes.”
Typically this function is used to set the color for an item that is an icon type. Your item-data callback calls this function in response to a set-data request for items that have display type kDataBrowserIconType or kDataBrowserIconAndTextType.
HIDataBrowser.h
Specifies the text to draw.
OSStatus SetDataBrowserItemDataText ( DataBrowserItemDataRef itemData, CFStringRef theData );
The item data reference for the item whose text you want to set. This value is passed to the callback routine from which you are calling the function SetDataBrowserItemDataText.
The CFString object that contains the text you want to draw. You are responsible for releasing the CFString object.
A result code. See “Data Browser Result Codes.”
You call the function SetDataBrowserItemDataText from inside a data callback routine when the item being drawn is inside a column that has the kDataBrowserTextType display type or the kDataBrowserIconAndTextType display type.
HIDataBrowser.h
Sets the value of an item; useful for such display types as sliders, progress bars, relevance indicators, and pop-up menus.
OSStatus SetDataBrowserItemDataValue ( DataBrowserItemDataRef itemData, SInt32 theData );
The item data reference for the item whose integer value you want to set. The item data reference is passed to the callback routine from which you are calling the function SetDataBrowserItemDataValue.
The value to display. The value must be between the minimum and maximum values specified by calling the functions SetDataBrowserItemDataMinimum and SetDataBrowserItemDataMaximum. Values displayed by a progress bar can vary between the minimum and maximum values, inclusive.
A result code. See “Data Browser Result Codes.”
Your application calls the function SetDataBrowserItemDataValue to set a new value for a display type when your item-data callback routine is called with the setValue parameter set to false.
HIDataBrowser.h
Specifies whether there is a column that has disclosure triangles and, if so, which column.
OSStatus SetDataBrowserListViewDisclosureColumn ( ControlRef browser, DataBrowserTableViewColumnID column, Boolean expandableRows );
A data browser.
The property ID for the column for which you want to set as disclosure column. Only one column in list view can be designated as a disclosure column. Pass kDataBrowserNoItemProperty if you do not want a disclosure column. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
A value that specifies how a disclosed row behaves. Pass true to have a container open as a single row with an expanded height. Pass false to have a container opens to expose other rows. See the Discussion for more details on expandable rows.
A result code. See “Data Browser Result Codes.”
A disclosure triangle next to an item denotes the item is a container. You can use the expandableRows parameter to specify whether an opened container displays its items in individual rows, as shown in the top of Figure 1 or increases its row height to accommodate the contained information, as shown in the bottom of the figure.
When the expandableRows parameter is set to true:
Disclosure triangles are drawn top-justified in the row.
Custom row height, if any, for that row is respected only while the row is disclosed. At other times, the default row height is used.
When the expandableRows parameter is set to false:
Disclosure triangles are centered vertically in the row.
Custom row height, if any, for that row is always respected.
When a disclosure triangle is clicked by the user, your application receives the same notifications regardless of whether expandableRows is set to true or false. When your application receives a notification that an expandable row is toggled to open, call the function SetDataBrowserTableViewItemRowHeight to set the row to the appropriate height.
HIDataBrowser.h
Sets the height of the rectangular area where the column title appears.
OSStatus SetDataBrowserListViewHeaderBtnHeight ( ControlRef browser, UInt16 height );
A data browser.
The height, in pixels, to use for the rectangular area where the column title appears. Pass 0 to turn off header button display. To turn on header button display, pass the value previously obtained from the function GetDataBrowserListViewHeaderBtnHeight. The default height is currently 17 pixels.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Provides a description for a column title in list view.
OSStatus SetDataBrowserListViewHeaderDesc ( ControlRef browser, DataBrowserTableViewColumnID column, DataBrowserListViewHeaderDesc *desc );
A data browser.
The property ID for the column in list view whose title description you want to set. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
The list view header description structure that you have filled out with data that describes the appearance of a column title in list view.
A result code. See “Data Browser Result Codes.”
This functions allows you to change the behavior or appearance of a column title. Typically you call this function if your application:
Supports switching between list and column views, and you need to restore previously saved list view title information.
Creates a list view data browser programmatically and the columns have titles.
HIDataBrowser.h
Specifies whether list view uses a plain white background.
OSStatus SetDataBrowserListViewUsePlainBackground ( ControlRef browser, Boolean usePlainBackground );
A data browser.
A value that specifies whether to use a plain background (true) or not to use a plain background (false). A plain background is an all-white background. In Mac OS X, passing false currently does nothing, as Mac OS X supports only a plain white background. However, pass true if you want a plain white background just in case the API changes in the future. In Mac OS 9, passing false causes the data browser to use a shaded background.
A result code. See “Data Browser Result Codes.”
A list view that does not use a plain background can use colors or patterns to distinguish one column from another. For example, you could specify a color to designate a column as the sorted column.
HIDataBrowser.h
Sets the appearance and behavior attributes for a column in list view.
OSStatus SetDataBrowserPropertyFlags ( ControlRef browser, DataBrowserPropertyID property, DataBrowserPropertyFlags flags );
A data browser.
The property ID of the column whose appearance and behavior you want to set.
The property flags to apply. A DataBrowserPropertyFlags value is a 32-bit value that is divided into four parts as follows:
Bits 0–7 specify properties applied to the data browser as a whole—see “Property Flags: Universal”
Bits 8–15 modify display behavior—see “Property Flags: Modifiers”
Bits 16–23 are properties specific to list view—see “Property Flags: Offset and Mask for List View Properties” and “Property Flags: List View Column Behavior”
Bits 24–31 can be defined by your application—see “Property Flags: Offset and Mask for Client-Defined Properties”
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets the inset values to use for the scroll bars of a data browser.
OSStatus SetDataBrowserScrollBarInset ( ControlRef browser, Rect *insetRect );
A data browser.
A pointer to a rectangle that specifies the inset values you want the data browser to use. The left and right fields contain the horizontal inset values for the horizontal scroll bar, and the top and bottom fields contain the vertical inset values for the vertical scroll bar.
A result code. See “Data Browser Result Codes.”
Your application can call the functions GetDataBrowserScrollBarInset and SetDataBrowserScrollBarInset if you want to place placards or controls beside the horizontal scroll bars or above the vertical ones. To do so, first call GetDataBrowserScrollBarInset to obtain the current settings. After modifying the current inset settings to provide space for the placard or control, call SetDataBrowserScrollBarInset with the new values.
HIDataBrowser.h
Scrolls a list to the specified position.
OSStatus SetDataBrowserScrollPosition ( ControlRef browser, UInt32 top, UInt32 left );
A data browser.
The vertical scrolling position to use.
The horizontal scrolling position to use.
A result code. See “Data Browser Result Codes.”
The scrolling position (0,0) represents the home position, and is located at the top left of the data browser. Horizontal and vertical units are relative to the home position.
You can call this function to scroll a list to any arbitrary scrolling position. Normally, you use the function GetDataBrowserScrollPosition in conjunction with SetDataBrowserScrollPosition to save and restore the scrolling position of a list to the user’s last scrolling position. These functions should not be used to scroll particular cells into the view. For that, call the function RevealDataBrowserItem.
HIDataBrowser.h
Modifies the current selection by adding items, removing items, or toggling the selection state of items.
OSStatus SetDataBrowserSelectedItems ( ControlRef browser, ItemCount numItems, const DataBrowserItemID *items, DataBrowserSetOption operation );
A data browser.
The number of item ID values stored in the array pointed to by the items parameter.
A pointer to an array of the item IDs to modify the selection with.
The operation you want to perform on the current selection. You can add, assign, toggle, or remove the items specified by the items parameter. See “Selection State Options” for a list of the constants you can supply and a complete description of what each constant does.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets allowable selection behavior for a data browser.
OSStatus SetDataBrowserSelectionFlags ( ControlRef browser, DataBrowserSelectionFlags selectionFlags );
A data browser.
Flags that specify the selection behavior you want to allow in the data browser. The flags control such things as whether discontinuous selections are allowed by the user. See “User Selection Flags” for detailed descriptions of these flags.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets the sorting order for a list in list view.
OSStatus SetDataBrowserSortOrder ( ControlRef browser, DataBrowserSortOrder order );
A data browser.
The sorting order. See “Sorting Orders” for a list of the constants you can supply.
A result code. See “Data Browser Result Codes.”
List view tracks the sorting order by column. In Mac OS X, setting the sorting order only affects the sorting order of the column currently set for sorting.
HIDataBrowser.h
Designates the list view column to use for sorting.
OSStatus SetDataBrowserSortProperty ( ControlRef browser, DataBrowserPropertyID property );
A data browser.
The property ID of the column to use for sorting.
A result code. See “Data Browser Result Codes.”
If the list is not currently sorted, or if the list is currently sorted with a different column, then the list is sorted and redrawn. You can all the function GetDataBrowserSortProperty to obtain the property ID of the column currently used for sorting.
HIDataBrowser.h
Changes the visual position of a column in list view.
OSStatus SetDataBrowserTableViewColumnPosition ( ControlRef browser, DataBrowserTableViewColumnID column, DataBrowserTableViewColumnIndex position );
A data browser.
The property ID for the list view column you want to move. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
The position you want to move the column to.
A result code. See “Data Browser Result Codes.”
If you set your list to have the property kDataBrowserListViewMovableColumn, the user can rearrange columns by dragging. The function SetDataBrowserTableViewColumnPosition provides a way for your application to rearrange columns programmatically.
HIDataBrowser.h
Sets the default column width for all columns in a data browser.
OSStatus SetDataBrowserTableViewColumnWidth ( ControlRef browser, UInt16 width );
A data browser.
The column width, in pixels.
A result code. See “Data Browser Result Codes.”
You can override the default width for an individual list view column by calling the function SetDataBrowserTableViewNamedColumnWidth.
HIDataBrowser.h
Sets whether columns and rows can have variable widths in list view.
OSStatus SetDataBrowserTableViewGeometry ( ControlRef browser, Boolean variableWidthColumns, Boolean variableHeightRows );
A data browser.
A Boolean value that specifies whether column widths can be variable (true) or not (false).
A Boolean value that specifies whether row heights can be variable (true) or not (false).
A result code. See “Data Browser Result Codes.”
After you call the function SetDataBrowserTableViewGeometry to set up variable row heights or columns widths in list view, you can modify individual row heights or columns widths in list view by calling the appropriate function—either SetDataBrowserTableViewItemRowHeight or SetDataBrowserTableViewNamedColumnWidth.
HIDataBrowser.h
Sets the highlighting style to use for a list view data browser.
OSStatus SetDataBrowserTableViewHiliteStyle ( ControlRef browser, DataBrowserTableViewHiliteStyle hiliteStyle );
A list view data browser.
The highlighting style you want to use. See “Table View Highlighting Styles” for a description of the constants you can supply.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Changes the visual position for an item in a list view data browser.
OSStatus SetDataBrowserTableViewItemRow ( ControlRef browser, DataBrowserItemID item, DataBrowserTableViewRowIndex row );
A data browser.
The item ID for the item whose row you want to set.
The row index for the row you want to move the item to.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Sets the row height for a single row in a list view data browser.
OSStatus SetDataBrowserTableViewItemRowHeight ( ControlRef browser, DataBrowserItemID item, UInt16 height );
A data browser.
The item ID for the item whose row height you want to set.
The row height, in pixels.
A result code. See “Data Browser Result Codes.”
Before calling this function, you must call the function SetDataBrowserTableViewGeometry to set up variable row heights.
HIDataBrowser.h
Sets the column width for a single column in a list view data browser.
OSStatus SetDataBrowserTableViewNamedColumnWidth ( ControlRef browser, DataBrowserTableViewColumnID column, UInt16 width );
A data browser.
The property ID for the list view column whose width you want to set. The DataBrowserTableViewColumnID data type is the same as the DataBrowserPropertyID data type.
The width of the column, in pixels.
A result code. See “Data Browser Result Codes.”
Before calling this function, you must call the function SetDataBrowserTableViewGeometry to set up variable column widths.
HIDataBrowser.h
Sets the default row height for all rows in a data browser.
OSStatus SetDataBrowserTableViewRowHeight ( ControlRef browser, UInt16 height );
A data browser.
The row height, in pixels.
A result code. See “Data Browser Result Codes.”
This function sets the default row height for all rows. You override the default row height for an individual row by calling the function SetDataBrowserTableViewItemRowHeight.
HIDataBrowser.h
Sets the target for a data browser.
OSStatus SetDataBrowserTarget ( ControlRef browser, DataBrowserItemID target );
A data browser.
The item ID to assign as the target for the browser control.
A result code. See “Data Browser Result Codes.”
Your application can set an item ID to use as a target if you do not want to use the default target set by the data browser. By default, the target is a container whose ID is kDataBrowserNoItem. For the list view, the target can be thought of as the root container. For the column view, the target is the rightmost column. When an item is dragged over a data browser but not dropped over any particular item, the target becomes the destination.
SetDataBrowserTarget changes the container that the data browser displays, thereby populating the data browser with items. If you use the function in column view, you must make sure your item-data callback responds to the property kDataBrowserItemParentContainerProperty by providing the item ID of the target’s parent. This allows the function SetDataBrowserColumnViewPath to process the data properly. The target is the leaf node item whose contents you want to display. However, unlike GetDataBrowserColumnViewPathLength, the function SetDataBrowserTarget doesn’t offer a way for you to communicate the item IDs of the rest of the column containers, so SetDataBrowserTarget asks for them explicitly by requesting the item’s parent, then the parent of the item’s parent, and so on.
You can pass a noncontainer item to this function in either list or column views. If you do, you must also respond to the property kDataBrowserItemParentContainerProperty. The data browser requests the parent of the target so it knows which container to display the contents of in the list view.
HIDataBrowser.h
Restores the view-style settings in list view to a previous state set by the user.
OSStatus SetDataBrowserUserState ( ControlRef browser, CFDictionaryRef stateInfo );
A data browser.
A CFDictionary object that specifies the view-style settings that you want to restore. Note that although this parameter is typed as a CFData object, you must supply a CFDictionary object because that is the form of the data the system expects.
A result code. See “Data Browser Result Codes.”
Typically you use this function to restore the user state you previously obtained by calling the function GetDataBrowserUserState.
HIDataBrowser.h
Sets the view style of the specified data browser.
OSStatus SetDataBrowserViewStyle ( ControlRef browser, DataBrowserViewStyle style );
A data browser.
The view style to use. Pass the constant kDataBrowserListView to draw the data browser using list view or kDataBrowserColumnView to use column view. See “View Styles” for more information on these constants.
A result code. See “Data Browser Result Codes.”
Although you specify a view style when you call the function CreateDataBrowserControl, you can call SetDataBrowserViewStyle to change the style. Use SetDataBrowserViewStyle when you provide users the option of changing between list and column views.
After calling SetDataBrowserViewStyle, you need to perform the necessary tasks to configure the data browser for the view style you switched to. If you switch to list view, you need to set up list view header and column descriptions and call the function AddDataBrowserListViewColumn. You might also need to call other functions such as SetDataBrowserListViewDisclosureColumn (for hierarchical lists).
HIDataBrowser.h
Sorts a hierarchical list of items.
OSStatus SortDataBrowserContainer ( ControlRef browser, DataBrowserItemID container, Boolean sortChildren );
A data browser.
An item ID or the constant kDataBrowserNoItem. To sort all of the items that are organized as subitems of a container item, pass the item ID for the container item. To sort all of the items displayed at the top level of the data browser, pass the constant kDataBrowserNoItem.
A value that indicates whether to sort all items in the container hierarchy. Pass true to sort all items in the container hierarchy and false to sort just the immediate children of the container.
A result code. See “Data Browser Result Codes.”
HIDataBrowser.h
Requests a redraw of one or more items in a data browser.
OSStatus UpdateDataBrowserItems ( ControlRef browser, DataBrowserItemID container, ItemCount numItems, const DataBrowserItemID *items, DataBrowserPropertyID preSortProperty, DataBrowserPropertyID propertyID );
A data browser.
An item ID or the constant kDataBrowserNoItem. Pass the item ID that uniquely identifies the container. If you are updating one or more items that are in the root container, pass kDataBrowserNoItem.
The number of items in the array pointed to by the items parameter.
A pointer to an array of item ID values for the items you want to update. If you pass NULL or if the value kDataBrowserNoItem is an element in this array, then all rows are updated.
The property ID of the column whose sorting order is the same as 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 of if you don’t know the sorting order.
The property ID of the column that must be updated. To update all columns associated with the items in the items array, pass kDataBrowserNoItem.
A result code. See “Data Browser Result Codes.”
After your application makes changes to any of the data items in a data browser you must update the display by calling the function UpdateDataBrowserItems. Calling this function also updates any internal caches allocated by the data browser.
HIDataBrowser.hDefines a pointer to an accept-drag callback function that determines whether your application can accept a drag object in the specified location.
typedef Boolean (*DataBrowserAcceptDragProcPtr) ( ControlRef browser, DragRef theDrag, DataBrowserItemID item );
You would declare an accept-drag callback function named MyDataBrowserAcceptDragCallback like this:
Boolean MyDataBrowserAcceptDragCallback ( ControlRef browser, DragRef theDrag, DataBrowserItemID item );
A data browser.
The drag reference provided by the data browser to your callback.
The item ID of the item the drag object is held over. If the drag object is over the data browser but not over any specific item, the item parameter contains the item ID that represents one of the following:
In list view, the target. (See SetDataBrowserTarget.)
In column view, the item ID of the column the drag object is over
Your callback returns true if it is capable of accepting the drag object in the location designated by the item parameter. Otherwise, your callback returns false.
The accept-drag callback is called by the data browser when your application needs to determine if it can accept a drag object in a particular location.
To provide a pointer to your accept-drag callback, you create a universal procedure pointer (UPP) of type DataBrowserAcceptDragUPP, using the function NewDataBrowserAcceptDragUPP. You can do so with code similar to the following:
DataBrowserAcceptDragUPP MyDataBrowserAcceptDragUPP; |
MyDataBrowserAcceptDragUPP = NewDataBrowserAcceptDragUPP |
(&MyDataBrowserAcceptDragCallback); |
You can then assign MyDataBrowserAcceptDragUPP to the acceptDragCallback field of the structure DataBrowserCallbacks. You install your data browser callbacks using the function SetDataBrowserCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserAcceptDragUPP function.
HIDataBrowser.hDefines a pointer to an add-drag-item callback function that adds an item to a drag reference.
typedef Boolean (*DataBrowserAddDragItemProcPtr) ( ControlRef browser, DragRef theDrag, DataBrowserItemID item, ItemReference *itemRef );
You would declare an add-drag-item callback function named MyDataBrowserAddDragItemCallback like this:
Boolean MyDataBrowserAddDragItemCallback ( ControlRef browser, DragRef theDrag, DataBrowserItemID item, ItemRef *itemRef );
A data browser.
The drag reference provided by the data browser to your callback.
The item ID of the item to add to the drag object.
A pointer to a drag item reference variable. Your callback must set this to the DragItemRef value that it passes to the Drag Manager function AddDragItemFlavor.
Your callback returns true to indicate the item should be or is part of the drag object. Your callback returns false if the item isn’t part of the drag object.
The add-drag-item callback is called by the data browser when a drag operation needs to be started. The data browser iterates through the selected items, invoking your callback for each item. Your callback is called after the drag reference is created by the data browser but before the function TrackDrag is called by the system.
Your callback adds an item to the drag reference calling the function AddDragItemFlavor. When you call AddDragItemFlavor, you must provide a unique drag item reference (DragItemRef) for each data browser item that you add to the drag. You must also provide the data type of the added item (drag flavor type) and set the appropriate drag flavor flags.
The data browser handles imaging and adds transparency for you. As a result, you do not need to create or add your own transparency information to the drag reference.
To provide a pointer to your add-drag-item callback, you create a universal procedure pointer (UPP) of type DataBrowserAddDragItemUPP, using the function NewDataBrowserAddDragItemUPP. You can do so with code similar to the following:
DataBrowserAddDragItemUPP MyDataBrowserAddDragItemUPP; |
MyDataBrowserAddDragItemUPP = NewDataBrowserAddDragItemUPP |
(&MyDataBrowserAddDragItemCallback); |
You can then assign MyDataBrowserAddDragItemUPP to the addDragItemCallback field of the structure DataBrowserCallbacks. You install your data browser callbacks using the function SetDataBrowserCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserAddDragItemUPP function.
HIDataBrowser.hDefines a pointer to a draw-item callback function that draws a custom item.
typedef void (*DataBrowserDrawItemProcPtr) ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserItemState itemState, const Rect *theRect, SInt16 gdDepth, Boolean colorDevice );
You would declare a draw-item callback function named MyDataBrowserDrawItemCallback like this:
void MyDataBrowserDrawItemCallback ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, DataBrowserItemState itemState, const Rect *theRect, SInt16 gdDepth, Boolean colorDevice );
A data browser.
The item ID for the item to draw.
The property ID for the item. In list view, this is the four-character sequence that you previously assigned to the column. In column view, this is the property kDataBrowserItemSelfIdentityProperty.
The state to use when drawing the item. See “Item States” for a description of the constants that can be provided to your callback.
A pointer to the bounding rectangle (in local coordinates, relative to the port) that specifies where to draw the item. This rectangle is the content rectangle, not the enclosing rectangle.
The bit depth of the current QuickDraw graphics port. The data browser sets the current QuickDraw port to the port that you draw into. This may not always be the port of the data browser’s own window.
A value that specifies whether the current QuickDraw port is a color device (true) or is not (false).
The draw-item callback is called by the data browser when an item whose display type is kDataBrowserCustomType needs to be drawn. Your application draws the item so it reflects the state specified by the itemState parameter.
To provide a pointer to your draw-item callback, you create a universal procedure pointer (UPP) of type DataBrowserDrawItemUPP, using the function NewDataBrowserDrawItemUPP. You can do so with code similar to the following:
DataBrowserDrawItemUPP MyDataBrowserDrawItemUPP; |
MyDataBrowserDrawItemUPP = NewDataBrowserDrawItemUPP |
(&MyDataBrowserDrawItemCallback); |
You can then assign MyDataBrowserDrawItemUPP to the drawItemCallback field of the structure DataBrowserCustomCallbacks. You install your data browser custom callbacks using the function SetDataBrowserCustomCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserDrawItemUPP function.
HIDataBrowser.hDefines a pointer to an edit-item callback function that determines if the data browser should start an edit session for a custom item.
Not Recommended
typedef Boolean (*DataBrowserEditItemProcPtr) ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, CFStringRef theString, Rect *maxEditTextRect, Boolean *shrinkToFit );
You would declare an edit-item callback function named MyDataBrowserEditItemCallback like this:
Boolean MyDataBrowserEditItemCallback ( ControlRef browser, DataBrowserItemID item, DataBrowserPropertyID property, CFStringRef theString, Rect *maxEditTextRect, Boolean *shrinkToFit );
A data browser.
The item ID number for the item.
The property ID for the item. In list view, this is the four-character sequence that you previously assigned to the column. In column view, this is the property kDataBrowserItemSelfIdentityProperty.
The string to be edited. See Special Considerations for more information.
On input, a pointer to a rectangle structure. On return, set the rectangle to the largest size the edit field can grow to. If the text grows beyond the size of the edit field, the text scrolls as the user types. This parameter is used only if the parameter shrinkToFit is true. Otherwise, the current size of the text editing field is used.
On input, a pointer to a Boolean variable. On return, set this variable to true if you want the data browser to expand or shrink the text editing field to match the width of the text in the edit field. Note that this parameter is currently ignored; shrinkToFit is always true by default.
A value that indicates whether or not you want to start an edit operation for the given property of the item. If your application performs the editing operation, your callback returns true. Otherwise, your callback returns false.
The edit-item callback is called by the data browser for an item whose property is kDataBrowserCustomType. Your callback must determine whether an editing session should be started and, if so, set the string to be edited, set the size of the edit rectangle, and specify whether the text editing field can adjust to match the width of the text in the edit field.
To provide a pointer to your edit-item callback, you create a universal procedure pointer (UPP) of type DataBrowserEditItemUPP, using the function NewDataBrowserEditItemUPP. You can do so with code similar to the following:
DataBrowserEditItemUPP MyDataBrowserEditItemUPP; |
MyDataBrowserEditItemUPP = NewDataBrowserEditItemUPP |
(&MyDataBrowserEditItemCallback); |
You can then assign MyDataBrowserEditItemUPP to the editItemCallback field of the structure DataBrowserCustomCallbacks. You install your data browser custom callbacks using the function SetDataBrowserCustomCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserEditItemUPP function.
This callback does not work properly. The theString parameter is an immutable sting, which means it is not possible for the callback to set the string to the text that is to be edited.
HIDataBrowser.hDefines a pointer to a get-contextual-menu callback function that obtains a menu and information about the menu.
typedef void (*DataBrowserGetContextualMenuProcPtr) ( ControlRef browser, MenuRef *menu, UInt32 *helpType, CFStringRef *helpItemString, AEDesc *selection );
You would declare a get-contextual-menu callback function named MyDataBrowserGetContextualMenuCallback like this:
void MyDataBrowserGetContextualMenuCallback ( ControlRef browser, MenuRef *menu, UInt32 *helpType, CFStringRef *helpItemString, AEDesc *selection );
A data browser.
On input, a pointer to a menu. Your callback must set the pointer to the menu that you want to have displayed for the given item. Your application is responsible for disposing of the menu; you typically perform this task in the callback DataBrowserSelectContextualMenuProcPtr.
On input, a pointer to an unsigned 32-bit integer. On return, this value specifies the type of help available for this item. This value is then passed by the data browser to the Menu Manager function ContextualMenuSelect. You can provide one of the following values:
kCMHelpItemNoHelp if your application does not support help. The Menu Manager inserts an appropriate string into the menu and then disables the associated help item.
kCMHelpItemAppleGuide if your application supports Apple Guide help. The Menu Manager inserts the name of the main Apple Guide file into the menu and enables the associated help item. You can pass this in Mac OS 9. Apple Guide is not supported in Mac OS X. In Mac OS X, this value is ignored; a generic, but inactive, help item is displayed.
kCMHelpItemOtherHelp if your application supports some other form of help. In this case, your application must pass a valid string in the helpItemString parameter. The Menu Manager inserts the string in the menu and enables the associated help item.
See Menu Manager Reference for more information about these constants.
On input, a CFStringRef variable. On return, a CFString object that contains the name of the item to display in the contextual menu. This is the first item that appears in the contextual menu. If you pass NULL, the default string (“Help”) is displayed. Data Browser does not retain the string; it releases it.
On input, a pointer to an empty AEDesc data structure. On return, the structure contains the data supplied by your callback. The data browser passes this structure to the function ContextualMenuSelect.
The get-contextual-menu callback is called by the data browser when the user Control-clicks in the data browser. You application provides a menu and information about help that is (or is not) available for the data browser. You can determine what to provide for the content of the menu and what information to put in the AEDesc structure by calling the function GetDataBrowserItems with the state parameter set to kDataBrowserItemIsSelected. This tells you what items are selected, which you can then use to choose the appropriate information to supply.
To provide a pointer to your get-contextual-menu callback, you create a universal procedure pointer (UPP) of type DataBrowserGetContextualMenuUPP, using the function NewDataBrowserGetContextualMenuUPP. You can do so with code similar to the following:
DataBrowserGetContextualMenuUPP MyDataBrowserGetContextualMenuUPP; |
MyDataBrowserGetContextualMenuUPP = NewDataBrowserGetContextualMenuUPP |
(&MyDataBrowserGetContextualMenuCallback); |
You can then assign MyDataBrowserGetContextualMenuUPP to the getContextualMenuCallback field of the structure DataBrowserCallbacks. You install your data browser callbacks using the function SetDataBrowserCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserGetContextualMenuUPP function.
HIDataBrowser.hDefines a pointer to a hit-test callback function that determines if the pointer is over content that can be selected or dragged.
typedef Boolean (*DataBrowserHitTestProcPtr) ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, const Rect *mouseRect );
You would declare a hit-test callback function named MyDataBrowserHitTestCallback like this:
Boolean MyDataBrowserHitTestCallback ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, const Rect *mouseRect );
A data browser.
The item ID number for the item over which the pointer is located.
The property ID for the column in which the pointer is located. In list view, this is the four-character sequence that you previously assigned to the column. In column view, this is the property kDataBrowserItemSelfIdentityProperty.
A pointer to the bounding rectangle, in local coordinates, of the item.
A pointer to a rectangle structure that contains the local coordinates of the selection. 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 data browser is testing to see whether your custom item is inside of the bounding rectangle of a selection.
Your application returns a true value for either of the following conditions:
The pointer is located over the part of the item that can be selected or dragged.
The rectangle provided in the parameter mouseRect intersects with the content area of the item that can be selected or dragged.
The hit-test callback is called by the data browser when the user hovers the pointer over, clicks the mouse within, or drags within an item whose display type is kDataBrowserCustomType. Your callback can use the functions SetRect or SectRgn to determine if the selectable content of the custom item is part of the selection. Figure 2 illustrates a situation for which the selectable or draggable content area differs from the background area in which the item is displayed.
To provide a pointer to your hit-test callback, you create a universal procedure pointer (UPP) of type DataBrowserHitTestItemUPP, using the function NewDataBrowserHitTestUPP. You can do so with code similar to the following:
DataBrowserHitTestUPP MyDataBrowserHitTestUPP; |
MyDataBrowserHitTestUPP = NewDataBrowserHitTestUPP |
(&MyDataBrowserHitTestCallback); |
You can then assign MyDataBrowserHitTestUPP to the hitTestCallback field of the structure DataBrowserCustomCallbacks. You install your data browser custom callbacks using the function SetDataBrowserCustomCallbacks.
When you no longer need the UPP, remove it using the DisposeDataBrowserHitTestUPP function.
HIDataBrowser.hDefines a pointer to an item-accept-drag callback function that determines if a custom item can accept a drag object.
typedef DataBrowserDragFlags (*DataBrowserItemAcceptDragProcPtr) ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, DragRef theDrag );
You would declare an item-accept-drag callback function named MyDataBrowserItemAcceptDragCallback like this:
DataBrowserDragFlags MyDataBrowserItemAcceptDragCallback ( ControlRef browser, DataBrowserItemID itemID, DataBrowserPropertyID property, const Rect *theRect, DragRef theDrag );
A data browser.
The item ID number for the item the drag object is held over. If the drag object is over the data browser but not over any specific item, the item parameter contains the item ID that represents one of the following:
The target in list view. (See SetDataBrowserTarget.)
The column the drag object is over in column view
The property ID of the column the dragged object is over. In list view, this is the four-character sequence that you previously assigned to the column. In column view, this is the property kDataBrowserItemSelfIdentityProperty.
A pointer to the bounding rectangle of the item, in local coordinates relative to the current port.
The drag reference provided by the data browser to your callback.
If your callback determines the drag object can be accepted, return a nonzero value that has the bit kDataBrowserItemIsDragTarget set. Otherwise return kDataBrowserItemNoState. The return value is then passed to your item-receive-drag callback in the dragFlags