A simple view that can draw a border around itself and can title itself.

You can use a box to visually group other views or to serve as simple separators.

Figure 3-1 shows several boxes, including an empty box, a box that contains two radio buttons, and boxes used as horizontal and vertical separators. In Interface Builder, you will find separator boxes on the Cocoa Views palette (along with various buttons and text views), while container boxes are on the Container Views palette (along with tab and custom views).

See the scroll view class for information on how to make objects into subviews of a box or other view in Interface Builder.

Figure 3-1  Boxes, including horizontal and vertical separators

Properties of box objects

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

Elements of box objects

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

Events supported by box objects

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

Examples

For a window “main” that contains a box with several text fields, you could set the text of one of the fields with the following statement:

set contents of text field "company" of box "info"  of window "main" to "Acme Nuts  and Bolts, Ltd."

To access various properties of the same box, you could do the following:

tell window "main"

    tell box "info"

        set boxTitle to title

        set boxType to type

        -- and so on

    end tell

end tell

Version Notes

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

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

Properties of clip view objects

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

Elements of clip view objects

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

Events supported by clip view objects

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

A user interface element that contains and displays view objects.

Drawers typically contain text field, scroll view, browser, and other objects based on classes that inherit from the view class. Figure 3-2 shows a drawer that contains many user interface objects.

A drawer is associated with a window, called its parent, and can only appear while its parent is visible on screen. A drawer cannot be moved or ordered independently of a window, but is instead attached to one edge of its parent and moves along with it.

Figure 3-2  A window with an open drawer (from the Drawer sample application)

To add a drawer to your AppleScript Studio application, you drag it from the Cocoa-Windows palette, shown in Figure 3-3. You typically use the window item shown with an open drawer on the left. That’s a convenience object that takes care of the overhead of creating and connecting a window, its drawer, and the content view for the drawer. If you drag that window to your main nib window, you will see the three instances visible in the bottom row in Figure 3-4. You use them as follows:

• NSDrawer instance: To connect event handlers for the drawer object, select the NSDrawer instance and open the Info window to the AppleScript pane.

• ParentWindow instance: To add interface items to the window that owns the drawer, double-click the ParentWindow instance to open the window. You can also use the Info window to connect event handlers for the window.

• DrawContentsView instance: To add interface items to the drawer, double-click the DrawContent… instance to open a window (shown in Figure 3-5). You can also use the Info window to connect event handlers for the window. You will see that the Info window identifies the instance as “NSView (Custom)”.

Once you have added a window and drawer in Interface Builder, you will have to take steps to show the window in your application, and to allow a user to open and close the drawer. You can show the window by connecting a launched handler to the File’s Owner object (which represents the application) in the main nib window. See the application class for more information about the File’s Owner.

Figure 3-3  Interface Builder’s Cocoa-Windows palette, with drawers

If you give your drawer window the AppleScript name “main” (in the AppleScript pane in the Info window in Interface Builder), your launched handler might look something like this one, from the Drawer sample application, available at <Xcode>/Examples/AppleScript Studio:

on launched theObject

show window "main"

end launched

To allow a user to open and close the drawer, you might add a button with the title “Open Drawer”. You could then connect a clicked handler to the button that

• opens or closes the drawer according to the current state of the drawer

• sets the button title to reflect the state of the drawer (such as “Open Drawer” when the drawer is closed and “Close Drawer” when the drawer is open)

You can use the open drawer command to open or close a drawer. For example, the following statement opens a drawer named “drawer”:

tell drawer "drawer" to open drawer

It is also possible to instantiate a drawer by itself (without a parent window or content view) by dragging the object labeled “Drawer” in Interface Builder’s Cocoa-Windows palette to a nib window. In that case, you will get just the NSDrawer instance, and you will have to hook it up to a window and content view yourself (the details of which are beyond the scope of this reference).

Figure 3-4  MainMenu.nib window after adding a window and drawer combination

For more information, see the document Drawers.

Figure 3-5  The content view for a drawer

Properties of drawer objects

In addition to the properties it inherits from the responder class, a drawer object has these properties:

Elements of drawer objects

A drawer 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 drawer objects

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

Events supported by drawer objects

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

Examples

For an overview of working with drawers, see the description above for this class. For a detailed programming example of working with drawers, see the Drawer sample application, available at <Xcode>/Examples/AppleScript Studio.

Properties of scroll view objects

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

Elements of scroll view objects

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

Events supported by scroll view objects

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

Examples

Because several kinds of objects, including outline, table, and text views automatically reside on a scroll view, AppleScript Studio applications often need to include a scroll view in specifying an object. The following line is from the Table sample application, available at <Xcode>/Examples/AppleScript Studio.

tell table view "contacts" of scroll view "contacts"

    of window of theObject to update

You can access properties of a scroll view with statements like the following, which sets a boolean variable based on whether the scroll view has a vertical scroller:

set hasVertScroller to has vertical scroller of scroll view "contacts"  of window  of theObject

Version Notes

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

Stacks several subviews within one view to coordinate changes in their relative sizes.

The pane splitter bars between the views can be horizontal or vertical, depending on whether the views are arranged vertically or side by side. In Figure 3-6, an outline view appears above a table view.

See the scroll view class for information on how to make objects into subviews of a split view or other view in Interface Builder.

Figure 3-6  A split view that contains an outline view and a table view

Properties of split view objects

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

Elements of split view objects

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

Events supported by split view objects

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

Examples

The following script gets the vertical property of a split view in the Mail Search sample application, available at <Xcode>/Examples/AppleScript Studio. This script is not part of the application, but you can run it from Script Editor to access the property in the Mail Search application. Similar statements will work within an AppleScript Studio application script (though you won’t need the tell application statement).

tell application "Mail Search"

    tell front window

        set isVertical to vertical of first split view

        -- Do something based on result

    end tell

end tell

You may also need to refer to a split view to access another view in your application. The following fragment from Mail Search specifies a scroll view on a split view of a window:

tell scroll view "mailboxes" of split view 1 of theWindow

    -- Access properties or subviews of the scroll view.

end tell

Version Notes

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

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

Provides a convenient way to present information in multiple pages.

The view contains a row of tabs that select different panes, as shown in Figure 3-7. The user selects the desired page by clicking the appropriate tab or using the arrow keys to move between pages. Each page displays a view hierarchy provided by your application. Each tab, and its associated view hierarchy, is represented by a tab view item.

The Examples section describes how to use a tab view to give the appearance of switching out the entire contents of a view.

Important:  You cannot access user interface elements of a tab view item unless it is the current tab view item. A tab view switches tabs by removing the view for one tab view item and adding the view for another to the view hierarchy. AppleScript must walk the view hierarchy to get access to the user interface elements in its subviews.

Your application that uses a tab view can perform any necessary validation on the user interface elements on a tab view item before the item is switched out. You can do this in the should select tab view item event handler, which is called when the tab view is about to switch tab view items. If the tab view item is valid, you should save any required information from its user interface elements and allow it to be switched out. Your application can do any necessary work to prepare the user interface elements on a tab view item when it is switched in. You can do this in the selected tab view item event handler, which is called when the current tab view item has been changed. The Assistant sample application, available at <Xcode>/Examples/AppleScript Studio, shows one way to perform these operations.

See the scroll view class for information on how to make objects into subviews of a tab view or other view in Interface Builder.

Figure 3-7  A tab view with three panes

Properties of tab view objects

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

Elements of tab view objects

In addition to the elements it inherits from the view class, a tab 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.”

Events supported by tab view objects

A tab view object supports handlers that can respond to the following events.

Examples

Given appropriately-named objects, you can use terminology like the following to set the text in a text field on a tab view:

set contents of text field "textFieldName" of view of  tab view item  "tabViewItemName" of tab view "tabViewName"  of window "windowname"

Items on a tab view item are actually on a view that’s on the tab view item, which accounts for the view in the phrase of view of tab view item in this example. However, starting in AppleScript Studio version 1.2, you no longer need to specify the view, and can use the following, slightly simpler form:

set contents of text field "textFieldName" of tab view  item "tabViewItemName" of  tab view "tabViewName" of window "windowname"'

You can use a tab view to give the appearance of switching out the entire contents of a view. In Interface Builder, drag a tab view from the Cocoa-Containers pane of the Palette window to the target window. With the tab view selected, select the Tabless radio button. You can then choose styles between having a drop shadow or having no visible frame at all. If you choose no visible frame, you can also choose whether the tab view should draw its background.

You will still be able to put whatever user interface items you want on each tab view item. Because there are no tabs to select, the Info window provides a stepper control to navigate between tab view items. Since a user won’t be able to select among tabs (presumably that’s your goal), you will have to change the currently displayed tab view item programmatically, with statements like the following (if you’ve given the first tab view item the name "tabViewItem1"):

tell tab view "tabview" of window "main"

    set the current tab view item to tab view item "tabViewItem1"

end

The Assistant sample application, available at <Xcode>/Examples/AppleScript Studio, shows how to use a tab view and separate tab view items to represent an information panel.

Version Notes

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

Tab views in AppleScript Studio are implemented by Cocoa’s NSTabView class. Prior to Mac OS X version 10.2, NSTabView only supported tab views with the tabs on the top.

Starting with AppleScript Studio version 1.2, a script can say button 1 of tab view item 1 of tab view 1 instead of button 1 of view of tab view item 1 of tab view 1, though the longer version still works (and will run with any version of AppleScript Studio, not just version 1.2). See the Examples section above for another example.

Properties of tab view item objects

A tab view item has these properties:

Events supported by tab view item objects

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

Examples

The following handler is from the sample application Assistant, available at <Xcode>/Examples/AppleScript Studio (starting with AppleScript Studio version 1.1). This handler is called when the script’s properties need to be updated from the contents of user interface objects associated with a tab view item. As the first line of the tell statement shows, the terminology to access a tab view can be quite complex. A common error prior to AppleScript Studio version 1.2 was to omit view of at the beginning of the statement. Starting with version 1.2, the view of is optional.

Within the tell block, the statements to gather information from individual text field objects are more straightforward. Each statement assigns a value to a property of the script.

    on updateValues(theWindow)

        tell view of tab view item infoPanelName of tab view "info  panels"

                    of box "border" of theWindow

            set my company to contents of text field "company"

            set my name to contents of text field "name"

            set my address to contents of text field "address"

            set my city to contents of text field "city"

            set my state to contents of text field "state"

            set my zip to contents of text field "zip"

            set my email to contents of text field "email"

        end tell

    end updateValues

The Examples section for the tab view class describes how to use a tab view to give the appearance of switching out the entire contents of a view by switching tab view items.

Properties of view objects

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

Elements of view objects

A 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.”

Commands supported by view objects

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

Events supported by view objects

A view object view supports handlers that can respond to the following events. To connect an event handler to a view object in Interface builder, put the nib window for the window object that contains the view into outline mode by clicking the small outline icon above the right scroll bar; use the disclosure triangles to open the window and other enclosed objects until the view object is visible; select it, then connect the event handler in the AppleScript pane of the Info window.

Examples

The view class is an abstract class that you don’t typically target in your scripts. More often you target subclasses, such as box or scroll view or tab view. The control class also inherits from the view class, so all subclasses of control inherit view properties and elements (though view elements such as a movie view or progress indicator are not of much use to a control such as a button).

You can use the following script in Script Editor to rotates the text in a text view by 50 degrees. Similar statements will work within an AppleScript Studio application script (though you won’t need the tell application statement).

tell application "rotate"

    tell window 1

        tell scroll view 1

            tell text view 1

                set bounds rotation to 50.0

                set needs display to true

            end tell

        end tell

    end tell

end tell

Version Notes

Through AppleScript Studio version 1.4, the needs display property is not supported for the window class, but is supported for the view class.

The lock focus and unlock focus commands are not supported through AppleScript Studio version 1.4.