Events supported by action cell objects

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

Examples

See the examples for cell.

Control subclass that intercepts mouse-down events and initiates a handler call when it is clicked or pressed.

A button contains a single button cell. Figure 4-1 shows a simple button.

Figure 4-1  A button

You will find an assortment of buttons on the Cocoa-Controls pane of Interface Builder’s Palette window. You can set many attributes for buttons in Interface Builder’s Info window. You can also change button types in your scripts, using the constants defined in Button Type.

Properties of button objects

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

Elements of button objects

A button object can contain only the elements it inherits from control.

Commands supported by button objects

Your script can send the following command to a button object:

Events supported by button objects

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

Examples

AppleScript Studio provides access to many types of button objects and the sample applications distributed with AppleScript Studio include many examples of working with buttons. The following script statements demonstrate some of the basic terminology for using buttons.

In the most common case, you use a button to trigger an action in a clicked handler. The following clicked handler, from the Currency Converter sample application, just performs the currency conversion, based on the values the user has supplied, and displays the result. The clicked handler’s theObject parameter refers to the button. In this case, the handler uses the window of the button to get at other objects.

on clicked theObject

    tell window of theObject

        try

            set theRate to contents of text field "rate"

            set theAmount to contents of text field "amount"  as number

            set contents of text field "total" to theRate  * theAmount

        on error

            set contents of text field "total" to 0

        end try

    end tell

end clicked

The following statement disables a button with AppleScript name “someButton”.

set enabled of button "someButton" to false

You implement radio buttons with a matrix object. See that class for examples.

The following statements, from the clicked handler of the Unit Converter sample application, show how to determine if a particular button was the target for a view that has more than one button that may need to respond. In this case, the button of interest (the Convert button) is part of a box object.

on clicked theObject

    tell window "Main"

        if theObject is equal to button "Convert" of box  1 then

            my convert()

        else if ...

        ...

    end tell

end clicked

Discussion

Buttons provide a simple mechanism for switching the button title or image as a user toggles the button state. For example, to create a button in Interface Builder that toggles its text between “Start” and “Stop”, you use these steps:

1. Drag a button object from the Cocoa-Controls pane of the Palette window to the target window. You can use any button that shows “NSButton” when you rest the cursor over it in the Palette window.

2. With the button selected in the target window, open the Info window by choosing Show Info from the Tools menu or by typing Command-Shift-I.

3. If the Behavior pop-up on the attributes pane of the Info window isn’t enabled, choose a button type in the Type pop-up that causes the Behavior pop-up to be enabled. For example, you might set the button type to Rounded Bevel Button, Square Button, or Round Button.

4. Set the Behavior pop-up to Toggle.

5. Type “Start” in the Title field and “Stop” in the Alt. Title field.

6. To test the button, choose Test Interface from the File menu (or type Command-R). You should be able to click the button and toggle its title between “Start” and “Stop”.

The Attributes pane provides other button settings, including fields for setting an icon and an alternate icon for buttons that show an icon. Note that you can display any image in the button, not just an icon.

Properties of button cell objects

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

Events supported by button cell objects

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

Examples

AppleScript Studio applications typically script buttons, rather than scripting a button cell directly, and the button class has some of the same properties as the button cell class. In addition, the button class inherits from the control class, which has a current cell property, through which you can access properties of the button’s button cell, if necessary. For example, you can use the following script in Script Editor to access the button cell of a push button in the main window of an AppleScript Studio application. Similar statements will work within an AppleScript Studio application script (though you won’t need the tell application statement).

tell application "testApplication"

    -- check the "image dims when disabled" property:

    image dims when disabled of (current cell of first button of  window 1)

        -- result: 1

    -- check transparency:

    transparent of (current cell of first button of window 1)

        -- result: 0

end tell

Version Notes

The shows state by property in this class is not supported, through AppleScript Studio version 1.4.

Properties of cell objects

A cell object has these properties:

Commands supported by cell objects

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

Events supported by cell objects

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

Examples

You typically script a subclass of control or view that contains a cell (or a subclass of cell), not the cell itself. One situation where you might access a cell itself is when working with a matrix. A matrix is used to create groups of cell objects, such as radio buttons.

The Assistant application, available at <Xcode>/Examples/AppleScript Studio (starting with AppleScript Studio version 1.2) uses a matrix of radio buttons to specify the severity of a problem. It uses the following statement in its updateValues handler to get the title property of the currently selected radio button. This statement sets a property severity to the title of the current cell of the matrix (the matrix is also named “severity”):

set my severity to title of current cell of matrix "severity"

Version Notes

The action method property was added in AppleScript Studio version 1.4. As a result, you can dynamically change the target of an action in your application or change the Cocoa method that is executed when the action is triggered. For an example of how to do this, see the toolbar item class.

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.

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

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

Supports selecting and displaying a single color value.

A color-panel uses a color well to display the current color selection. You typically work with colors through the color panel property of the application class, not by working directly with a color well.

Figure 4-2 shows a color well in a window. Clicking the color well opens a color panel; choosing a color in the color panel sets the color in the color well.

Figure 4-2  A color well in a window

You will find the color well object on the Cocoa-Controls pane of Interface Builder’s Palette window. You can set attributes for color wells in Interface Builder’s Info window.

For related information, see the document Color Programming Topics for Cocoa.

Properties of color well objects

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

Events supported by color well objects

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

Examples

You typically work with colors through the color panel property of the application class, not by working directly with a color well. For examples, see color-panel.

Version Notes

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

A control that provides two ways to enter a value: through direct text entry (as with a text field), or by choosing from a pop-up list of pre-selected values.

Figure 4-3 shows a combo box with its pop-up list hidden.

Figure 4-3  A combo box, with no pop-up list showing

Figure 4-4 shows the same combo box with its pop-up list displayed.

Figure 4-4  A combo box, with the pop-up list displayed

You will find the combo box object on the Cocoa-Text pane of Interface Builder’s Palette window. You can set many attributes for combo boxes in Interface Builder’s Info window. Note that through AppleScript Studio version 1.4, you cannot use a data source object with a combo box.

For more information, see the document Combo Boxes.

Properties of combo box objects

In addition to the properties it inherits from the text field class, a combo box object has these properties:

Elements of combo box objects

In addition to the elements it inherits from the text field class, a combo box object can contain the elements listed below. Your script can access most elements with any of the key forms described in