When designing an interface in AppleScript Studio, you will find that different situations call for different types of buttons. In last month’s column, we focused on two specific types of buttons, push buttons and popup buttons (click here for last month’s column). This month, we’re going to discuss two more specific types of buttons, checkboxes and radio buttons.
Preparing to Follow Along
To follow along with the examples in this month’s column, you will need to create an AppleScript Studio project. Launch Xcode, and select New Project… from the File menu. Next, select the AppleScript Application project template, and create a new project named Button Demo.
Once the project has been created, double click on the MainMenu.nib component to open the project’s interface in Interface Builder. Next, design the main window of the project to match the example window shown in figure 1, below. The completed window should contain a single checkbox (titled Checkbox 1), a radio button matrix consisting of two button cells (titled Radio Button 1 and Radio Button 2), and a push button (titled Test). We’ll use the push button on the window to test the code within our project that will interact with the checkbox and radio buttons.
Figure 1: Example Interface
Next, we need to assign AppleScript names to the checkboxes and radio buttons in our project. This will allow us to accurately target the elements of our interface by name. Begin by selecting the checkbox, and assign an AppleScript name of checkbox via the AppleScript pane of the Inspector palette. See figure 2.
Figure 2: Assigning an AppleScript Name to Checkbox
Next, select each of the radio button’s cells (double click in the radio button to select an individual cell). Name the cells Button Cell 1 and Button Cell 2, respectively. See figure 3.
Figure 3: Assigning an AppleScript Name to a Radio Button Cell
Next, to allow us to test our code, select the push button, enable its clicked event handler, and connect it to the Button Demo.applescript script in our project. See figure 4.
Figure 4. Assigning a clicked Event Handler to a Push Button
Click the Edit button at the bottom of the Inspector palette to bring Xcode to the front and display the main script within the project. You should see an empty clicked event handler.
on clicked theObject
(*Add your script here.*)
end clicked
Please note, an example project, complete with the interface described above, as well as all example code provided below, is available for download and testing. You may download this example project here.
Checkboxes
Let’s begin discussing checkboxes first. A checkbox is a type of button that will allow the user to select an on/off option. Checkboxes can be useful in a variety of situations. For example, suppose you’re designing an interface that will allow the user to specify options for saving a file. The option to overwrite existing files with the same name might be well served as a checkbox.
Like push buttons, checkboxes can be configured with various event handlers, such as a clicked handler, which will execute code when the checkbox is clicked. I would encourage you to browse through the different event handlers available for checkboxes in the AppleScript pane of the Inspector palette.
Determining Checkbox Selections
To determine whether a checkbox is enabled, you need to determine its state. This can be done in a few different ways. One way is to check the value of the checkbox’s integer value property. If the checkbox is selected, the value of this property will be 1. If it’s not selected, then the value of this property will be 0. To illustrate this concept, modify the clicked handler within our project as follows. Note, in the code below, the checkbox is referenced as a button. A checkbox is a specific type of button, and must be referenced as such.
on clicked theObject
if (integer value of button "checkBox" of window 1) = 1 then
display dialog "Selected"
else
display dialog "De-selected"
end if
end clicked
Next, build and run the project. When the interface is displayed, select or de-select the checkbox. Then, click the Test button to execute the clicked handler, and a dialog should be displayed indicating whether the checkbox is selected.
Another way to determine whether a checkbox is selected is to check the value of its string value property. This property will contain the same value as the integer value property of the checkbox, only in string format. For example, rather than a value of 1 or 0, this property will contain a value of “1” or “0”. To test this, modify the code within the clicked handler of our project as follows. Then, build and run the project, and repeat the previous test.
on clicked theObject
if (string value of button "checkBox" of window 1) = "1" then
display dialog "Selected"
else
display dialog "De-selected"
end if
end clicked
Selecting/De-Selecting Checkbox
At times, you may not want to determine the state of a checkbox. Instead, you may want to set the state of a checkbox to be either selected or de-selected. To do this, you can set the checkbox’s integer value or string value properties, which are both read/write properties, to the desired value. The following example code demonstrates how to set the state of a checkbox by modifying its integer value property.
on clicked theObject
tell button "checkBox" of window 1
if integer value = 1 then
set integer value to 0
else
set integer value to 1
end if
end tell
end clicked
Build and run the project. Now, when you click the Test button, the checkbox should toggle between being selected and de-selected.
Enabling/Disabling Checkboxes
There may also be situations where, although a checkbox is present on your interface, you don’t want the user to be able to select/de-select it. You can disable a checkbox, like you can a push button, by modifying the value of its enabled property. The following code will toggle the checkbox between being enabled or disabled, when the Test button is clicked in our project’s interface. Modify the code of our project as follows. Then, build and run the project, and click the Test button to ensure the expected behavior.
on clicked theObject
tell button "checkBox" of window 1
if enabled = true then
set enabled to false
else
set enabled to true
end if
end tell
end clicked
Radio Buttons
Radio buttons are a bit different than other types of buttons. In most cases, radio buttons aren’t individually included in an interface. Rather, they are typically included in a set, allowing the user to select one or more of a series of options. Radio buttons of this nature are actually contained within another type of interface element in AppleScript Studio, called a matrix. A matrix represents a grouping of multiple objects, such as radio buttons, that will work together in a specified way. For example, in a radio button matrix, selecting one radio button will automatically disable the other radio buttons in the matrix.
Like other types of buttons, radio buttons can be configured with a clicked event handler, allowing AppleScript code within a project to be executed when the button is clicked. With radio buttons, the clicked handler can be configured for any individual radio button within the matrix, or to the matrix itself, giving you flexibility to adjust the button’s response according to the specific needs of your project. Other event handlers are available for both matrixes and radio buttons, and I encourage you to explore these further on your own.
Determining Radio Button Selections
When working with radio buttons, you will need a way to determine which radio button the user has selected in the matrix. There are a number of methods for determining this. One way is to check the value of the current row property of the matrix. This property will contain an integer value, indicating the currently selected row in the matrix, i.e. 1 for the first radio button in a matrix, 2 for the second, and so forth. To illustrate this concept, modify the clicked handler within our project as follows. Then, build and run the project. When the Test button is clicked, a dialog will be displayed, indicating the number of the currently selected radio button.
on clicked theObject
tell matrix 1 of window 1
display dialog (current row) as string
end tell
end clicked
Another property of a matrix, called current cell, may be used to determine the currently selected cell within the matrix. In other words, a reference to the selected radio button. Using this reference, you can get the title property of the radio button, in order to determine which button is currently selected. Modify our project as follows, build and run the project, and click the Test button. This time, you should see a dialog displayed that indicates the title of the currently selected radio button, rather than the row number.
on clicked theObject
tell matrix 1 of window 1
display dialog (title of current cell) as string
end tell
end clicked
Since we have assigned AppleScript names to the radio buttons within the matrix in our test project’s interface, this information can also be used to determine which radio button is selected. Rather than referencing the title property of the current cell, as demonstrated above, we can reference its name property. For example:
on clicked theObject
tell matrix 1 of window 1
display dialog (name of current cell) as string
end tell
end clicked
Test this example code, and notice how the result differs from the previous example.
Selecting Radio Buttons
Like checkboxes, you can also set the state of a radio button. In other words, you can set the currently selected radio button in a matrix. To do this, set the value of the matrix’s current row property to the desired row number. For example, the following code will toggle the currently selected row of the matrix in our project’s interface. Modify the clicked handler within our project as follows, then build and run the project, and click the Test button to demonstrate this functionality.
on clicked theObject
tell matrix 1 of window 1
if current row = 1 then
set current row to 2
else
set current row to 1
end if
end tell
end clicked
Enabling/Disabling Radio Buttons
Like other types of buttons, radio buttons can be enabled or disabled. This may be done to the individual radio buttons within the matrix, and not to the matrix itself. Modify the clicked handler within our project as follows. The build and run the project. When the Test button is clicked, the code will first determine whether the first cell, i.e. radio button, within the matrix is enabled. If it is enabled, then it will disable all cells within the matrix. If it is not enabled, then it will enable all cells within the matrix. This will cause the radio buttons to toggle between enabled and disabled.
on clicked theObject
tell matrix 1 of window 1
if enabled of cell 1 = true then
set enabled of every cell to false
else
set enabled of every cell to true
end if
end tell
end clicked
In Conclusion
The examples demonstrated throughout this column should give you a good foundation for working with checkboxes and radio buttons in AppleScript Studio projects. Of course, there will no doubt be situations you encounter which don’t adhere to the normal use of these buttons that we have discussed. If you find yourself struggling with these, or any other types of buttons, be sure to check out the terminology for the object you are attempting to reference in the AppleScript Studio AppleScript dictionary. See figure 5. This can be accessed by double clicking on the AppleScriptKit.sdef component in any project created using one of Apple’s AppleScript Studio Xcode templates.
Figure 5. AppleScript Studio’s AppleScript Dictionary
For more in-depth help, take some time to browse the AppleScript Studio Terminology Reference included in Xcode’s Help documentation, and also available online via the ADC website. There are also dozens of great fully editable example projects installed with Xcode in the Developer/Examples/AppleScript Studio/ folder. Be sure to check those out too.
Until next time, just script it!
-Ben Waldie