ADC Home > Reference Library > Reference > Scripting & Automation > Tools > AppleScript Studio Terminology Reference >

< Previous PageNext Page > Hide TOC

Data View Suite

This chapter describes the terminology in AppleScript Studio’s Data View suite.

The Data View suite defines classes whose primary purpose is to display rows and columns of data. Many classes in the Data View suite inherit from the view class or the cell class. The Data View suite defines events for working with the items, cells, rows, and columns found in table and outline views.

The following features became available in the Data View suite in AppleScript Studio version 1.4. Many of these features are demonstrated in the Simple Table and Simple Outline sample applications.

Terminology

The classes, commands, and events in the Data View suite are described in the following sections:

For enumerated constants, see “Enumerations.”

Classes

The Data View suite contains the following classes:

browser
Plural: browsers
Inherits from: control
Cocoa Class: NSBrowser

Provides a user interface for displaying and selecting items from a list of data, or from hierarchically organized lists of data such as directory paths.

When working with a hierarchy of data, the levels are displayed in columns, which are numbered from left to right. Column numbers are zero-based.

You will find the browser object on the Cocoa-Data pane in Interface Builder’s Palette window. You can set many attributes for browsers in Interface Builder’s Info window.

Figure 5-1 shows a browser displaying files on a hard drive. For more information, see browser cell and update, as well as the document Browsers.

Note: Unlike other data views such as outline view and table view, you cannot supply data to a browser view with a data source. As a result, performance may be inadequate for browser views that display more than a small number of items, and you should consider using one of the other data views, if suitable for your purpose.


Figure 5-1  A browser view displaying part of the file system

A browser view displaying part of the file system

Properties of browser objects

In addition to the properties it inherits from the control class, a browser object has these properties:

accepts arrow keys
 Access:/write
 Class:boolean
 Does the browser accept input from arrow keys? default is false; you can set this property in the Info window in Interface Builder
allows branch selection
 Access:read/write
 Class:boolean
 Does the browser allow selection of a branch item when multiple selection is enabled? each cell can be either a branch cell (such as a directory) or a leaf cell (such as a file); default is false; you can set this property in the Info window in Interface Builder
allows empty selection
 Access:read/write
 Class:boolean
 Can there be an empty selection? default is true; you can set this property in the Info window in Interface Builder
allows multiple selection
 Access:read/write
 Class:boolean
 Can there be multiple items selected? default is false; you can set this property in the Info window in Interface Builder
cell prototype
 Access:read/write
 Class:browser cell
 the prototype cell for the browser; this cell is copied to display items in the browser’s columns
displayed cell
 Access:read/write
 Class:browser cell
 the cell being displayed in the browser
first visible column
 Access:read/write
 Class:integer
 the zero-based index of the first visible column in the browser; see also the maximum visible columns property
has horizontal scroller
 Access:read/write
 Class:boolean
 Does the browser have a horizontal scroll bar? default is true; you can set this property in the Info window in Interface Builder
last column
 Access:read/write
 Class:integer
 the zero-based index of the last column in the browser
last visible column
 Access:read/write
 Class:integer
 the zero-based index of the last currently visible column in the browser; see also the maximum visible columns property
loaded
 Access:read only
 Class:boolean
 Is the data for the browser loaded? if true, all the information for the currently displayed columns has been acquired (a browser view calls the will display browser cell event handler for each cell when it needs to display data in a column)
maximum visible columns
 Access:read/write
 Class:integer
 the total number of visible columns; you can set the number of visible columns in the Info window in Interface Builder
minimum column width
 Access:read/write
 Class:real
 the maximum width of a column
path
 Access:read/write
 Class:Unicode text
 the path that represents the selected item (for example, when the browser is displaying files in a file system)
path separator
 Access:read/write
 Class:Unicode text
 the string to use as the separator for the path; defaults to the slash character (/)
reuses columns
 Access:read/write
 Class:boolean
 Should the browser reuse its columns? default is true, meaning the browser doesn’t free underlying column objects when columns are unloaded
selected cell
 Access:read/write
 Class:browser cell
 the currently selected cell
selected column
 Access:read/write
 Class:integer
 the zero-based index of the currently selected column
send action on arrow key
 Access:read/write
 Class:boolean
 Should the browser perform actions when it receives arrow key input?
separates columns
 Access:read/write
 Class:boolean
 Should the columns be separated by bezeled borders? default is true; you can set this property in the Info window in Interface Builder, but only if you have deselected the “Is titled” checkbox
title height
 Access:read only
 Class:real
 the height of the title
titled
 Access:read/write
 Class:boolean
 Does the browser use titles? you can set this property in the Info window in Interface Builder; not supported (through AppleScript Studio version 1.4); however, the following is a workaround that uses the call method command:
 
set isTitled to call method "isTitled" of browser 1
uses title from previous column
 Access:read/write
 Class:boolean
 Should the browser use the value of the previous column for the title of the next column? default is true


Elements of browser objects

In addition to the elements it inherits from the control class, a browser object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

cell
 Specify by: “Standard Key Forms”
 

the browser’s data cells; may actually be of class browser cell


Commands supported by browser objects

Your script can send the following commands to a browser object:

path for
update

Events supported by browser objects

A browser object supports handlers that can respond to the following events:

Action
clicked

Browser View
number of browser rows
will display browser cell

Drag and Drop
conclude drop
drag
drag entered
drag exited
drag updated
drop
prepare drop

Key
keyboard down
keyboard up

Mouse
mouse down
mouse dragged
mouse entered
mouse exited
mouse up
right mouse down
right mouse dragged
right mouse up
scroll wheel

Nib
awake from nib

View
bounds changed

Examples

The following statement shows how to set the path separator property of a browser with AppleScript name “browser” in a window with name “main”.

set path separator of browser "browser" of window "main"  to ":"

This statement is from the launched handler of the Browser sample application distributed with AppleScript Studio. The full handler is listed in the example for the update command.

Working with browser views is a complex task that can’t be covered fully here. The Browser application provides a complete but relatively simple example that browses the file system, displaying files and folders in a window similar to the Finder’s column view.

Version Notes

The titled property in this class is not supported, through AppleScript Studio version 1.4.

Support for drag-and-drop commands was added in AppleScript Studio version 1.2.
browser cell
Plural: browser cells
Inherits from: cell
Cocoa Class: NSBrowserCell

Represents the default subclass of cell used to display data in the columns of a browser.

Each column in a browser contains a matrix filled with browser cells. For more information, see browser, as well as the document Browsers.

Properties of browser cell objects

In addition to the properties it inherits from the cell class, a browser cell has these properties:

alternate image
 Access:read/write
 Class:image
 an alternate image that should used for the highlighted state for the browser cell
leaf
 Access:read/write
 Class:boolean
 Is this a leaf cell? each cell can be either a branch cell (such as a directory) or a leaf cell (such as a file); a branch browser cell has an image near its right edge indicating that more, nested information is available; a leaf browser cell has no image, indicating that the user has reached a terminal piece of information
loaded
 Access:read/write
 Class:boolean
 Is the cell loaded? true if all the browser cell’s state has been set and the cell is ready to display (a browser view calls the will display browser cell event handler for each cell when it needs to display data in a column)


Events supported by browser cell objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following is the will display browser cell handler from the Browser sample application distributed with AppleScript Studio. The Browser application browses the file system, displaying files and folders in a window similar to the Finder’s column view. This handler uses the Finder to get information about the browser cell to be displayed, then sets properties of the cell. See the Browser application for a complete example of working with a browser view, including the full text for this handler.

on will display browser cell theObject row theRow browser cell theCell  in column  theColumn
    -- Code to set the values of the cellContents and isLeaf variables
    --      is not shown
    set string value of theCell to cellContents
    set leaf of theCell to isLeaf
 
end will display browser cell

Note that unlike other data views such as outline view and table view, you cannot supply data to a browser view with a data source. As a result, performance may be inadequate for browser views that display more than a small number of items, and you should consider using one of the other data views, if suitable for your purpose.
data cell
Plural: data cells
Inherits from: None.
Cocoa Class: ASKDataCell

Represents one cell in a data row of a data source.

The data cell stores contents for the cell, as well as other information for accessing its data.

You typically create a data source to manage the data for an outline view or table view. You then create each data column and supply a name. This process is demonstrated in the Examples section for the append command.

Next you create data rows (for a table view) or data items (for an outline view) for the data source. For each data row or data item you create, the data source automatically creates a data cell for each column, by default giving each data cell the name of its column. After creating a row (or item), you can set the data for its data cells, typically by specifying the row (or item) and name for the cell. You can use the same information to get the contents of a data cell.

Properties of data cell objects

A data cell object has these properties:

content
 Access:read/write
 Class:item
 the contents of the cell; nearly synonymous with contents; for related information, see the Version Notes section for this class
contents
 Access:read/write
 Class:item
 the contents of the cell; nearly synonymous with content; for related information, see the Version Notes section for this class
name
 Access:read/write
 Class:Unicode text
 the name of the cell; when you create a data row, a data cell is created for each column and by default the name is set to the name of the column


Elements of data cell objects

A data cell object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data item
 Specify by: “Standard Key Forms”
 

data item for the row that contains the data cell

data row
 Specify by: “Standard Key Forms”
 

the row that contains the data cell


Events supported by data cell objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following getContactInfo handler is from the Table sample application distributed with AppleScript Studio. You will find it in the script file WithDataSource.applescript. The getContactInfo handler shows how to set the contents of a data cell from the contents of a text field. Each of the data cells is identified by its name, supplied earlier when the data source was initialized.

-- Get the values from the text fields and set the cells in the  data row
--
on getContactInfo(theWindow, theRow)
    tell theWindow
        set contents of data cell "name" of theRow
            to contents of text field "name"
        set contents of data cell "address" of theRow
            to contents of text field "address"
        set contents of data cell "city" of theRow
            to contents of text field "city"
        set contents of data cell "state" of theRow
            to contents of text field "state"
        set contents of data cell "zip" of theRow
            to contents of text field "zip"
    end tell
end getContactInfo

Figure 5-2 shows the running Table application, with one contact. Another handler from the Table application is shown in the Examples section for the data column class.

To get information from a data cell, given the data row that contains the cell, you use a statement like the following, from the setContactInfo handler in the same Table application. As in the previous example, this statement appears within a tell block that specifies the window:

set contents of text field "name"
    to contents of data cell "name" of theRow

The Task List sample application (available starting with AppleScript Studio version 1.2), contains a data representation handler that shows how to access every data cell of a data source.

on data representation theObject of type ofType
    -- Set some local variables to various objects in the UI
    set theWindow to window 1 of theObject
    set theDataSource to data source of table view "tasks"
        of scroll view "tasks" of theWindow
    set theTasks to contents of every data cell of every data row
        of theDataSource
    set theSortColumn to sort column of theDataSource
 
    -- Statements for working with data cells not shown.
end data representation

To get the contents of every data cell in a table, you could use a statement like the following:

set theData to contents of every data cell of every data row of  data source of  table view 1 of scroll view 1 of window "main"

To get the contents of every data cell of a particular column, you could use a statement like the following:

set theData to contents of data cell "zip" of data rows  of dataSource of table  view "bigTable" of scroll view "myScrollView"  of window 1

Note: You can specify objects by index, by name, or by a mix of the two, as shown in the previous two examples.

For an example that uses data cells with data items in an outline view, see the Examples section for the data item class. For an example that extracts a name from a data cell in the clicked data row, see the Examples section for the table view class.

Version Notes

The content property was added in AppleScript Studio version 1.2. You can use content and contents interchangeably, with one exception. Within an event handler, contents of theObject returns a reference to an object, rather than the actual contents. To get the actual contents of an object (such as the text contents from a text field) within an event handler, you can either use contents of contents of theObject or content of theObject.

For a sample script that shows the difference between content and contents, see the Version Notes section for the control class.
data column
Plural: data columns
Inherits from: None.
Cocoa Class: ASKDataColumn

Represents a column in a data source.

Stores the column name, data source, and other information for the column. You can use the data column’s elements to access its rows or the individual cells that provide its data.

You typically create a data source to manage the data for an outline view or table view. You then create each data column and supply a name. This process is demonstrated in the Examples section for the append command.

For an outline view, one column is the outline column, which contains disclosure triangles for expanding or contracting its items. The first column is typically the outline column (though you can specify whether to allow users to reorder columns in the Info window in Interface Builder).

For related information, see data cell.

Properties of data column objects

A data column object has these properties (see the Version Notes section for this class for the AppleScript Studio version in which a particular property was added):

data source
 Access:read only
 Class:data source
 the data source the data column is associated with
name
 Access:read/write
 Class:Unicode text
 the name of the column
sort case sensitivity
 Access:read/write
 Class:enumerated constant from Sort Case Sensitivity
 the case sensitivity of the sort (case sensitive, case insensitive)
sort order
 Access:read/write
 Class:enumerated constant from Sort Order
 the order of the sort (ascending, descending)
sort type
 Access:read/write
 Class:enumerated constant from Sort Type
 the type of sort (alphabetical, numerical)


Elements of data column objects

A data column object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data cell
 Specify by: “Standard Key Forms”
 

the data cells for the column, one per row; by default there is one data cell for each data column in a data row

data row
 Specify by: “Standard Key Forms”
 

the data rows in the column


Events supported by data column objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following will open handler is from the Table sample application distributed with AppleScript Studio. It shows how to create and name the data columns of a data source. This handler does the following:

on will open theObject
    -- Set up reference variable to simplify later statements.
    set contactsDataSource to data source of table view "contacts"
        of scroll view "contacts" of theObject
 
    -- Add the data columns to the data source of the contacts table  view.
    tell contactsDataSource
        make new data column at the end of the data columns
            with properties {name:"name"}
        make new data column at the end of the data columns
            with properties {name:"address"}
        make new data column at the end of the data columns
            with properties {name:"city"}
        make new data column at the end of the data columns
            with properties {name:"state"}
        make new data column at the end of the data columns
            with properties {name:"zip"}
    end tell
end will open

Figure 5-2 shows the running application, with one contact. For another example that uses data columns, see the Examples section for the data item class.


Figure 5-2  The Table application

The Table application

Version Notes

The sort case sensitivity, sort order, and sort type properties were added in AppleScript Studio version 1.2.
data item
Plural: data items
Inherits from: data row
Cocoa Class: ASKDataItem

Represents one, possibly expandable, row of a data source.

A data item can contain nested data items, supporting data storage for items in a hierarchical view, such as an outline view, where a user can open an item to display contained items. A data item’s properties specify whether it has any nested data items, as well as whether it has a parent item, and if so, a reference to the parent item. Its elements store any nested data items.

You typically create a data source to manage the data for an outline view or table view. You then create each data column and supply a name. This process is demonstrated in the Examples section below, as well as in the Examples section for the append command.

Next, for a outline view, you create data item objects for the data source. For each data item you create, the data source automatically creates a data cell for each column, by default giving each data cell the name of its column. After creating a data item, you can set the data for its data cells, typically by specifying the data item and the name for the cell. You can use the same information to get the contents of a data cell.

For a table view, you create data row objects instead of data item objects, as described in the Examples section for the data row class.

Properties of data item objects

In addition to the properties it inherits from the data row class, a data item has these properties:

has data items
 Access:read only
 Class:boolean
 Does this item have any data items?
has parent data item
 Access:read only
 Class:boolean
 Does this item have a parent item?
parent data item
 Access:read/write
 Class:data item
 the parent item for the item


Elements of data item objects

A data item object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data cell
 Specify by: “Standard Key Forms”
 

the data cells for the item, one per row

data item
 Specify by: “Standard Key Forms”
 

the data item’s nested data items

data row
 Specify by: “Standard Key Forms”
 

the data rows in the column


Events supported by data item objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following launched handler is from a simple outline application. It demonstrates the common steps for working with data items and data columns in a data source, including:

The launched event handler is called at the end of the startup sequence of an application, so it is a suitable place to create a data source for an outline view and populate it with data items. This handler adds the following information to the outline view:

- Things to do
    - Work on outline example
        - Make it plain and simple
        - Put it all in a "launched" event handler
    - Put it in my iDisk when done

Here is the launched handler:

on launched theObject
    -- Create the data source; this places it in the application
    --  object’s data source elements. (Assign it to outline view  below.)
    set dataSource to make new data source at end of data sources
        with properties {name:"tasks"}
 
    -- Create the data columns
    tell dataSource
        make new data column at end of data columns
            with properties {name:"task"}
        make new data column at end of data columns
            with properties {name:"completed"}
    end tell
 
    -- Create the top-level parent data item "Things to do"
    set parentItem to make new data item at end of data items of  dataSource
    set contents of data cell "task" of parentItem to  "Things to do"
    set contents of data cell "completed" of parentItem  to "--"
 
    -- Create the first child data item "Work on outline example",  which
    --  will have its own children
    set childItem to make new data item at end of data items of  parentItem
    set contents of data cell "task" of childItem
        to "Work on outline example"
    set contents of data cell "completed" of childItem  to "Yes"
 
    -- Create first child data item of "Work on outline example"
    set childChildItem to make new data item at end of data items  of childItem
    set contents of data cell "task" of childChildItem
        to "Make it plain and simple"
    set contents of data cell "completed" of childChildItem  to "Yes"
 
    -- Create second child data item of "Work on outline example"
    set childChildItem to make new data item at end of data items
        of childItem
    set contents of data cell "task" of childChildItem
        to "Put it all in a \"launched\" event handler"
    set contents of data cell "completed" of childChildItem  to "Yes"
 
    -- Create the second child data item of "Things to do"
    set childItem to make new data item at end of data items of  parentItem
    set contents of data cell "task" of childItem
        to "Put it in my iDisk when done"
    set contents of data cell "completed" of childItem  to "No"
 
    -- Assign the data source to the outline view
    set data source of outline view "tasks" of scroll  view "scroll"
        of window "main" to dataSource
end launched

Figure 5-3 shows the running application, with all the data items expanded.


Figure 5-3  The to do list application

The to do list application
data row
Plural: data rows
Inherits from: None.
Cocoa Class: ASKDataRow

Represents one row in a data source.

Stores the row’s data source and other information. You can use the data row’s elements to access its columns or the individual cells that provide its data.

You typically create a data source to manage the data for an outline view or table view. You then create each data column and supply a name. This process is demonstrated in the Examples section for the append command.

Next, for a table view, you create data rows for the data source.

Important:  You must create the data columns before creating the data rows.

For each row you create, the data source automatically creates a data cell for each column, by default giving each data cell the name of its column. After creating a row, you can set the data for its data cells, typically by specifying the row and name for the cell. You can use the same information to get the contents of a data cell.

For an outline view, you create data item objects instead of data row objects, as described in the Examples section for the data item class.

Properties of data row objects

A data row object has these properties:

associated object
 Access:read/write
 Class:item
 an object that can be associated with the row
content
 Access:read/write
 Class:item
 the contents of the data row; nearly synonymous with contents; for related information, see the Version Notes section for this class
contents
 Access:read/write
 Class:item
 the contents of the data row; nearly synonymous with content; for related information, see the Version Notes section for this class
name
 Access:read/write
 Class:Unicode text
 the name of the cell; when you create a data row, a data cell is created for each column and by default the name is set to the name of the column
data source
 Access:read only
 Class:data source
 the data source the data row is associated with


Elements of data row objects

A data row object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data cell
 Specify by: “Standard Key Forms”
 

the data row’s data cells; each cell stores cell name, contents, and other information

data column
 Specify by: “Standard Key Forms”
 

the data row’s data columns; each column stores column name, data source, and other information


Events supported by data row objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following statement shows how to create a data row. It is taken from the clicked handler in the Table sample application distributed with AppleScript Studio.

set theRow to make new data row at the end of the data rows
    of contactsDataSource

For an example that extracts a name from a data cell in the clicked data row, see the Examples section for the table view class. That Examples section also shows how to use the content property to set data rows starting in AppleScript Studio 1.4.

For an additional example that works with data rows, see the Examples section for data cell.

Version Notes

The content and contents properties were added to the data row class in AppleScript Studio version 1.4. You can use content and contents interchangeably, with one exception. Within an event handler, contents of theObject returns a reference to an object, rather than the actual contents. To get the actual contents of an object (such as the text contents from a text field) within an event handler, you can either use contents of contents of theObject or content of theObject.

For a sample script that shows the difference between content and contents, see the Version Notes section for the control class.
data source
Plural: data sources
Inherits from: None.
Cocoa Class: ASKDataSource

Stores the data for and provides the data to views that display row and column data.

A data source object represents a form of backing store for a table and is based on a special class supplied by AppleScript Studio’s AppleScriptKit framework.

For related information, see data cell, data column, data item, and data row, as well as the document Table View Programming Guide.

Your application supplies a data source object with row and column data for a view such as a table view or outline view. Once you have supplied the data, the data source object works with the view to automatically display the correct information as a user scrolls, resizes the window, reorders the columns, or otherwise changes the displayed rows and columns.

You can supply the data for a data source directly in your script or read it from a file. AppleScript Studio provides the read from file and load data representation handlers to get information from a file, but it doesn’t provide any special support moving data from a file to a data source.

Using a data source is much more efficient that supplying data in script event handlers that must be queried for each bit of data. And to make use of a data source even more efficient, you can set its update views property to false before updating the data source, then set it to true afterwards, so that updating in the associated view happens all at once.

Each view that displays row and column data uses at most one data source. However, you can use multiple views with the same data source if, for example, you want to emphasize different aspects of the data. Then if you change the data in the data source, each view will automatically update to reflect the new values.

For examples that show how to create a data source in your application scripts, see the Examples sections for the append command and the data item class. You can also create a data source in Interface Builder by dragging it from the Cocoa-AppleScript pane of the Palette window. This mechanism isn’t recommended and isn’t described here, but you can read about it in the Mail Search tutorial in AppleScript Studio Programming Guide. See “See Also” for information on how to obtain that document.

Starting with AppleScript Studio version 1.2, data sources can be sorted. The data source still retains the data rows in the order that they were added to the data source, but it can present the data in sorted order. To enable sorting of a data source, you must do the following

  • Add the following properties when creating data columns in the make new statement.

    • sort order: ascending or descending

    • sort type: alphabetical or numerical

    • sort case sensitivity: case sensitive or case insensitive

    For example:

    make new data column at end of data columns of theDataSource with properties {name: "name", sort order: ascending, sort type: alphabetical, sort case sensitivity: case sensitive}

  • Set the sorted property of the data source to true.

    For example:

    set sorted of theDataSource to true

  • Set the sort column property of the data source to the initial column to sort on.

    For example:

    set sort column of theDataSource to data column "name"  of theDataSource

  • Connect a column clicked event handler to your table view. This will provide the opportunity to change the current sort column, as well as the sort order of the data columns in your data source, when a user clicks in a column’s table header view. The sample script shown in the Examples section below is fairly standard and can be used, as is, in your application.

    For full examples, see the Table Sort and Task List sample applications distributed with AppleScript Studio (starting with version 1.2).

If you designate the sort type of a column as numerical, you need to ensure that the contents of the data cells for that column are in fact numbers, not strings. Or if you designate the column as alphabetical, the contents of the data cells for that column must contain strings (text).

Starting in AppleScript Studio version 1.4, your application can can access the data rows of a data source in their sorted order by using the sorted data rows property.

Properties of data source objects

A data source object has these properties (see the Version Notes section for this class for the AppleScript Studio version in which a particular property was added):

allows reordering
 Access:read/write
 Class:boolean
 Can the columns be reordered? default is false; you cannot set this property in Interface Builder; if you set this property to true in your application, a user can drag rows up and down within a table view or outline view, in effect changing the order
content
 Access:read/write
 Class:item
 the contents of the data source; nearly synonymous with contents; for related information, see the Version Notes section for this class
contents
 Access:read/write
 Class:item
 the contents of the data source; nearly synonymous with content; for related information, see the Version Notes section for this class
localized sort
 Access:read/write
 Class:boolean
 Should the data be sorted using localization rules?
returns records
 Access:read/write
 Class:boolean
 Will getting the contents of the data source return a list of records? default is true
sort column
 Access:read/write
 Class:data column
 the data column to sort the data on; properties of the column control the sort
sorted
 Access:read/write
 Class:boolean
 Should the data source be sorted?
sorted data rows
 Access:read only
 Class:list
 the data rows of the data source in its currently sorted order
update views
 Access:read/write
 Class:boolean
 Should views of the data source be updated? for efficiency, you should avoid unnecessary updating by setting this property to false before updating the data source, then setting it to true afterwards, as shown in the Examples section for this class; see also the update command


Elements of data source objects

A data source object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data cell
 Specify by: “Standard Key Forms”
 

the data source’s data cells; each cell stores cell name, contents, and other information

data column
 Specify by: “Standard Key Forms”
 

the data sources data columns; each column stores column name and other information

data item
 Specify by: “Standard Key Forms”
 

the data source’s data items

data row
 Specify by: “Standard Key Forms”
 

the data source’s data rows

view
 Specify by: “Standard Key Forms”
 

the data source’s view


Commands supported by data source objects

Your script can send the following commands to a data source object:

append

Events supported by data source objects

A data source object supports handlers that can respond to the following events:

Nib
awake from nib
 

You can only connect an awake from nib handler to a data source object if you create the data source in Interface Builder, not if you create the data source in an application script file (the recommended approach). However, it is unlikely you will need to connect this handler to a data source object. See the data source class description above for additional information about creating a data source in Interface Builder.


Examples

For examples that show how to create a data source, see the Examples sections for the append command and the data item class.

When you make changes to the data for a data source for a visible view, performance is likely to suffer as the data source continually updates the view. You can ensure optimum performance by turning off updating while you modify the data source, then turning it on again when finished. The following lines show how to do this.

    -- Turn off updating
    set update views of theDataSource to false
    -- Add statements here that modify the data source
    --
    -- Turn updating back on
    set update views of theDataSource to true

Sorting for data sources, added to AppleScript Studio version 1.2, is described in the description for this class above. You can also see sorting in the Table and Task List sample applications (available starting with AppleScript Studio version 1.2).

The following column clicked handler shows how to handle a change in the selected sort column. You connect the clicked handler to the table view or outline view that contains the columns to sort. This handler is fairly standard and can be used, as is, in most applications. It does the following:

on column clicked theObject table column tableColumn
    -- Get the data source of the table view
    set theDataSource to data source of theObject
 
    -- Get the identifier of the clicked table column;
    --  you can instead use the name of the column
    set theColumnIdentifier to identifier of tableColumn
 
    -- Get the current sort column of the data source
    set theSortColumn to sort column of theDataSource
 
    -- If the current sort column is not the same as the clicked  column
    --   then switch the sort column
    if (name of theSortColumn) is not equal to theColumnIdentifier  then
        set the sort column of theDataSource to
            data column theColumnIdentifier of theDataSource
    else
        -- Otherwise change the sort order
        if sort order of theSortColumn is ascending then
            set sort order of theSortColumn to descending
        else
            set sort order of theSortColumn to ascending
        end if
    end if
 
    -- Update the table view (so it will be redrawn)
    update theObject
end column clicked

The Table Sort and Task List sample applications, first distributed with AppleScript Studio version 1.2, provide full examples of how to sort a data source.

Working with data sources is a complex task that can’t be covered fully here. For an additional, relatively simple example, see the Outline sample application, which shows how to use an outline view to display items in the file system. The Table sample application uses a data source with a table view.

For a more detailed example, see the chapters in AppleScript Studio Programming Guide that describe how to build the Mail Search application (which is also distributed with AppleScript Studio).

Version Notes

The following properties were added to the data source class in AppleScript Studio version 1.4:

You can use content and contents interchangeably, with one exception. Within an event handler, contents of theObject returns a reference to an object, rather than the actual contents. To get the actual contents of an object (such as the text contents from a text field) within an event handler, you can either use contents of contents of theObject or content of theObject.

For a sample script that shows the difference between content and contents, see the Version Notes section for the control class.

Support for drag-and-drop commands was added in AppleScript Studio version 1.2.

Sorting for data source objects was added in AppleScript Studio version 1.2.

The localized sort, sort column, and sorted properties were added in AppleScript Studio version 1.2.

The Table Sort and Task List sample applications were added in AppleScript Studio version 1.2.

The preferred (and most convenient) method for using a data source is to create it and assign it directly in an application script, as shown in the Examples sections for the append command and the data item class. This option was added in AppleScript Studio version 1.1. Prior to version 1.1, you had to use a more cumbersome process of adding and connecting a data source to your application in Interface Builder.

Note that if you wish to connect an awake from nib handler to a data source, you will have to add and connect the data source in Interface Builder. The steps for doing so are described in AppleScript Studio Programming Guide, available in Xcode help. See the chapter in the Mail Search tutorial on connecting the interface.

The view element was added in AppleScript Studio version 1.1.
outline view
Plural: outline views
Inherits from: table view
Cocoa Class: NSOutlineView

A view that uses a row-and-column format to display hierarchical data that can be expanded and collapsed, such as directories and files in a file system.

A user can expand and collapse rows, edit values, and resize and rearrange columns.

Figure 5-4 shows an outline view that displays a hierarchy of files and folders.


Figure 5-4  An outline view

An outline view

You will find the outline view object on the Cocoa-Data pane in Interface Builder’s Palette window. You can set many attributes for outline views in Interface Builder’s Info window.

Although AppleScript Studio provides event handlers for managing the data an outline view displays, the preferred and far more efficient approach is to use a data source object.

For more information on outline views, see the document Outline View Programming Topics for Cocoa.

Properties of outline view objects

In addition to the properties it inherits from the table view class, an outline view object has these properties:

auto resizes outline column
 Access:read/write
 Class:boolean
 Should the outline column be automatically resized? default is false; you can set this property in the Info window in Interface Builder
auto save expanded items
 Access:read/write
 Class:boolean
 not supported (through AppleScript Studio version 1.4); Should the expanded state of the outline items be automatically saved? default is false
clicked data item
 Access:read only
 Class:data item
 the data item that was clicked; available in AppleScript Studio version 1.3; returns missing value if no item was clicked, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
edited data item
 Access:read only
 Class:data item
 the data item that was edited; available in AppleScript Studio version 1.3; returns missing value if no item was edited, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
selected data item
 Access:read/write
 Class:data item
 the selected data item; available in AppleScript Studio version 1.3; returns missing value if no item was selected, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
selected data items
 Access:read/write
 Class:list
 the selected data items; available in AppleScript Studio version 1.3; returns missing value if no item was selected, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
indentation per level
 Access:read/write
 Class:real
 the amount to indent per level; default is 16.0
marker follows cell
 Access:read/write
 Class:boolean
 Should the marker follow the cells (that is, as the cells in the outline view are indented, should the disclosure triangle also be indented)? default is true;
outline table column
 Access:read/write
 Class:table column
 the table column that contains the outline


Elements of outline view objects

An outline view object can contain only the elements it inherits from table view.

Commands supported by outline view objects

Your script can send the following commands to an outline view object:

item for
update

Events supported by outline view objects

An outline view object supports handlers that can respond to the following events:

Action
clicked
double clicked

Data View

Through Mac OS X version 10.5, an outline view object does not respond to the following Data View suite events—you can connect handlers for these events in Interface Builder, but they will not be called:

column clicked
column moved
column resized
selection changed
selection changing
should select column
should select item
should select row
should selection change
will display cell

Drag and Drop
accept table drop
conclude drop
drag
drag entered
drag exited
drag updated
drop
prepare drop

Key
keyboard down
keyboard up

Mouse
mouse down
mouse dragged
mouse entered
mouse exited
mouse up
right mouse down
right mouse dragged
right mouse up
scroll wheel

Nib
awake from nib

Outline View
accept table drop
change item value
child of item
item expandable
item value
item value changed
items changed
number of items
prepare outline drag
prepare outline drop
should collapse item
should expand item
will display item cell
will display outline cell

Table View
cell value
change cell value
number of rows

View
bounds changed

Examples

The following script statement shows how to identify an outline view and send it the update command.

tell outline view "outline" of scroll view "scroll"  of window "main" to update

Working with outline views is a complex task that can’t be covered in detail here. For a complete but relatively simple example, see the Examples section for the data item class. For a more detailed example, see the chapters in AppleScript Studio Programming Guide that describe how to build the Mail Search application (which is also distributed with AppleScript Studio).

Version Notes

The following event handlers were added in AppleScript Studio version 1.4:

The following properties were added in AppleScript Studio version 1.3:

Support for drag-and-drop commands was added in AppleScript Studio version 1.2.

The auto save expanded items property in this class is not supported, through AppleScript Studio version 1.4.

See the Version Notes section for the table view class (from which outline view inherits) for properties added in AppleScript Studio version 1.2 to support sorting.

Prior to AppleScript Studio version 1.1, the Mail Search application was named Watson.
table column
Plural: table columns
Inherits from: None.
Cocoa Class: NSTableColumn

Stores the display characteristics and identifier for a column in a table view or outline view.

The table column determines the height and width limits, resizability, and editability of its column in the table view or outline view. It also stores two cell objects: the header cell, which is used to draw the column header, and its data cell, used to draw the values for each row.

When you insert a table or outline view in Interface Builder, the view contains a table column object for each column. If the table or outline view will use a data source, you must specify either an identifier name or an AppleScript name for each column. For more information, see the identifier property and the Version Notes section for this class.

Important:  Make sure the AppleScript names you assign to table columns in Interface Builder are identical to the name property of a data column in the data source for the table view.

Starting in AppleScript Studio version 1.4, columns in a table view support sort indicators, as described in the table view class.

For more information, see table header cell and table header view, as well as the document Table View Programming Guide.

Properties of table column objects

A table column object has these properties:

data cell
 Access:read/write
 Class:data cell
 not supported (through AppleScript Studio version 1.4); the data cell for the column
editable
 Access:read/write
 Class:boolean
 Is the column editable? default is true; you can set this property in the Info window in Interface Builder
header cell
 Access:read/write
 Class:table header cell
 the header cell used to draw the header for the column
identifier
 Access:read/write
 Class:Unicode text
 the name used by the data source to identify a column; you can set this value in the Identifier field in the Attributes Pane of the Info window in Interface Builder; see the Version Notes section for this class for related information
maximum width
 Access:read/write
 Class:real
 the maximum width of the column; default is 1000; you can set this property in the Info window in Interface Builder
minimum width
 Access:read/write
 Class:real
 the minimum width of the column; you can set this property in the Info window in Interface Builder
resizable
 Access:read/write
 Class:boolean
 Is the column resizable? default is true; you can set this property in the Info window in Interface Builder
table view
 Access:read/write
 Class:table view
 the table view or outline view that contains the table column
width
 Access:read/write
 Class:real
 the width of the column


Elements of table column objects

A table column object has no elements.

Events supported by table column objects

A table column object supports handlers that can respond to the following events:

Nib
awake from nib

Examples

For an example that shows how to access properties of a table column, see the column clicked handler in the Examples section of the data source class. The Examples section for the table view class points to additional sample code and documentation for using table views, both with and without data sources.

Version Notes

Starting with AppleScript Studio version 1.2, and the version of Interface Builder released with Mac OS X version 10.2, you can name table columns in a table view or outline view using the Name field of the AppleScript pane in Interface Builder’s Info window. It is no longer necessary to enter the value in the Identifier field of the Attributes pane (although that is still supported for backward compatibility).

If you do specify an identifier name (rather than an AppleScript name) for a table column, it must match the name of the data column in your data source. Otherwise, starting in AppleScript Studio version 1.1, no data will be provided for that data column to draw.

The data cell property in this class is not supported, through AppleScript Studio version 1.4.
table header cell
Plural: table header cells
Inherits from: text field cell
Cocoa Class: NSTableHeaderCell

Used by a table header view to draw its column headers.

For more information, see table header view, as well as the document Table View Programming Guide.

Properties of table header cell objects

A table header cell object has only the properties it inherits from text field cell.


Events supported by table header cell objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

You don’t typically script a text field cell, which adds no properties or elements to its superclass, text field cell.
table header view
Plural: table header views
Inherits from: view
Cocoa Class: NSTableHeaderView

Used by a table view to draw headers over its columns and to handle mouse events in those headers.

For more information, see table view, as well as the document Table View Programming Guide.

Properties of table header view objects

In addition to the properties it inherits from the view class, a table header view object has these properties:

dragged column
 Access:read only
 Class:integer
 if the user is dragging a column, the one-based index of that column; otherwise -1
dragged distance
 Access:read only
 Class:real
 if the user is dragging a column, the column's horizontal distance from its original position, otherwise the value is meaningless
resized column
 Access:read only
 Class:integer
 if the user is resizing a column, the one-based index of that column; otherwise -1
table view
 Access:read/write
 Class:table view
 the table view that contains the table header view


Elements of table header view objects

A table header view object can contain only the elements it inherits from view.

Events supported by table header view objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

You don’t typically script a table header view.
table view
Plural: table views
Inherits from: control
Cocoa Class: NSTableView

A view that displays record-oriented data in a table, and allows the user to edit values and resize and rearrange columns.

A table view displays data for a set of related records, with rows representing individual records and columns representing the attributes of those records. If you use a data source object to provide data for the table view, the data source works with the view to automatically display the correct information as a user scrolls, resizes the window, reorders the columns, or otherwise changes the displayed rows and columns.

You will find the table view object on the Cocoa-Data pane in Interface Builder’s Palette window. When you insert a table view in a window, the table view is automatically enclosed in a scroll view. You can set many attributes for table views in Interface Builder’s Info window, but to do so, make sure you’ve double-clicked to select the table view, not its enclosing scroll view (with Interface Builder’s Info window open to the AppleScript pane, you should see “NSTableView” as the window title).

Figure 5-5 shows a table view in Interface Builder. The row and column information is temporary filler provided by Interface Builder. For more information, see the document Table View Programming Guide.


Figure 5-5  A table view in Interface Builder

A table view in Interface Builder

Although AppleScript Studio provides event handlers for managing the data a table view displays, the preferred and far more efficient approach is to use a data source object to provide data. The Examples section for this class points to sample code and documentation for using table views both with and without data sources.

For additional information on working with table views, see the Version Notes section for this class.

Properties of table view objects

In addition to the properties it inherits from the control class, a table view object has these properties (see the Version Notes section for this class for the AppleScript Studio version in which a particular property was added):

allows column reordering
 Access:read/write
 Class:boolean
 Can the columns be reordered? default is true; you can set this property in the Info window in Interface Builder; if you connect a column clicked handler for a table view, the handler will not be called unless the value of this property is true
allows column resizing
 Access:read/write
 Class:boolean
 Can the columns be resized? default is true; you can set this property in the Info window in Interface Builder
allows column selection
 Access:read/write
 Class:boolean
 Can columns be selected? default is true; you can set this property in the Info window in Interface Builder
allows empty selection
 Access:read/write
 Class:boolean
 Should the table view allow an empty selection? default is true; you can set this property in the Info window in Interface Builder
allows multiple selection
 Access:read/write
 Class:boolean
 Should the table view allow multiple selection? default is false; you can set this property in the Info window in Interface Builder
allows reordering
 Access:read/write
 Class:boolean
 Can the columns be reordered? default is false; you cannot set this property in Interface Builder; if you set this property to true in your application, a user can drag rows up and down within the table, in effect changing the order; if the table view’s data source is sorted, the allows reordering property is ignored
auto resizes all columns to fit
 Access:read/write
 Class:boolean
 Should the columns automatically be resized to fit? default is false; you can set this property in the Info window in Interface Builder
auto save name
 Access:read/write
 Class:Unicode text
 the name used for automatically saving information about the table’s columns (see auto save table columns property); default is no name; you can set this property in the Info window in Interface Builder
auto save table columns
 Access:read/write
 Class:boolean
 not supported (through AppleScript Studio version 1.4); Should the order and width of the table columns be automatically saved? default is false; when you supply a name for the auto save name property in the Info window in Interface Builder, this property is automatically set to true
background color
 Access:read/write
 Class:RGB color
 the background color for the table view; a three-item integer list that contains the values for each component of the color; for example, red can be represented as {65535,0,0}; by default, {65535, 65535, 65535}, or white; you can set this property in the Info window in Interface Builder
clicked column
 Access:read only
 Class:integer
 the one-based index of the column that was clicked to trigger an event handler; value is 0 if no event occurred; the return value of this method is meaningful only in the clicked or double clicked event handlers
clicked data column
 Access:read only
 Class:data column
 the data column that was clicked; allows you to get the clicked data column object directly and regardless of sorted state; returns nil if no column was clicked, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
clicked data row
 Access:read only
 Class:data row
 the data row that was clicked; allows you to get the data row object directly and regardless of sorted state; returns nil if no row was clicked, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
clicked row
 Access:read only
 Class:integer
 the one-based index of the row that was clicked to trigger an event handler; value is 0 if no event occurred; the return value of this method is meaningful only in the clicked or double clicked event handlers
content
 Access:read/write
 Class:item
 the contents of the table or outline view; nearly synonymous with contents; for related information, see the Version Notes section for this class
contents
 Access:read/write
 Class:item
 the contents of the table or outline view; nearly synonymous with content; for related information, see the Version Notes section for this class
corner view
 Access:read/write
 Class:anything
 the corner view (the view used to draw the area to the right of the column headers and above the vertical scroller of the enclosing scroll view; this is by default a simple view that merely fills in its frame, but you can replace it with a custom view)
dragged items
 Access:read only
 Class:list
 the items currently being dragged
draws grid
 Access:read/write
 Class:boolean
 Should the table view draw its grid? default is false; you can set this property in the Info window in Interface Builder
edited column
 Access:read only
 Class:integer
 the one-based index of the column being edited; value is 0 if no column is being edited
edited data column
 Access:read only
 Class:data column
 the data column being edited; allows you to get the data column object directly and regardless of sorted state; value is nil if no column is being edited, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
edited data row
 Access:read only
 Class:data row
 the data row being edited; allows you to get the data row object directly and regardless of sorted state; value is nil if no row is being edited, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
edited row
 Access:read only
 Class:integer
 the one-based index of the row being edited; value is 0 if no row is being edited
grid color
 Access:read/write
 Class:RGB color
 the color of the grid; a three-item integer list that contains the values for each component of the color; for example, green can be represented as {0,65535,0}; default is {32767, 32767, 32767} (or gray); you can set this property in the Info window in Interface Builder
header view
 Access:read/write
 Class:table header view
 the table header view used to draw headers over columns; returns nil if the table has no header view, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
intercell spacing
 Access:read/write
 Class:list
 the space between cells; represented as a two-item list of numbers
row height
 Access:read/write
 Class:real
 the height of the row
selected column
 Access:read/write
 Class:integer
 the one-based index of the selected column; 0 if no column is selected; if allows column selection is true but allows multiple selection is false, you can evaluate this property to obtain the index of the selected column, if any
selected columns
 Access:read/write
 Class:list
 the one-based index of every selected column; an empty list if no column is selected; if allows column selection is true and allows multiple selection is true, you can use this property to determine the selected columns
selected data column
 Access:read/write
 Class:data column
 the data column that is selected; there will be no selected data column unless allows multiple selection is true; returns nil if no data column was selected, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
selected data columns
 Access:read/write
 Class:list
 the data columns that are selected; returns an empty list if no data columns are selected; if allows multiple selection is false, the returned list will contain at most one data column
selected data row
 Access:read/write
 Class:data row
 the data row that is selected; if allows multiple selection is false, you can use this property to obtain the selected data row—otherwise use the selected data rows property; returns nil if no data row was selected, so you should only access the value in a try, on error block (for an example of a try, on error block, see the Examples section of the path for command)
selected data rows
 Access:read/write
 Class:list
 the data rows that are selected; returns an empty list if no data rows are selected; if allows multiple selection is false, the returned list will contain at most one data row
selected row
 Access:read/write
 Class:integer
 the one-based index of the selected row; if allows multiple selection is false, you can check this property for the selected row
selected rows
 Access:read/write
 Class:list
 the one-based index of every selected row; if allows multiple selection is true, you can check this property for the selected rows
use sort indicators
 Access:read/write
 Class:boolean
 Should table columns use sort indicators? default is false


Elements of table view objects

In addition to the properties it inherits from the control class, a table view object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

data source
 Specify by: “Standard Key Forms”
 

the data source that supplies data for the table; a table view can have either no data sources or one data source; you do not need an index to refer to the data source: set theDataSource to data source of table view 1 of scroll view 1 of window 1

table column
 Specify by: “Standard Key Forms”
 

the tables columns, which store the display characteristics and identifier for each column


Commands supported by table view objects

Your script can send the following commands to a table view:

update

Events supported by table view objects

A table view supports handlers that can respond to the following events:

Action
clicked
double clicked

Data View
column clicked
column moved
column resized
selection changed
selection changing
should select column
should select row
should selection change
will display cell

Drag and Drop
conclude drop
drag
drag entered
drag exited
drag updated
drop
prepare drop

Key
keyboard down
keyboard up

Mouse
mouse down
mouse dragged
mouse entered
mouse exited
mouse up
right mouse down
right mouse dragged
right mouse up
scroll wheel

Nib
awake from nib

Table View
accept table drop
cell value
cell value changed
change cell value
number of rows
prepare table drag
prepare table drop
rows changed

View
bounds changed

Examples

The following script statements show how to identify a table view and send it the update command. The object names used in this example match those in the Table sample application distributed with AppleScript Studio.

set theTableView to table view "contacts" of scroll view  "contacts" of window  "main"
tell theTableView to update

You can use statements like the following to set the selected rows in the table view. The first statement sets a property to allow multiple selection in the table view; the second statement selects the first and fourth rows of the table view:

set allows multiple selection of theTableView to true
set selected rows of theTableView to {1, 4}

You can use the similar statements to set the selected columns in the table view. In the following example, the second statement sets a property to allow column selection in the table view; the third statement selects the second and third columns in the table view:

set allows multiple selection of theTableView to true
set allows column selection of theTableView to true
set selected columns of theTableView to {2, 3}

To get information from a named data cell in a data row of a table view with a data source, you can use statements like those in the following clicked handler, connected to the table view.

on clicked theObject
    set rowIndex to clicked row of theObject
    if rowIndex is greater than 0 then
        set dataSource to data source of theObject
        set theRow to data row rowIndex of dataSource
        set theName to contents of data cell "name" of  theRow
    end if
end clicked

Working with table views is a complex task that can’t be covered fully here. For a complete example, see the Table sample application. The application demonstrates two mechanisms for working with table views. The preferred mechanism, which makes use of a data source object to manage the table’s data, is shown in the script file WithDataSource.applescript. A less efficient mechanism, which may be adequate for very simple tables, is shown in the file WithoutDataSource.applescript.

For a more detailed example, see the chapters in AppleScript Studio Programming Guide that describe how to build the Mail Search application (which is also distributed with AppleScript Studio).

The following examples are valid starting with AppleScript Studio version 1.4. The script statements in Listing 5-1 create three data rows in the first column of the specified table.

Listing 5-1  A simple example of setting data rows with the content property

set tableView to table view 1 of scroll view 1 of window 1
set content of tableView to {"One", "Two", "Three"}

Given a table view with three columns, you can add two rows populated based on index position, using the statement shown in Listing 5-2.

Listing 5-2  Setting the data for two data rows with three columns

set content of tableView to {{"Red", "Green",  "Blue"}, {"Black", "White",  "Gray"}}

Listing 5-3 shows how to create two data rows and assign the column values based on the specified column names.

Listing 5-3  Setting data rows based on column names

set content of tableView to {{|name|: "John Smith", |phone|:"222-555-3456"},  {|name|: "Paul Jones", |phone|:"123-456-7890"}}

Note that it wasn’t necessary to create the data source, data columns or data rows. If the table view doesn't have the necessary data items, it will create them automatically. In this example, a data source, two data columns (named “name” and “phone”), and two data rows are created automatically.

Discussion

It is important to make sure that the AppleScript names you assign to table columns in Interface Builder must be identical to the name property of a data column in the data source for the table view.

Version Notes

Starting in AppleScript Studio version 1.4, columns in a table view support sort indicators. You can turn the indicators on or off by setting the use sort indicators boolean property of the table view class. Setting the boolean only controls the presence of sort indicators. To actually sort a column, your application must detect a click in a table column and change the sort order.

Also starting in AppleScript Studio version 1.4, your application can can access the data rows of a table view in their sorted order by using the sorted data rows property of the table view’s data source.

Prior to AppleScript Studio version 1.4, table views could be scripted either by using a data source or by using various event handlers. If you used the event handlers, you couldn't use the data source. In AppleScript Studio version 1.4, you can mix and match data sources and specific event handlers, providing a balance of performance and flexibility.

The following event handlers were added in AppleScript Studio version 1.4:

The following properties were added to the table view class in AppleScript Studio version 1.4:

You can use content and contents interchangeably, with one exception. Within an event handler, contents of theObject returns a reference to an object, rather than the actual contents. To get the actual contents of an object (such as the text contents from a text field) within an event handler, you can either use contents of contents of theObject or content of theObject.

For a sample script that shows the difference between content and contents, see the Version Notes section for the control class.

Support for drag-and-drop commands was added in AppleScript Studio version 1.2.

The following properties were added to the table view class (and are therefore also available to its subclass, the outline view class) in AppleScript Studio version 1.2:

These properties return the appropriate elements regardless of their sorted state and should be used in place of their non-sorted counterparts (edited column, edited row, and so on).

The auto save table columns property in this class is not supported, through AppleScript Studio version 1.4.

Because of a bug fix in Cocoa Scripting in Mac OS X version 10.2, it is possible, starting in AppleScript Studio version 1.2, to set a property that is a list to a new list. For instance you can specify a list to select the rows in a table view, as shown in the Examples section for this class.

Starting with AppleScript Studio version 1.1, the behavior of table views and data sources was changed as follows: if the name you set for a table column in the Identifier field of the Attributes pane in Interface Builder does not match the name of the data column in your data source, no data will be provided for that data column to draw.

However, starting with AppleScript Studio version 1.2, and the version of Interface Builder released with Mac OS X version 10.2, you can name table columns in a table view using the Name field of the AppleScript pane in Interface Builder’s Info window. Use of an identifier name is still supported for backward compatibility.

Prior to AppleScript Studio version 1.1, the Mail Search application was named Watson.

Commands

Objects based on classes in the Data View suite support the following commands. (A command is a word or phrase a script can use to request an action.) To determine which classes support which commands, see the individual class descriptions.

append

Appends the provided list of lists or list of records to a data source.

The data from each list or record provides the contents for the cells in one row of the data source. This command provides a simple, efficient mechanism for adding data to a data source associated with a view, such as an outline view or a table view.

If you supply a list of records, the append command will attempt to match the labels for the fields of each record with the data column identifiers. For each label that matches a column identifier, it inserts the data from that field into the matching column. If no record label matches the identifier for a column, that column is left blank.

If you supply a list of lists, the append command will match the items in each list to the corresponding column, by index. That is, the data for the first item goes in the first column, and so on.

Starting with AppleScript Studio version 1.3, the append command accepts a simple list of items.

Syntax
append data source required
 with list required
Parameters
data source

the data source to append data to

with  list

a list of lists or list of records to append to the specified data source

Examples

The following awake from nib handler is from the Table Sort sample application distributed with AppleScript Studio (available starting with version 1.2). This handler, which is connected to a table view, does the following:

on awake from nib theObject
    -- Create the data source; this places it in the application
    --  object’s data source elements. (Assign it to table view  below.)
    set theDataSource to make new data source at end of data sources
        with properties {name:"names"}
 
    -- Create each of the data columns, including the sort information
    --   for each column
    make new data column at end of data columns of theDataSource
        with properties {name:"name", sort order:ascending,
        sort type:alphabetical, sort case sensitivity:case sensitive}
    make new data column at end of data columns of theDataSource
        with properties {name:"city", sort order:ascending,
        sort type:alphabetical, sort case sensitivity:case sensitive}
    make new data column at end of data columns of theDataSource
        with properties {name:"zip", sort order:ascending,
        sort type:alphabetical, sort case sensitivity:case sensitive}
    make new data column at end of data columns of theDataSource
        with properties {name:"age", sort order:ascending,
        sort type:numerical, sort case sensitivity:case sensitive}
 
    -- Make this a sorted data source
    set sorted of theDataSource to true
 
    -- Set the "name" data column as the sort column
    set sort column of theDataSource to data column "name"  of theDataSource
 
    -- Set the data source of the table view to the new data source
    set data source of theObject to theDataSource
 
    -- Add the table data (using the new "append" command)
    append theDataSource with tableData
end awake from nib

The following is the tableData property defined in the Table Sort application. The “name” field is enclosed in vertical bars to differentiate it from any similarly-named key words:

property tableData : {{|name|:"Bart Simpson", city:"Springfield", zip:"19542", age:12}, {|name|:"Ally McBeal", city:"Boston", zip:"91544", age:28}, {|name|:"Joan of Ark", city:"Paris", zip:"53255", age:36}, {|name|:"King Tut", city:"Egypt", zip:"00245", age:45}, {|name|:"James Taylor", city:"Atlanta", zip:"21769", age:42}}

You can also get the data back out of a data source (as a list of lists) with terminology like the following (where theDataSource specifies a data source):

set myList to contents of every data cell of every data row of theDataSource

Starting with AppleScript Studio version 1.3, the append command accepts a simple list of items. For example, if you have a single column table view, you can say append the data source of table view 1 of window 1 with {"One", "Two", "Three"}.

Version Notes

Starting with AppleScript Studio version 1.4, you can use the append command to append a list of strings to a table view, or a list of lists, or a list of records.

Starting with AppleScript Studio version 1.3, the append command accepts a simple list of items.

The append command was added in AppleScript Studio version 1.2.

item for

Returns the data item for the specified row (base 1) of a data source.

A data item represents one, possibly expandable, row of the data source.

This command works only for an outline view.

Syntax
item for outline view required
 row integer required
Parameters
outline view

the outline view from which to get the item for the specified row

row  integer

the one-based index of the row of the outline view from which to get the item

Result
data item

The data item for the specified row of the outline view. Returns no result if the row is out of range.

Examples

The following script statements are from the mailboxesForIndex handler in the Mail Search sample application distributed with AppleScript Studio. Among other things, the Mail Search application uses an outline view to display account items, each of which may have multiple mailboxes. A mailbox, in turn, has a mailbox name and may contain nested mailboxes. The mailboxesForIndex handler uses the item for command to obtain a row at a specified index, then obtains data (the name of the mailbox at that row) from the first data cell of that item.

    -- Determine if the selected item is an account or a mailbox
    tell outline view "mailboxes" of scroll view "mailboxes"
        of split view 1 of theWindow
            set theItem to item for row mailboxIndex
            set theName to contents of data cell 1 of theItem
            -- some statements omitted
    end tell

Events

Objects based on classes in the Data View suite support handlers for the following events (an event is an action, typically generated through interaction with an application’s user interface, that causes a handler for the appropriate object to be executed). To determine which classes support which events, see the individual class descriptions.

accept outline drop

Called when a drop has occurred in an outline view. Returns a boolean value specifying whether to accept or reject the drop.

All of the parameters of this handler will have values when the handler is called.

Syntax
accept outline drop reference required
 child index unsigned integer required
 data item anything required
 drag info drag info required
Parameters
reference

a reference to the outline view whose accept outline drop handler is called

child index  unsigned integer

the one-based index of the child data item of the data item

data item  anything

the data item that will accept the drop

drag info  drag info

information about the drag operation

Result
boolean

Return true if the outline view accepts the drop, false if it does not.

Examples

When you connect an accept outline drop handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following.

on accept outline drop theObject data item dataItem drag info dragInfo  child index  childIndex
    (* Statements to deal with the drop. *)
end drag updated

In your handler, you decide whether to accept the drop and return the appropriate boolean value (true if you accept the drop, false otherwise). If you accept the drop, you should handle it in this routine, or in a routine it calls. To handle a drop, you might use steps like the following:

For an example of a handler that demonstrates these steps, see the Simple Outline application distributed with AppleScript Studio version 1.4.

Version Notes

The accept outline drop event handler was added in AppleScript Studio version 1.4.

accept table drop

Called when a drop has occurred in a table view. Returns a boolean value specifying whether to accept or reject the drop.

All of the parameters of this handler will have values when the handler is called.

Syntax
accept table drop reference required
 drag info drag info required
 drop operation integer required
 row unsigned integer required
Parameters
reference

a reference to the table view whose accept table drop handler is called

drag info  drag info

information about the drag operation

drop operation  integer

the type of drop operation, 0 = on the designated row, 1 = above the designated row

row  unsigned integer

the one-based index of the row for the drop operation

Result
boolean

Return true if the table view accepts the drop, false if it does not.

Examples

When you connect an accept table drop handler to a table view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. (The parameter order doesn’t match the order in the syntax table above, which is alphabetical to match the display of AppleScript dictionaries.)

on accept table drop theObject drag info dragInfo row theRow operation  dropOperation
    (* Statements to deal with the drop. *)
end drag updated

In your handler, you decide whether to accept the drop and return the appropriate boolean value (true if you accept the drop, false otherwise). If you accept the drop, you should handle it in this routine, or in a routine it calls.

For an example of a accept table drop handler, see the Simple Table application distributed with AppleScript Studio version 1.4.

Version Notes

The accept table drop event handler was added in AppleScript Studio version 1.4.

cell value

Called for a table or outline view to get the value of a cell.

The handler should return the value of the specified cell.

The preferred way to manipulate data for table view and outline view objects is to use a data source, in which case this handler is not needed (or called).

Syntax
cell value reference required
 row integer required
 table column table column required
Parameters
reference

a reference to the table view or outline view that contains the cell

row  integer

the one-based row of the cell

table column  table column

the column of the cell

Result
anything

The value of the cell at the specified row and column. If you implement this handler, you should always return a value.

Examples

The following cell value handler is from the Table sample application distributed with AppleScript Studio. It’s in the script file WithoutDataSource.applescript. (See the file WithDataSource.applescript for the preferred mechanism for working with tables, using a data source object.)

This handler:

on cell value theObject row theRow table column theColumn
    -- Set the value to an empty string for now
    set theValue to ""
 
    -- Make sure the row we’re asked for is within the number  of contacts
    if (count of contacts) ≥ theRow then
        set theContact to item theRow of contacts
 
        -- Get the column identifier to determine which field
        --  of the record to return
        set theID to identifier of theColumn
        if theID is "name" then
            set theValue to name of theContact
        else if theID is "address" then
            set theValue to address of theContact
        else if theID is "city" then
            set theValue to city of theContact
        else if theID is "state" then
            set theValue to state of theContact
        else if theID is "zip" then
            set theValue to zip of theContact
        end if
    end if
 
    -- Now return the value that we set
    return theValue
end cell value
cell value changed

Called when a user edits a cell in a table or outline view.

Syntax
cell value changed reference required
 row unsigned integer required
 table column table column required
 value anything required
Parameters
reference

a reference to the table view or outline view

row  unsigned integer

the one-based row of the cell that changed

table column  table column

the column of the cell that changed

value  anything

the value of the cell that changed

Examples

When you connect a cell value changed handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should perform any operations required by the change in cell value.

on cell value changed theObject table column tableColumn old width  oldWidth
    if width of tableColumn is not equal to oldWidth then
    (* Add statements to perform any operations required after change
        of column width. *)
    end if
end cell value changed
Version Notes

The cell value changed event handler was added in AppleScript Studio version 1.4.

change cell value

Called for a table or outline view to change the value of a cell.

The preferred way to manipulate data for table view and outline view objects is to use a data source, in which case this handler is not needed (or called).

Syntax
change cell value reference required
 row integer required
 table column table column required
 value item required
Parameters
reference

a reference to the table view or outline view that contains the cell

row  integer

the one-based row of the cell to change

table column  table column

the column of the cell to change

value  item

the new value

Examples

When you connect a change cell value handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler should set the cell in the specified row and column to the specified value.

on change cell value theObject value theValue row theRow table column  tableColumn
    (*Set the specified cell to the passed value. *)
end change cell value
Version Notes

Prior to AppleScript Studio version 1.4, you could assign the change cell value handler, but it wasn’t called. Starting in Studio version 1.4, it is called.

change item value

Called for an outline view to change the value of an item at a specified row.

The preferred way to manipulate data for an outline view is to use a data source, in which case this handler is not needed (or called).

Syntax
change item value reference required
 outline item item required
 table column table column required
 value item required
Parameters
reference

a reference to the outline view that contains the item

outline item  item

The item to change the value for.

table column  table column

The column of the item to change.

value  item

The new value to change to.

Examples

When you connect a change item value handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler should set the specified item to the specified value.

on change item value theObject value theValue outline item outlineItem  table  column tableColumn
    (*Set the specified item to the passed value. *)
end change item value
child of item

Called for an outline view to get a specified child item from an item.

Although AppleScript Studio provides event handlers for managing the data an outline view displays, such as getting the child of an item, the preferred and far more efficient approach is to use a data source object.

Syntax
child of item reference required
 outline item item required
 child integer optional
Parameters
reference

a reference to the outline view that contains the items

outline item  item

the item that contains the child item; typically a one-based index or a string

child  integer

the one-based index of the child of the given child

Result
anything

The handler should return the specified child of the specified outline item.

Examples

The following child of item event handler is from the Outline sample application distributed with AppleScript Studio. Outline uses an outline view to display items in the file system. This handler:

on child of item theObject outline item outlineItem child theChild
    set childItem to ""
 
    tell application "Finder"
        if outlineItem is 0 then
            set childItem to disk (get item theChild
                of diskNames as string) as string
        else
            set childItem to item theChild of (get item outlineItem)
                as string
        end if
    end tell
 
    return childItem
end child of item
column clicked

Called for a table or outline view when a column is clicked.

The handler can perform operations such as setting column-sorting properties of a data source object.

This handler will not be called unless the table or outline view that contains the column allows column reordering (either the Allows Reordering checkbox for the table or outline view is selected on the Attributes pane of Interface Builder’s Info window, or you set the allows column reordering property to true in an application script).

Syntax
column clicked reference required
 table column table column required
Parameters
reference

a reference to the table view or outline view

table column  table column

the column that was clicked

Examples

For an example of a column clicked handler, see the Examples section of the data source class.

column moved

Called for a table or outline view after a column moves, as when a user shuffles the rows in a table or outline view.

Syntax
column moved reference required
 new column integer required
 old column integer required
Parameters
reference

a reference to the table view or outline view

new column  integer

the zero-based index of the new column position

old column  integer

the zero-based index of the old column position

Examples

When you connect a column moved handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. The column parameters provide the indices of the new and old column positions. Your handler should perform any operations required by the changed column positions.

on column moved theObject new column newColumn old column oldColumn
    (* Respond to changed column position. *)
end column moved
column resized

Called for a table or outline view after a column is resized.

The new size may be the same as the old size.

Syntax
column resized reference required
 old width real required
 table column table column required
Parameters
reference

a reference to the table view or outline view

old width  real

the previous width of the column

table column  table column

the column that may have been resized

Examples

When you connect a column resized handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should perform any operations required by the change in column size, possibly after first determining if the column width actually changed.

on column resized theObject table column tableColumn old width oldWidth
    if width of tableColumn is not equal to oldWidth then
    (* Add statements to perform any operations required after change
        of column width. *)
    end if
end column resized
item expandable

Called for an outline view to find out if the specified item is expandable.

The handler returns true if the item is expandable, false if it is not.

The preferred way to provide data for an outline view is to use a data source, in which case this handler is not needed (or called).

Syntax
item expandable reference required
 outline item item optional
Parameters
reference

a reference to the outline view that contains the item

outline item  item

the item that may be expandable

Result
boolean

Returns false if the item is not expandable or true if it is. If you implement this handler, you should always return a boolean value.

Examples

The following item expandable event handler is from the Outline sample application distributed with AppleScript Studio. Outline uses an outline view to display items in the file system. This handler:

on item expandable theObject outline item outlineItem
    set isExpandable to false
 
    if outlineItem is 0 then
        if (count of diskNames) is greater than 1 then
            set isExpandable to true
        end if
    else
        tell application "Finder"
            if (count of items of (get item outlineItem))
                    is greater than 1 then
                set isExpandable to true
            end if
        end tell
    end if
 
    return isExpandable
end item expandable
item value

Called for an outline view to get the value for an item.

The handler returns the value (typically as a string) to be displayed for the specified item.

The preferred way to provide data for an outline view is to use a data source, in which case this handler is not needed (or called).

For outline views that do not use a data source, this event handler is called once for each currently displayed row in each column. For example, if an outline view displays a file system hierarchy in three columns, one each for the name, date modified, and size for each item, the outline view will call the item value handler three times for each displayed item (once for the name column, once for the modification date, and once for the size).

The handler is not called for collapsed rows that are not visible.

Syntax
item value reference required
 outline item item optional
 table column table column required
Parameters
reference

a reference to the outline view that contains the item

outline item  item

the item to get the value for

table column  table column

the column of the item

Result
Anything

The value of the specified item; typically returned as a string.

Examples

The following item value event handler is from the Outline sample application distributed with AppleScript Studio. Outline uses an outline view to display items in the file system. This handler uses the column identifier to determine which kind of value to return for the item. It then calls on the Finder application to obtain the value (either a name, date, or a kind) and returns the value as a string.

on item value theObject outline item theItem table column theColumn
    set itemValue to ""
 
    if the identifier of theColumn is "name" then
        tell application "Finder"
            set itemValue to displayed name of (get item theItem)
                as string
        end tell
    else if the identifier of theColumn is "date" then
        tell application "Finder"
            set itemValue to modification date of
                (get item theItem) as string
        end tell
    else if the identifier of theColumn is "kind" then
        tell application "Finder"
            set itemValue to kind of (get item theItem) as string
        end tell
    end if
 
    return itemValue
end item value
item value changed

Called when the user edits a cell in an outline view.

Syntax
item value changed reference required
 table column table column required
 value anything required
 outline item anything required
Parameters
reference

a reference to the outline view in which the item value changed

table column  table column

the column of the item that changed

value  anything

the value of the item that changed

outline item  anything

the item that changed

Examples

When you connect a item value changed handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should perform any operations required by the change in item value.

on item value changed theObject table column tableColumn value theValue  outline  item outlineItem
    (* Perform any operations to deal with change to item value.
end item value changed
Version Notes

The item value changed event handler was added in AppleScript Studio version 1.4.

items changed

Called when the items in an outline view change.

Syntax
items changed reference required
Parameters
reference

a reference to the outline view for which the items changed

Examples

When you connect an items changed handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler should perform any operations required by the changed items.

on items changed theObject
    (* Perform operations based on the changes. *)
end items changed
Version Notes

The items changed event handler was added in AppleScript Studio version 1.4.

number of browser rows

Called to obtain the number of rows in a browser view for the specified column.

Unlike other data views such as outline view and table view, you currently cannot supply data to a browser view with a data source. As a result, performance may be inadequate for browser views that display more than a small number of items, and you should consider using one of the other data views, if suitable for your purpose.

Syntax
number of browser rows reference required
 in column integer required
Parameters
reference

a reference to the browser object for which to obtain the number of rows

in column  integer

the one-based index of the column

Result
integer

Returns the number of rows in the specified column of the browser.

Examples

The following number of browser rows handler is from the Browser application distributed with AppleScript Studio. The Browser application browses the file system, displaying files and folders in a window similar to the Finder’s column view. This handler:

on number of browser rows theObject in column theColumn
    set rowCount to 0
 
    if (count of diskNames) > 0 then
        if theColumn is 1 then
            set rowCount to count of diskNames
        else
            tell browser "browser" of window "main"
                set thePath to path for column theColumn - 1
            end tell
 
            tell application "Finder"
                set rowCount to count of items of item thePath
            end tell
        end if
    end if
 
    return rowCount
end number of browser rows
number of items

Called for an outline view to obtain the number of child items of the specified item.

The preferred way to provide data for an outline view is to use a data source, in which case this handler is not needed (or called).

Syntax
number of items outline view required
 outline item item optional
Parameters
reference

a reference to the outline view that contains the items

outline item  item

the item for which to obtain the number of contained items

Examples

The following number of items handler is from the Outline application distributed with AppleScript Studio. Outline uses an outline view to display items in the file system. This handler uses the Finder application to count the number of file system items in the specified item. This process is described in more detail in the Examples sections for the item expandable and number of browser rows commands.

on number of items theObject outline item outlineItem
    set itemCount to 0
 
    tell application "Finder"
        if (count of diskNames) > 0 then
            if outlineItem is 0 then
                set itemCount to count of diskNames
            else
                set itemCount to count of items of (get item outlineItem)
            end if
        end if
    end tell
 
    return itemCount
end number of items
number of rows

Called for a table or outline view to get the number of rows.

The preferred way to manipulate data for table view and outline view objects is to use a data source, in which case this handler is not needed (or called).

Syntax
number of rows reference required
Parameters
reference

a reference to the table view or outline view for which to obtain the number of rows

Examples

The following number of rows handler is from the Table sample application distributed with AppleScript Studio. You will find it in the script file WithoutDataSource.applescript. Table demonstrates how to work with data displayed as rows and columns in a table view. Note, however, that although you can work with the data in a table view without a data source object, as in this method, the preferred and far more efficient approach is to use a data source. The Table application demonstrates that approach, which doesn’t require a number of rows handler, in the project script file WithDataSource.applescript.

The following handler just returns the count of contacts in a global script property, since there is one row per contact.

on number of rows theObject
    return count of contacts
end number of rows
prepare outline drag

Called when a drag is about to start in an outline view. Returns a boolean value specifying whether to continue the drag.

Your application uses this handler to prepare for an outline drag. For example, your handler should set the preferred type of the pasteboard to “items” and set the content of the pasteboard to the items being dragged. For an example of how to do this, see the Simple Outline sample application distributed with AppleScript Studio version 1.4.

All of the parameters of this handler will have values when the handler is called.

Syntax
prepare outline drag reference required
 data items list required
 pasteboard drag info required
Parameters
reference

a reference to the outline view whose prepare outline drag handler is called

data items  list

the data items that will be used in the drag operation

pasteboard  pasteboard

the pasteboard where data is placed for the drag operation

Result
boolean

Return true to continue the drag, false to cancel it.

Examples

When you connect a prepare outline drag handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following.

on prepare outline drag theObject drag items dragItems pasteboard  thePasteboard
    (* Statements to deal with the drag. *)
end prepare outline drag

In your handler, you decide whether to prepare the drop and return the appropriate boolean value (true if you prepare the drop, false otherwise). If you prepare the drop, you should handle it in this routine, or in a routine it calls.

For an example of a accept table drop handler, see the Simple Outline application distributed with AppleScript Studio version 1.4.

Version Notes

The prepare outline drag event handler was added in AppleScript Studio version 1.4.

prepare outline drop

Called during a drag when an outline view should prepare for a possible drop. The handler returns the type of drag operation (such as a move or copy drag operation).

Your application uses this handler to prepare for a drop in an outline view. It returns one of the enumerated values from Drag Operation.

For example, your handler might set the preferred type of the pasteboard to “items” and set the content of the pasteboard to the items being dragged. For an example of how to do this, see the Simple Outline sample application distributed with AppleScript Studio version 1.4.

All of the parameters of this handler will have values when the handler is called.

Syntax
prepare outline drop reference required
 child index unsigned integer required
 data item anything required
 drag info drag info required
Parameters
reference

a reference to the outline view whose prepare outline drop handler is called

child index  unsigned integer

the one-based index of the child data item of the data item

data item  anything

the data item that will accept the drop

drag info  drag info

information about the drag operation

Result
enumerated constant from Drag Operation

Return a value that specifies the type of drag operation, such as move drag operation.

Examples

When you connect a prepare outline drop handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following.

on prepare outline drop theObject data item dataItems dragItems  drag info  dragInfo child index childIndex
    (* Statements to deal with the drop. *)
end prepare outline drop

In your handler, you determine which type of drag operation is under way and return the corresponding constant value from Drag Operation.

For an example of a prepare outline drop handler, see the Simple Outline application distributed with AppleScript Studio version 1.4.

Version Notes

The prepare outline drag event handler was added in AppleScript Studio version 1.4.

prepare table drag

Called when a drag is about to start in a table view. Returns a boolean value specifying whether to continue the drag.

Your application uses this handler to prepare for a table drag. For example, your handler should set the preferred type of the pasteboard to “items” and set the content of the pasteboard to the items being dragged.

All of the parameters of this handler will have values when the handler is called.

Syntax
prepare table drag reference required
 drag rows list required
 pasteboard drag info required
Parameters
reference

a reference to the table view whose prepare outline drag handler is called

drag rows  list

a list of indexes for the rows to be dragged

pasteboard  pasteboard

the pasteboard where data is placed for the drag operation

Result
boolean

Return true to continue the drag, false to cancel it.

Examples

When you connect a prepare table drag handler to an table view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following.

on prepare table drag theObject drag rows dragRows pasteboard thePasteboard
    (* Statements to deal with the drag. *)
end prepare outline drag

For an example of a prepare table drag handler, see the Simple Table application distributed with AppleScript Studio version 1.4.

Version Notes

The prepare table drag event handler was added in AppleScript Studio version 1.4.

prepare table drop

Called during a drag when a table view should prepare for a possible drop. The handler returns the type of drag operation (such as a move or copy drag operation).

Your handler should set the preferred type of the pasteboard to (for example, to “items”) and set the content of the pasteboard to the items being dragged. It should return one of the enumerated values from Drag Operation to indicate the type of operation under way.

All of the parameters of this handler will have values when the handler is called.

Syntax
prepare table drop reference required
 drag info drag info required
 drop operation integer required
 row unsigned integer required
Parameters
reference

a reference to the table view whose prepare table drop handler is called

drag info  drag info

information about the drag operation

drop operation  integer

the type of drop operation, 0 = on the designated row, 1 = above the designated row

row  unsigned integer

the one-based index of the row for the drop operation

Result
enumerated constant from Drag Operation

Return a value that specifies the type of drag operation, such as move drag operation.

Examples

When you connect a prepare table drop handler to a table view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following.

on prepare table drop theObject drag info dragInfo row theRow drop  operation  dropOperation
    (* Statements to deal with the drop. *)
end prepare table drop

In your handler, you determine which type of drag operation is under way and return the corresponding constant value from Drag Operation. For an example how to do this, see the Simple Table application distributed with AppleScript Studio version 1.4.

Version Notes

The prepare table drop event handler was added in AppleScript Studio version 1.4.

rows changed

Called when the rows in a table view change.

Syntax
rows changed reference required
Parameters
reference

a reference to the table view for which the rows changed

Examples

When you connect an rows changed handler to a table view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler can obtain information from the table view and use it to perform any operations required by the changed rows.

on rows changed theObject
    (* Perform operations based on the changes. *)
end rows changed
Version Notes

The rows changed event handler was added in AppleScript Studio version 1.4.

should collapse item

Called for an outline view to determine if an item should be collapsed.

The handler returns true to allow collapsing of the item, false to disallow it.

Syntax
should collapse item outline view required
 outline item item optional
Parameters
reference

a reference to the outline view that contains the items that may be collapsed

outline item  item

the item

Result
boolean

Return true to allow the item to collapse; false to prevent collapsing. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should collapse item handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the outline view. Your handler should determine whether to allow the specified item to collapse, then return the appropriate value.

on should collapse item theObject outline item outlineItem
    set allowCollapse to false
    --Check variable, perform test, or call handler to see if OK  to collapse
    -- If so, set allowCollapse to true
    return allowCollapse
end should collapse item
should expand item

Called for an outline view to determine if an item should be expanded.

The handler returns true to allow expanding of the item, false to disallow it.

Syntax
should expand item outline view required
 outline item item optional
Parameters
reference

a reference to the outline view that contains the items that may be expanded

outline item  item

the item that may be expanded

Result
boolean

Return true to allow the item to expand; false to prevent expanding. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should expand item handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the outline view. Your handler should determine whether to allow the specified item to expand, then return the appropriate value.

on should expand item theObject outline item outlineItem
    set allowExpand to false
    --Check variable, perform test, or call handler to see if OK  to expand
    -- If so, set allowExpand to true
    return allowExpand
end should expand item
should select column

Called to determine if selection is allowed when a user clicks a column in a table or outline view (such as when a user attempts to drag a column to change its position).

The handler returns true to allow selection or false to disallow it.

By default, column selection is turned on for table view objects but not for outline view objects, but you can change the setting in Interface Builder. You don’t need to connect this handler unless you want to allow column selection in some cases but prevent it in others.

Syntax
should select column reference required
 table column table column required
Parameters
reference

a reference to the table view or outline view that contains the column

table column  table column

the column to be selected

Result
boolean

Return true to allow the column to be selected; false to prevent selection. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should select column handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should determine whether to allow the specified column to be selected, then return the appropriate value.

on should select column theObject table column tableColumn
    set allowSelection to false
    --Check variable, perform test, or call handler to see if OK  to select
    -- If so, set allowSelection to true
    return allowSelection
end should select column
should select item

Called to determine if selection is allowed when a user clicks an item in an outline view.

The handler returns true to allow selection or false to disallow it. You don’t need to connect this handler unless you want to allow item selection in some cases but prevent it in others.

Syntax
should select item reference required
 outline item item optional
Parameters
reference

a reference to the outline view that contains the item that may be selected

outline item  item

the item that may be selected

Result
boolean

Return true to allow the item to be selected; false to prevent selection. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should select item handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should determine whether to allow the specified item to be selected, then return the appropriate value.

on should select item theObject outline item outlineItem
    set allowSelection to false
    --Check variable, perform test, or call handler to see if OK  to select
    -- If so, set allowSelection to true
    return allowSelection
end should select item
should select row

Called to determine if selection is allowed when a user clicks a row in a table or outline view.

The handler returns true to allow selection or false to disallow it. You don’t need to connect this handler unless you want to allow row selection in some cases but prevent it in others.

Syntax
should select row reference required
 row integer required
Parameters
reference

a reference to the table view or outline view that contains the row that may be selected

row  integer

the one-based index of the row to be selected

Result
boolean

Return true to allow the row to be selected; false to prevent selection. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should select row handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should determine whether to allow the specified row to be selected, then return the appropriate value.

on should select row theObject row theRow
    set allowSelection to false
    --Check variable, perform test, or call handler to see if OK  to select
    -- If so, set allowSelection to true
    return allowSelection
end should select row
should selection change

Called for a table or outline view to determine if the current selection should change.

The handler returns true to allow selection to change, false to disallow it.

Syntax
should selection change reference required
Parameters
reference

a reference to the table view or outline view for which the selection may be changed

Result
boolean

Return true to allow the selection to change; false to prevent change. If you implement this handler, you should always return a boolean value.

Examples

When you connect a should selection change handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler should determine whether to allow the selection to change, then return the appropriate value.

on should selection change theObject
    set allowSelectionChange to false
    --Check variable, perform test, or call handler to see if OK  to select
    -- If so, set allowSelectionChange to true
    return allowSelectionChange
end should selection change
will display browser cell

Called before a browser cell is displayed in a browser view.

The handler cannot cancel the display operation, but can prepare for it.

Unlike other data views such as outline view and table view, you cannot supply data to a browser with a data source. As a result, performance may be inadequate for browser views that display more than a small number of items, and you should consider using one of the other data views, if suitable for your purpose.

Syntax
will display browser cell reference required
 browser cell browser cell required
 in column integer required
 row integer required
Parameters
reference

a reference to the browser object that contains the cell that may be displayed

browser cell  browser cell

the cell that is to be displayed

in column  integer

the one-based index of the column for the given cell

row  integer

the one-based index of the row for the given cell

Examples

For an example of the will display browser cell handler, see the Examples section for the browser cell class.

will display cell

Called before a cell is displayed for a table or outline view (thus displaying the data at a specified row and column).

The handler cannot cancel the display operation, but can prepare for it.

The preferred way to manipulate data for table and outline views is to use a data source, in which case this handler is not needed (or called).

Syntax
will display cell reference required
 cell anything required
 row integer required
 table column table column required
Parameters
reference

a reference to the object that contains the cell that will be displayed

cell  anything

the cell that is about to be displayed; see cell, image cell, and text field cell

row  integer

the one-based index of the row of the cell to be displayed

table column  table column

the column of the cell to be displayed

Examples

When you connect a will display cell handler to a table view or outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler should do any required preparation for display of the specified cell.

on will display cell theObject row theRow cell theCell table column  tableColumn
    (* Prepare for cell to be displayed. *)
end will display cell
will display item cell

Called before a data cell is displayed for an outline view (thus displaying the data for a specified item and column).

The handler cannot cancel the display operation, but can prepare for it.

The preferred way to manipulate data for table and outline views is to use a data source, in which case this handler is not needed (or called).

Syntax
will display item cell reference required
 cell anything required
 outline item item optional
 table column table column required
Parameters
reference

a reference to the outline view that contains the item that will be displayed

cell  anything

the cell that is about to be displayed; see cell, image cell, and text field cell

outline item  item

the item that contains the cell that will be displayed

table column  table column

the column of the cell to be displayed

Examples

When you connect a will display item cell handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. Your handler should do any required preparation for display of the specified item cell.

on will display item cell theObject outline item outlineItem cell  theCell table  column tableColumn
    (* Prepare for cell to be displayed. *)
end will display item cell
will display outline cell

Called before display of a cell that implements a disclosure triangle symbol in an outline view.

The handler cannot cancel the display operation, but can prepare for it.

The preferred way to manipulate data for table and outline views is to use a data source, in which case this handler is not needed (or called).

Syntax
will display outline cell reference required
 cell anything required
 outline item item optional
 table column table column required
Parameters
reference

a reference to the outline view that contains the outline cell that will be displayed

cell  anything

the cell that is about to be displayed; see cell, image cell, and text field cell

outline item  item

the item that contains the cell that will be displayed

table column  table column

the column of the cell to be displayed

Examples

When you connect a will display outline cell handler to an outline view object in Interface Builder, AppleScript Studio supplies an empty handler template like the following. The theObject parameter refers to the table or outline view. Your handler should do any required preparation for display of the specified outline cell.

on will display outline cell theObject outline item outlineItem  cell theCell  table column tableColumn
    (* Prepare for cell to be displayed. *)
end will display outline cell


< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.