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 Box Programming Topics.

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 “Standard Key Forms.”

Commands supported by combo box objects

Your script can send the following commands to a combo box class object:

Events supported by combo box objects

An object of class combo box supports handlers that can respond to the following events:

Examples

You can access the items in the pop-up list of a combo box through its combo box item property. Given a combo box with AppleScript name “combo” in the window “main”, the following statement will return a simple list of text items, each representing one item in the pop-up list of the combo box:

every combo box item of combo box "combo" of window "main"

The following lines will delete all the items in the combo box and add one new item:

delete every combo box item of combo box "combo" of window  "main"

make new combo box item at end of combo box items of combo box "combo"  of

    window "main" with data "Test Item"

You can delete a combo box item by index with a statement like the following:

delete combo box item 2 of combo box 1 of window 1

To get the contents of a combo box (the value in the text field part of the combo box), you can use a statement like the following:

set comboContents to contents of combo box "combo" of  window "main"

See also the Examples section for the combo box item class.

Version Notes

The following properties in this class are not supported, through AppleScript Studio version 1.4:

• data source

• uses data source

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

Events supported by combo box item objects

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

Examples

Given a combo box with AppleScript name “combo” in the front window, the following statement will return a simple list of text items, each representing one item in the pop-up list of the combo box:

every combo box item of combo box "combo" of window 1

See the Examples section for the combo box class for information on creating and deleting combo box items.

Version Notes

The combo box item class was added in AppleScript Studio version 1.1.

Properties of control objects

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

Elements of control objects

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

Commands supported by control objects

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

Events supported by control objects

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

Examples

The control class is an abstract class that you don’t typically target in your scripts. More often you target subclasses, such as button or slider.

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.

The following listing of an action handler uses the log command to show the result of using content and contents on a text field that contains the text “Some text”.

on action theObject

    log theObject -- result: text field 1 of window 1

    log contents of theObject -- result: text field 1 of window  1

    log contents of contents of theObject as string

        -- result: "Some text"

    log content of theObject as string

        -- result: "Some text"

end action

Properties of image cell objects

In addition to the properties it inherits from the cell class, an image cell object has these properties:

Events supported by image cell objects

An image cell object supports handlers that can respond to the following events:

Examples

You don’t typically script an image cell. You can script similar properties (frame style, alignment, scaling) of an image view instead.

Displays a single image in a frame, and can optionally allow a user to drag an image to it.

Figure 4-5 shows an image displayed in an image view by the Image sample application, available at <Xcode>/Examples/AppleScript Studio.

You can store an image in your AppleScript Studio project by dragging an image file from the Finder into one of the groups in the Files list in Xcode’s Groups & Files list, or by using the Add Files… command from the Project menu. You can also drag images into the Images pane of a nib window in Interface Builder. You can display an image in an image view by loading it with load image command. For related information, see image, as well as the document Image Views.

If you continually load images and don’t free them, your application memory usage will increase. For information on how to free an image, movie, or sound, see the Discussion section of the load image command.

Figure 4-5  A window displaying an image in an image view (from the Image sample application)

Properties of image view objects

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

Elements of image view objects

An image view object can contain only the elements it inherits from control.

Events supported by image view objects

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

Examples

The following awake from nib handler is from the Image sample application, available at <Xcode>/Examples/AppleScript Studio. The handler simply uses the load image command to load an image from the project. (The image is stored in the project’s Resources group and is named AboutBox.tiff.)

on awake from nib theObject

    set image of image view "image" of window "main"  to load image "AboutBox"

end awake from nib

If you continually load images and don’t free them, your application memory usage will increase. For information on how to free an image, movie, or sound, see the Discussion section of the load image command.

Used to create groups of cell objects, such as radio buttons, that work together in various ways.

Figure 4-6 shows a matrix that contains three radio buttons.

Figure 4-6  A matrix with three radio buttons

You will find the matrix object (containing radio buttons) on the Cocoa-Controls pane of Interface Builder’s Palette window. You can set many attributes for matrix objects in Interface Builder’s Info window. For information on creating matrix objects that contain other kinds of objects, see the scroll view class, as well as the button cell, image cell, secure text field cell, and text field cell classes.

For more information, see the document Matrix Programming Guide for Cocoa.

Properties of matrix objects

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

set spacing to call method "intercellSpacing" of matrix  1 of window 1

call method "setIntercellSpacing:" of matrix 1 of window  1 with parameter {2.0,  2.0}

call method "setScrollable:" of matrix 1 of window 1 with  parameters {true}

Elements of matrix objects

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

Events supported by matrix objects

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

Examples

The Drawer sample application distributed with AppleScript Studio uses a matrix that contains four radio buttons to specify the side on which its drawer should open (left, top, right, or bottom). The following statements, from the application’s awake from nib handler, set the current row of the matrix to indicate the currently selected radio button, based on edge information from the drawer.

on awake from nib theObject

    tell theObject

        set openOnEdge to edge of drawer "drawer"

        ...

        if openOnEdge is left edge then

            set current row of matrix "open on" to 1

        else if openOnEdge is top edge then

            set current row of matrix "open on" to 2

        else if openOnEdge is right edge then

            set current row of matrix "open on" to 3

        else if openOnEdge is bottom edge then

            set current row of matrix "open on" to 4

        end if

        ...

    end tell

end awake from nib

The following statements, from the same application’s clicked handler, show how to extract row information from the matrix, so that when the “drawer” button is clicked, the application knows on which side to open the drawer.

on clicked theObject

    tell window "main"

        if theObject is equal to button "drawer" then

            ...

            set openOnSide to current row of matrix "open on"

    ...

Version Notes

The following properties in this class are not supported, through AppleScript Studio version 1.4:

• cell size

• intercell spacing

• next text

• previous text

• scrollable

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

Displays a movie in a frame and provides properties associated with playing and editing the movie.

You use the load movie command to load a movie for the movie view. For playing, stepping through, or jumping to a location in the movie, you use commands such as start, stop, play, step forward, step back, and go (to jump to a specified location).

Figure 4-7 shows a movie displayed in a movie view in the Talking Head sample application, available at <Xcode>/Examples/AppleScript Studio.

You can store a movie in your AppleScript Studio project by dragging a movie file from the Finder into one of the groups in the Files list in Xcode’s Groups & Files list, or by using the Add Files… command from the Project menu. You can display a movie in a movie view by loading it with load movie command.

You can insert a movie view object into a nib file in Interface Builder by dragging the object represented by the QuickTime symbol from the Cocoa-GraphicsViews pane of the Palette window to the target window.

Figure 4-7  A movie view (from the Talking Head sample application)

Properties of movie view objects

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

Commands supported by movie view objects

Your script can send the following commands to a movie view object:

Events supported by movie view objects

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

Examples

The following will open handler is from the Talking Head sample application, available at <Xcode>/Examples/AppleScript Studio. The handler simply uses the load movie command to load a movie from the project when the window that contains a movie view is opened. (The image is stored in the project’s Resources group and is named jumps.mov.)

on will open theObject

    set movie of movie view "movie" of window "main"  to load movie "jumps"

end will open

If you continually load movies and don’t free them, your application memory usage will increase. For information on how to free an image, movie, or sound, see the Discussion section of the load image command.

Version Notes

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

Provides access to a pop-up menu or a pull-down menu, from which a user can choose an item.

Figure 4-8 shows a popup button displaying the first menu item in the pop-up menu.

Figure 4-8  A popup button

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

For related information, see the document Application Menu and Pop-up List Programming Topics for Cocoa.

Properties of popup button objects

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

Elements of popup button objects

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

Commands supported by popup button objects

Your script can send the following commands to a popup button:

Events supported by popup button objects

An popup button supports handlers that can respond to the following events:

Examples

For examples that show how to work with a popup button and respond to user changes, see the sample applications Coordinate System, Task List, and Unit Converter, available at <Xcode>/Examples/AppleScript Studio.

The following statement, from the awake from nib handler of the Task List sample application (available starting with AppleScript Studio version 1.2) sets the title of a popup button with AppleScript name “priority” to “3”.

set title of popup button "priority" to "3"

You remove menu items from a popup button with the delete command and insert them with the make command. For example, in the file Converter.applescript of the Unit Converter sample application distributed with AppleScript Studio, you'll find the updateUnitTypes handler. This handler shows how to delete all the items in the pop-up menu associated with a popup button and replace them with new items when you need to update the items in the menu.

    on updateUnitTypes()

        tell box 1 of window "Main"

            -- Delete all of the menu items from the pop-ups

            delete every menu item of menu of popup button "From"

            delete every menu item of menu of popup button "To"

            -- Add each of the unit types as menu items to both  of the pop-ups

            repeat with i in my unitTypes

                make new menu item at the end of menu items of menu  of

                    popup button "From"

                    with properties {title:i, enabled:true}

                make new menu item at the end of menu items of menu

                    of popup button "To"

                    with properties {title:i, enabled:true}

            end repeat

        end tell

    end updateUnitTypes

You can get the current menu item in a popup button with a statement like the following:

current menu item of popup button 1 of window 1

You can set the current menu item in a popup button with a statement like the following:

set current menu item of popup button 1 of window 1 to menu item  2 of menu of  popup button 1 of window 1

You can get the zero-based index of the currently selected menu item in a popup button with a statement like the following:

set currentIndex to contents of popup button 1 of window 1

You can get the value of the currently selected menu item in a popup button with a statement like the following:

set currentValue to title of popup button 1 of window 1

You can delete a named menu item from a named popup button with a statement like the following:

delete menu item "Shrink It" of menu of popup button "Do  Laundry" of window  "Laundromat"

Version Notes

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

Starting with AppleScript Studio version 1.2, when referring to the menu of a popup button, a script can say menu item 1 of popup button 1 instead of the longer menu item 1 of menu of popup button 1, although the longer form still works.

A progress indicator (also known as a progress bar) provides a standard mechanism for user feedback. Combined with a text field, it can provide both determinate (the total time is known and the bar moves from left to right proportional to the percentage of the task completed) and indeterminate (the total time is not known, and a striped cylinder or circular image spins continually) progress bars, as well as text messages.

Figure 4-9 shows an indeterminate progress indicator.

Figure 4-9  An indeterminate progress indicator

You will find the progress indicator on the Cocoa-Controls pane of Interface Builder’s Palette window. Starting with the version of Interface Builder released with Mac OS X version 10.2, you can also choose the circular indeterminate progress indicator shown in Figure 4-10. This type of progress indicator is often used for activity such as connecting to a network.

You can set attributes for progress indicators in Interface Builder’s Info window.

Figure 4-10  A circular indeterminate progress indicator

Properties of progress indicator objects

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

Commands supported by progress indicator objects

Your script can send the following commands to a progress indicator object:

Events supported by progress indicator objects

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

Examples

For brief examples of commands you use with progress indicators, see the animate, increment, start, and stop commands.

The following openPanel handler is from the Mail Search sample application, available at <Xcode>/Examples/AppleScript Studio. (Prior to AppleScript Studio version 1.1, Mail Search was named Watson.) This handler is one of several handlers that are part of a script object defined in the Mail Search application to control the status panel window.

The handler has one parameter, statusMessage, which supplies a message to display in the status panel. It also relies on global and script properties, including initialized and statusPanelNibLoaded.

If the status panel window hasn’t already been loaded, the handler loads it, sets the state of the window’s progress indicator, tells the indicator to start, and sets a text message for the status panel. It then uses the display command to display the status panel (and its progress indicator) attached to another window.

        on openPanel(statusMessage)

            if initialized is false then

                if not statusPanelNibLoaded then

                    load nib "StatusPanel"

                    set statusPanelNibLoaded to true

                end if

                tell window "status"

                    set indeterminate of progress indicator "progress"

                        to true

                    tell progress indicator "progress"  to start

                    set contents of text field "statusMessage"

                        to statusMessage

                end tell

                set initialized to true

            end if

            display window "status" attached to theWindow

        end openPanel

The Mail Search application also demonstrates a determinate progress indicator. Look for the makeStatusPanel handler, which creates and returns a script object with handlers to load a status panel containing the progress indicator, set its minimum and maximum values, and tell it to increment. The Mail Search Application is described in detail in AppleScript Studio Programming Guide (see “See Also” for information on that document).

Version Notes

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

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.

Starting with AppleScript Studio version 1.2, the display command is preferred over the display panel command.

Starting with the version of Interface Builder released with Mac OS X version 10.2, you can use the circular indeterminate progress indicator shown in Figure 4-10.

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

Hides its text from display or other access via the user interface, and is thus suitable for use as a password-entry object, or for any item in which a secure value must be kept.

A user can drop text into a secure text field, but it will be displayed according to the current settings of the field—either as bullets as blank characters. The default is to display text as bullets. For information on how to specify blanks, see the Examples section of the secure text field cell class.

Figure 4-11 shows a secure text field with several bullets visible. You can create a secure text field in Interface Builder with the following steps:

1. Drag a text field from the Cocoa-Text pane of the Palette window to the target window.

2. Select the text field.

3. In the Custom Class pane of the Info window, select NSSecureTextField as the class type.

Figure 4-11  A secure text field showing several bullets

For more information, see the class descriptions for text field cell and secure text field cell, as well as the document Text Fields.

Properties of secure text field objects

A secure text field object has only the properties it inherits from text field.

Elements of secure text field objects

A secure text field object can contain only the elements it inherits from text field.

Events supported by secure text field objects

A secure text field object supports handlers that can respond to the following events:

Examples

A secure text field has no scriptable properties or elements of its own. However, it inherits all of the properties and elements of text field. See also secure text field cell.

Version Notes

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

Properties of secure text field cell objects

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

Elements of secure text field cell objects

A secure text field cell object can contain only the elements it inherits from text field cell.

Examples

The following script statement changes the echos bullets property of a secure text field cell. By default, text characters are displayed as bullets. When bullets are turned off, characters are displayed as blanks.

set echos bullets of cell of secure text field 1 of window 1 to  false

Displays a range of values and has an indicator, or knob, which indicates the current setting.

A slider can optionally have tick marks at regularly spaced intervals. The user moves the knob along the slider's bar to change the setting.

The slider automatically determines whether it's horizontal or vertical by its size. If the slider is wider than it is tall, it's horizontal. Otherwise, it's vertical. A vertical slider has its minimum on the bottom; a horizontal slider has its minimum on the left.

You will find the several kinds of slider objects on the Cocoa-Controls pane of Interface Builder’s Palette window. You can set many attributes for sliders in Interface Builder’s Info window.

Figure 4-12 shows vertical and horizontal sliders with different kinds of knobs, and with and without tick marks. You will find these types of sliders on the Cocoa-Controls pane in Interface Builder’s Palette window.

Figure 4-12  Horizontal, vertical, and circular sliders, with and without tick marks

For more information, see the document Slider Programming Topics for Cocoa.

Properties of slider objects

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

Elements of slider objects

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

Events supported by slider objects

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

Examples

When you add a slider object to a window in Interface Builder, you can set various attributes of the slider, such as its minimum, maximum, and current (or start) values, and its number of markers (or tick marks). The following action handler is from the Language Translator application distributed with AppleScript Studio. For that application, the slider is set to allow a range of 0.0 to 7.0, which corresponds to the volume level range you can set with the set volume scripting addition (where 0.0 is silent and 7.0 is full volume).

This action handler, which is called whenever a user changes the slider setting, gets the slider from the window of the passed theObject parameter. It then gets a volume value based on the current slider setting and calls the set volume scripting addition to adjust the volume at which translated text will be spoken.

on action theObject

    set enabled of slider of window "Language Translator"  to true

    set volumevalue to contents of slider "volumeslider"

        of window "Language Translator" as integer

    set volume volumevalue

end action

Version Notes

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

A control consisting of two small arrows that can increment and decrement a value that appears beside it, such as a date or time.

Figure 4-13 shows a stepper to the right of a text field to display the stepper's value.

Figure 4-13  A stepper

You will find the stepper object on the Cocoa-Controls pane in Interface Builder’s Palette window. You can set many attributes for steppers in Interface Builder’s Info window.

For more information, see the document Steppers.

Properties of stepper objects

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

Elements of stepper objects

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

Events supported by stepper objects

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

Examples

When you add a stepper object to a window in Interface Builder, you can set various attributes of the stepper, such as its minimum, maximum, current (or start), and increment amount values. The following clicked handler is from the Drawer application distributed with AppleScript Studio. For that application, the stepper that controls leading offset for the drawer is set to allow a range of 0.0 to 1000.0, with an increment amount of 1.0.

This clicked handler, which is called whenever a user clicks the stepper, checks the passed theObject parameter to determine which object it was called for. If it was the leading offset stepper, it gets a leading value based on the current stepper setting and sets the leading offset property of the drawer object. Finally, it sets the value displayed in its associated text field (note that it doesn’t have to convert the value to a string to set the contents of the text field).

on clicked theObject

    tell window "main"

        if theObject is equal to button "drawer" then

    ...

        else if theObject is equal to stepper "leading offset"  then

            set theValue to (contents of stepper "leading offset")

                as integer

            set leading offset of drawer "drawer" to theValue

            set contents of text field "leading offset"  to theValue

    ...

The following script statements, from the action handler of the Drawer application, show how to set the value of the stepper from a value entered in its associated text field.

on action theObject

    set textValue to contents of theObject

    ...

    if theObject is equal to text field "leading offset"  then

        set leading offset of drawer "drawer" to textValue

        set contents of stepper "leading offset" to textValue

...

To set a stepper’s value, and to display the same value in an accompanying text field, you can use statements like the following:

tell window "main"

    set contents of stepper "stepperName" to myNumber

    set contents of text field "textFieldName" to myNumber

end tell

To get the value, use a statement like the following, which returns a real number:

tell window "main"

    set currentStepperValue to contents of stepper "stepperName"

end tell

Version Notes

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

Provides the ability to input, display, and edit text, as well as to display non-editable text that can be used for labels.

You will find the text field object on the Cocoa-Text pane in Interface Builder’s Palette window. You can set many attributes for text fields in Interface Builder’s Info window. For information on setting font, color, and other attributes for a text field, see the Examples section for the font class.

You can connect an action handler to a text field object in Interface Builder to gain control when a user finishes editing (either by tabbing to another field or by pressing the Enter key). In Interface Builder, you can also optionally set the text field to only call its action handler when the Enter key is pressed (and not when a user tabs out of the field).

AppleScript Studio applications automatically support tabbing between any text fields you add to a window. By default, tab order goes from left to right and down across the window, and is independent of the order in which you insert the text fields. See “Enabling Tabbing Between Objects” in Interface Builder help for a description of how to set tab order between text fields and other objects; you can specify the first object to receive keyboard events (or initial first responder), and each successive object in the responder chain.

Figure 4-14 shows a text field label (“System Font Text”) and an input text field. For more information, see the document Text Fields.

Figure 4-14  Text fields used as labels and input fields

Properties of text field objects

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

Elements of text field objects

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

Events supported by text field objects

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

Examples

Many of the sample applications distributed with AppleScript Studio show how to work with text fields. For example, the Currency Converter application (available starting with AppleScript Studio version 1.1) uses the following statement to get text from a text field. In this statement, the text is stored in the variable theRate, while "rate" specifies the AppleScript name for the text field. (You supply the AppleScript name in the Name field on the AppleScript pane of the Info window in Interface Builder.)

set theRate to contents of text field "rate"

The same application uses the following statement to set the text in another text field to show the result of the currency conversion:

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

Note that the text field automatically displays the result as text.

You can use a statement like the following to set the color of text in a text field to red:

set the text color of text field "text1" of window 1 to  {65535, 0, 0}

Version Notes

Support for drag-and-drop commands was added in AppleScript Studio version 1.2. See the “Terminology” for details. In particular, the description for the conclude drop event handler provides information on supporting drag and drop for text view and text field objects.

The next text and previous text properties in this class are not supported, through AppleScript Studio version 1.4. Support for these properties is not likely to be added.

Properties of text field cell objects

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

Events supported by text field cell objects

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

Examples

You don’t typically script a text field cell. You can script similar properties (background color, draws background, text color) of a text field instead. However, if you do need to access the properties of a text field cell, you can do so with statements like the following:

set textFieldCell to cell 1 of matrix 1

set myColor to background color of textFieldCell

set draws background of textFieldCell to true