Set a control
Sets a checkbox, switch, slider, pop-up menu, tab or text field to a state instead of clicking it, and does nothing when it is already there.
Set locator to to
Details #
A click on a checkbox toggles it, so a macro that "turns on Reduce motion" turns it off the second time. This step says what the control should be. It reads the control, acts only when the value differs, reads it again, and fails with both values when it did not take. Running it twice leaves the same result as running it once.
It reports {was, now, changed, method}. changed is false when nothing needed doing, and the Activity note says "already PDF". Every method is an accessibility action or value, never the pointer, so the app does not have to be in front. The one exception is a checkbox that refuses both a press and a value: then the step clicks it.
| Control | to | How it is set |
|---|---|---|
| Checkbox, switch, toggle button, disclosure triangle, marked menu item | true / false (or on, off, open, closed) | Press when different; else write the value |
| Radio button | true, or its own title | Press |
| Radio group, tab group, segmented control | the title of the choice | Press the choice with that title |
| Pop-up button, menu button | the title of the item | Open the menu, press the item, confirm |
| Combo box | a title, or text if it has no menu | As a pop-up; else write the value |
| Slider, stepper | a number, or "40%" of its range | Write the value; else increment or decrement up to 200 times until within tolerance |
| Text field, text area | text | Write the value, then read it back |
| Color well, date and time fields | text | Write the value if the app allows it |
Anything else fails with "setControl doesn't know how to set a role; use click or setValue".
Titles match like menu items: exact, then prefix, then substring, ignoring case and accents, and /regex/ works. When nothing matches, the failure lists the choices it saw ("choices: PDF, PNG, JPEG").
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
locator | locator | Yes | The control. Required. | |
to | any value | Yes | What it should be. Required. The control's role decides what it means (table above). | |
app | text | The app to look in, by bundle id. Defaults to the locator's app, otherwise the front app. | ||
fuzzy | yes / no | |||
into | text | A variable that receives the value the control has afterwards. | ||
tolerance | number | For sliders and steppers: count it as set when within this much. Default 0. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- Set Reduce motion checkbox to on
- Set Format pop-up to “PDF”
Gotchas #
A dry run skips this step unless you mark it Safe; then it reads the control and reports what it would do.
A pop-up that a web page draws itself has no menu to open. The step presses Cancel so nothing is left hanging, and fails "the menu didn't open".
A slider that moves in steps bigger than
tolerancecan jump past the number. The step stops and says where it landed.
In the editor #
The Inspector's Set to control follows the element you pick. A checkbox, switch, radio button or tab gets On and Off. A slider gets a number field and, when the app reports its range, a slider. A pop-up button, tab group or segmented control gets a title field and a Choices menu that lists the control's own items, read from the app (it opens a pop-up's menu for a moment to do so, and closes it again). Anything else gets a text field. A line under the control says what it reads right now, and a warning appears when the value cannot mean anything to that kind of control, such as "PDF" for a checkbox. Switchboard looks at the control through the engine, so with the engine off the form still works and only that line is missing.
Recording #
Recording a click on a checkbox, switch, toggle button, disclosure triangle, radio button or tab writes Set a control with the state it ended in, so a recording that ticks a box is already safe to run twice. A tab is set by its title. A pop-up or slider stays a click, because the recorder cannot know where it ended. Generalize makes the same change to an older click when its locator remembers the state the control was in.
Recorded when #
The Recorder writes this step when you tick a checkbox, flip a switch, pick a radio button or a tab, or choose an item from a pop-up button: the state the control ended in. See Recording a macro.