> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulang v0

> Simulang v0 API reference — the action vocabulary used inside the Simular app.

Simular Pro gives you the highest level of flexibility and precise control over the full desktop via Simulang,
a specialized set of intuitive and easy-to-use action building blocks defined on top of Javascript.
While basic prompting of Simular using the chat mode may produce a good initial plan (in Simulang), full success for complex workflows may require edits to some steps in the plan.

<Note>
  **Simulang v0 (Simular app only).** This page documents the **v0** JavaScript-style actions that run **inside the Simular app** when you author or refine desktop workflows in Simular Pro. It does not describe the standalone Simulang CLI, `simulang-js` scripting, or other surfaces; for those, see the [Simulang Primer](/simulang/simulang-primer) and [Simulang with Claude Code](/simulang/simulang-claude-code).
</Note>

The best way to learn Simulang is by [Simulang v0 examples](/simular-pro/examples). Find out how to:

* [Read structured information](/simular-pro/examples#reading-structured-information)
* [Repeat a task on multiple objects](/simular-pro/examples#repeating-a-task-on-multiple-objects-on-a-page)
* [Write structured output](/simular-pro/examples#structured-information-output)
* [Locate an element precisely](/simular-pro/examples#clicking-on-ui-elements)

## General

### Act

Completes a task specified in natural language, up to a maximum number of steps.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Act({
      task: String = "",
      maxSteps: Int = 100
  })
  ```

  ```javascript Find all events of 100 museums in San Francisco theme={null}
  Act({task: "Find all events of 100 museums in San Francisco", maxSteps: 1000000})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="task">
    An arbitrary task.
  </ResponseField>

  <ResponseField name="maxSteps">
    Stop when this number of primitive actions have been executed.
  </ResponseField>
</Expandable>

## Application

### Open

Open or switch to an application.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Open({
      app: String = null,
      url: String = null,
      waitForLoadComplete: Bool = true,
      waitTime: Int = 0
  })
  ```

  ```javascript open chrome theme={null}
  Open({app: "Google Chrome"})
  ```

  ```javascript go to Zoom app theme={null}
  Open({app: "Zoom"})
  ```

  ```javascript switch to Slack theme={null}
  Open({app: "Slack"})
  ```

  ```javascript go to simular.ai theme={null}
  Open({url: "https://simular.ai"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="app">
    application name, e.g., Google Chrome, iMessage.
  </ResponseField>

  <ResponseField name="url">
    url address of a web page, e.g., google.com
  </ResponseField>

  <ResponseField name="waitForLoadComplete">
    Whether or not to wait for the app or URL to complete loading. Default is true.
  </ResponseField>

  <ResponseField name="waitTime">
    Duration in seconds to wait after opening the app or URL, in addition to the wait for load.
  </ResponseField>
</Expandable>

## Keyboard control

### Type

Type using the keyboard.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Type({
      text: String,
      withReturn: Bool = false,
      waitTime: Int = 0,
      waitForLoadComplete: Bool = false
  })
  ```

  ```javascript Enter John Smith with return theme={null}
  Type({text: "John Smith", withReturn: true})
  ```

  ```javascript Type John Smith theme={null}
  Type({text: "John Smith"})
  ```

  ```javascript Type https://google.com and press enter theme={null}
  Type({text: "https://google.com", withReturn: true})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="text">
    A piece of text to type.
  </ResponseField>

  <ResponseField name="withReturn">
    Whether or not to press the return (enter) key after typing.
  </ResponseField>

  <ResponseField name="waitTime">
    Duration in seconds to wait after typing.
  </ResponseField>

  <ResponseField name="waitForLoadComplete">
    Whether or not to wait for a page to complete loading after typing.
  </ResponseField>
</Expandable>

### Shortcut

Perform keyboard shortcut in the current application.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Shortcut({
      key: String,
      cmd: Bool = false,
      ctrl: Bool = false,
      option: Bool = false,
      shift: Bool = false,
      waitTime: Int = 0
  })
  ```

  ```javascript press ctrl+a theme={null}
  Shortcut({key: "a", ctrl: true})
  ```

  ```javascript use shortcut to select all theme={null}
  Shortcut({key: "a", cmd: true})
  ```

  ```javascript press cmd+shift+t theme={null}
  Shortcut({key: "t", cmd: true, shift: true})
  ```

  ```javascript press option and down arrow theme={null}
  Shortcut({key: "downArrow", option: true})
  ```

  ```javascript press enter theme={null}
  Shortcut({key: "enter"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="key">
    A key  to be pressed
  </ResponseField>

  <ResponseField name="cmd">
    Whether the command modifier should be pressed when tapping the key.
  </ResponseField>

  <ResponseField name="ctrl">
    Whether the control modifier should be pressed when tapping the key.
  </ResponseField>

  <ResponseField name="option">
    Whether the option modifier should be pressed when tapping the key.
  </ResponseField>

  <ResponseField name="shift">
    Whether the shift modifier should be pressed when tapping the key.
  </ResponseField>

  <ResponseField name="waitTime">
    Time in second to wait after executing the action.
  </ResponseField>
</Expandable>

## Mouse Control

### Click

Click on something, either specified by the `at` argument or the `element` argument.
Disambiguate by specifing the spatial relation between the target element and an anchor concept.
Available modes:

1. default is text-based grounding.
2. "textAndScreenshot": grounding using both text and vision.
3. "vision": vision-only grounding.
   When using modes with vision, all other arguments are ignored except `withCommand`, `clickType` and waits.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Click({
      at: String = "",
      mode: String = "",
      clickType: String = "left",
      withCommand: Bool = false,
      element: UIElement = null,
      spatialRelation: String = "",
      anchorConcept: String = "",
      prior: String = "none",
      position: String = "center",
      includeInvisible: Bool = false,
      waitForLoadComplete: Bool = false,
      waitTime: Int = 0
  })
  ```

  ```javascript click new tab theme={null}
  Click({at: "new tab"})
  ```

  ```javascript cmd+click verify insurance button theme={null}
  Click({at: "verify insurance button", withCommand: true})
  ```

  ```javascript double click Styles.zip theme={null}
  Click({at: "Styles.zip", clickType: "doubleClick"})
  ```

  ```javascript click "slider" closest to and on the right of "pointer size" theme={null}
  Click({at: "slider", spatialRelation: "closest,right", anchorConcept: "pointer size"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="at">
    Description of a target object to click. For higher accuracy, describe the target object by its role and value, e.g.
    "sign in button", "first name textfield".
  </ResponseField>

  <ResponseField name="mode">
    options: "textAndScreenshot", "vision". Leave empty for default text-based grounding.
  </ResponseField>

  <ResponseField name="clickType">
    Type of click. Options are: "left" (default), "right", and "doubleClick" (two quick left clicks)
  </ResponseField>

  <ResponseField name="withCommand">
    If true, agent presses the command key during click.
  </ResponseField>

  <ResponseField name="element">
    A UIElement. If given, ignores the `at` argument and directly clicks on this element.
  </ResponseField>

  <ResponseField name="spatialRelation">
    A comma-separated String of spatial relationship between the target object and element(s) that best
    match the `anchorConcept`. Options are: "closest", "furthest", "above", "right", "below", "left", "contains", "containedIn"
  </ResponseField>

  <ResponseField name="anchorConcept">
    Description of an object used as an anchor with `spatialRelation`.
  </ResponseField>

  <ResponseField name="prior">
    A optional global spatial location prior used for disambiguation among elements that have similar descriptions.
    Options are: "left", "right", "top", "bottom". For example, "left" means to choose the left-most element among candidates.
  </ResponseField>

  <ResponseField name="position">
    Position within the frame of an element to click. Options are: topleft, topcenter, topright, middleleft, center,
    middleright, bottomleft, bottomcenter, bottomright, anywhere
  </ResponseField>

  <ResponseField name="includeInvisible">
    Whether or not to find the target from sections of the page that are not currently visible (i.e., needs scrolling).
  </ResponseField>

  <ResponseField name="waitForLoadComplete">
    If true, waits for page to finish loading after the click.
  </ResponseField>

  <ResponseField name="waitTime">
    Integer number of seconds to wait after click.
  </ResponseField>
</Expandable>

### Move

Moves the cursor to an object. Disambiguate by specifing the spatial relation between the target element and an anchor concept.
All parameters besides `to` have the same definition as those in the `Click` action.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Move({
      to: String = "",
      element: UIElement = null,
      spatialRelation: String = "",
      anchorConcept: String = "",
      prior: String = "none",
      includeInvisible: Bool = false,
      waitForLoadComplete: Bool = false,
      waitTime: Int = 0
  })
  ```

  ```javascript Move to textarea below verify insurance theme={null}
  Move({to: "textarea", spatialRelation: "below", anchorConcept: "verify insurance"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="to">
    Description of a target object to click. For higher accuracy, describe the target object by its role and value, e.g.
    "sign in button", "first name textfield".
  </ResponseField>

  <ResponseField name="mode">
    See definition in `Click`.
  </ResponseField>

  <ResponseField name="element">
    See definition in `Click`.
  </ResponseField>

  <ResponseField name="spatialRelation">
    See definition in `Click`.
  </ResponseField>

  <ResponseField name="anchorConcept">
    See definition in `Click`
  </ResponseField>

  <ResponseField name="prior">
    See definition in `Click`
  </ResponseField>

  <ResponseField name="includeInvisible">
    See definition in `Click`
  </ResponseField>

  <ResponseField name="waitForLoadComplete">
    See definition in `Click`
  </ResponseField>

  <ResponseField name="waitTime">
    See definition in `Click`
  </ResponseField>
</Expandable>

### Drag

Drag on the screen, starting from where the mouse is located

Returns:

<CodeGroup>
  ```javascript function theme={null}
  function Drag({
      to: String = "",
      element: UIElement = null,
      destinationApp: String = null
  })
  ```

  ```javascript drag to "testFolder" in Google Chrome theme={null}
  Drag({to: "testFolder", destinationApp: "Google Chrome"})
  ```

  ```javascript drag to "testFolder" in the same app theme={null}
  Drag({to: "testFolder"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="to">
    the destination of the drag action in string
  </ResponseField>

  <ResponseField name="element">
    the destination of the drag action as UI Element
  </ResponseField>

  <ResponseField name="destinationApp">
    the target app, if destination is not in the same application as the origin
  </ResponseField>
</Expandable>

### Scroll

Scroll on the screen in a specified direction.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Scroll({
      direction: String = "down",
      distance: Int = 200
  })
  ```

  ```javascript Scroll down theme={null}
  Scroll({direction: "down"})
  ```

  ```javascript Scroll up 500 pixels theme={null}
  Scroll({direction: "up", distance: 500})
  ```

  ```javascript Scroll left 200 pixels theme={null}
  Scroll({direction: "left", distance: 200})
  ```

  ```javascript Scroll right a bit theme={null}
  Scroll({direction: "right", distance: 100})
  ```

  ```javascript Scroll down to see more content theme={null}
  Scroll({direction: "down", distance: 300})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="direction">
    The direction to scroll (up, down, left, right) Default is down.
  </ResponseField>

  <ResponseField name="distance">
    The scroll distance in pixels. Default is 200.
  </ResponseField>
</Expandable>

## Perception

### stateSatisfies

Checks whether the current screen satisfies the specified condition.

This is useful for checking complex conditions that cannot be easily checked by [ConceptsExist](#ConceptsExist) with simple element descriptions.
However, it may be slower and use more tokens than `ConceptsExist` for large pages.

Returns: true if the current screen satisfies the condition, false otherwise.

<CodeGroup>
  ```javascript function theme={null}
  function stateSatisfies({
      condition: String
  })
  ```

  ```javascript if the current state requires login, then respond to the user to request login theme={null}
  if (stateSatisfies({condition: "requires login"})) {
      Respond({message: "Please log in", requireConfirm: true})
  }
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="condition">
    A condition to check on the current screen
  </ResponseField>
</Expandable>

### ConceptsExist

Checks whether all the concepts can be found on the current visible screen.
Each concept must be a substring of the text description of an element in the current focused application.
This is faster and more token-efficient than [stateSatisfies](#stateSatisfies) for checking conditions that can be represented by a small set of element descriptions.

<Tip>Use the element picker tool <img src="https://mintcdn.com/simular/PrNYTyoRhGytL_hQ/images/picker.png?fit=max&auto=format&n=PrNYTyoRhGytL_hQ&q=85&s=c24b9ec85a6e895d209ceb33eabc7253" style={{
    display: 'inline', 
    verticalAlign: 'middle', 
    borderRadius: '0.5rem',
    width: '20px',   // adjust size here
    height: '20px'   // optional, keeps it square
}} width="42" height="38" data-path="images/picker.png" /> to check the text description of any element in the currently focused application.</Tip>

Returns: If all concepts can be found, returns true, otherwise false.

<CodeGroup>
  ```javascript function theme={null}
  function ConceptsExist({
      concepts: [String]
  })
  ```

  ```javascript if there is a play button, click it theme={null}
  if (ConceptsExist({concepts: ["play button"]})) {
  click({at: "play button"})
  }
  ```

  ```javascript if the page has a sign in button and a log in button, ask user to log in theme={null}
  if (ConceptsExist({concepts: ["sign in button", "log in button"]})) {
  respond({message: "Could you log in?", requireConfirm: true})
  }
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="concepts">
    An array of target concepts to find.
  </ResponseField>
</Expandable>

### pageContent

Gets a JSON object containing the structural text content and base64 encoded image of the current screen.
This object can be sent to a vision-language model for answering questions about the current screen.

Returns: A JSON dictionary with the following fields:

* text: A text description of the current web page;
* imageFilePath: temporary location in memory of the screenshot (accessible by `ask`).

<CodeGroup>
  ```javascript function theme={null}
  function pageContent({
  })
  ```

  ```javascript What is the color of this page? theme={null}
  var content = pageContent({});
  var color = ask({prompt: "What is the color of this page? Return only the color:", context: content});
  ```
</CodeGroup>

## Text Generation

### ask

Runs a large vision-language model on the given input prompt string and a JSON dictionary context.
Often used after pageContent().

Returns: String response from a large vision language model.

<CodeGroup>
  ```javascript function theme={null}
  function ask({
      prompt: String, context: [[String: String]]
  })
  ```

  ```javascript write a poem about the content of the current page theme={null}
  var content = pageContent({});
  var output = ask({{prompt: "Write a poem about the content", context: content}});
  ```

  ```javascript check two pages' differences theme={null}
  var content1 = pageContent({});
  doSomething({})
  var content2 = pageContent({});
  var content = [content1,content2]
  var output = ask({{prompt: "What are the difference between these two pages? ", context: content}});
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="prompt">
    String query to a large vision language model.
  </ResponseField>

  <ResponseField name="context">
    Array of JSON dictionaries, each containing the following fields:

    * text: an optional text description of the current web page.
    * imageFilePath: an optional path in memory of a screenshot taken by `pageContent()`.

    Also accepts a single JSON dictionary, such as the output of `pageContent()`.
  </ResponseField>
</Expandable>

## Wait

### Wait

Put Agent into sleep state for a certain amount of time.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function Wait({
      waitTime: Int, unit: String = "s"
  })
  ```

  ```javascript Wait for 3s theme={null}
  Wait({waitTime: 3})
  ```

  ```javascript Wait for 500ms theme={null}
  Wait({waitTime: 500, unit: "ms"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="unit">
    Options are "s" for seconds (default) and "ms" for milliseconds.
  </ResponseField>

  <ResponseField name="waitTime">
    Duration of time to wait in the given units.
  </ResponseField>
</Expandable>

### WaitForConcepts

Waits until all concepts can be found in the current frontmost window.
If not all concepts can be found within 10 seconds, action returns failure

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function WaitForConcepts({
      concepts: [String]
  })
  ```

  ```javascript Wait for the log in button and sign up button to show up theme={null}
  WaitForConcepts({concepts: ["log in button", "sign up button"]})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="concepts">
    An array of target concepts to find.
  </ResponseField>
</Expandable>

## User interaction

### Respond

Respond to the user with a short message. Optionally require the user to give a yes/no answer or input text to proceed.

Returns:

* If `requireConfirm` is true, then this function returns true if the user chooses "yes", returns false if the user chooses "no".
* If `requireTextInput` is true, then returns the string value that the user submitted.
* Otherwise, returns true

<CodeGroup>
  ```javascript function theme={null}
  function Respond({
      message: String, 
      requireConfirm: Bool = false, 
      requireTextInput: Bool = false
  })
  ```

  ```javascript Ask the user for confirmation theme={null}
  Respond({message: "Could you confirm?", requireConfirm: true})
  ```

  ```javascript Output llmResult to the user theme={null}
  Respond({message: llmResult})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="message">
    A message to show to the user.
  </ResponseField>

  <ResponseField name="requireConfirm">
    Whether or not user confirmation is required to proceed with the remaining actions. Default is false.
    If requireConfirm is true, then the message must be phrased as a question, to which the only possible responses are "yes" and "no".
  </ResponseField>

  <ResponseField name="requireTextInput">
    Whether or not to require the user to input text before proceeding. Default is false.
    If requireTextInput is true, then the user will be prompted to input text after the message is shown.
  </ResponseField>
</Expandable>

## System IO

### CopyToClipboard

Copies a String to clipboard.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function CopyToClipboard({
      text: String
  })
  ```

  ```javascript copy cell to the clipboard theme={null}
  CopyToClipboard({text: cell})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="text">
    Text to be copied to the clipboard.
  </ResponseField>
</Expandable>

### GetFromClipboard

Get the content of the current clipboard.

Returns: Content of the currrent clipboard

<CodeGroup>
  ```javascript function theme={null}
  function GetFromClipboard({
  })
  ```

  ```javascript get the clipboard content theme={null}
  var clipboardContent = GetFromClipboard({})
  ```
</CodeGroup>

### SaveScreenshot

Takes a screenshot of an element on the screen or the whole screen, and saves the screenshot as a PNG to a file.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function SaveScreenshot({
      element: UIElement = null,
      fileName: String = null,
      directory: String = null
  })
  ```

  ```javascript Save screenshot of whole screen to screenshot.png theme={null}
  SaveScreenshot({fileName: "screenshot.png"})
  ```

  ```javascript Screenshot the group element and save to clipboard theme={null}
  SaveScreenshot({element: group})
  ```

  ```javascript Screenshot the table element and save to /User/path/to/screenshot/ theme={null}
  SaveScreenshot({element: table, directory: "/User/path/to/screenshot/"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="element">
    If provided, limit the screenshot to the frame of the element. Default is the whole screen.
  </ResponseField>

  <ResponseField name="fileName">
    Name for the image name, default is "simularSavedImage.png".
  </ResponseField>

  <ResponseField name="directory">
    Directory to save the image, default at desktop.
  </ResponseField>
</Expandable>

### ScreenshotToClipboard

Take a screenshot of an element or the current page and save it to the system clipboard

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function ScreenshotToClipboard({
      element: UIElement = null
  })
  ```

  ```javascript take screenshot and save to clipboard theme={null}
  ScreenshotToClipboard({})
  ```

  ```javascript get the table element on the page, save a screenshot of it to clipboard theme={null}
  var elements = GetElements({elementRoles: ["table"]})
  ScreenshotToClipboard({element: elements[0]})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="element">
    If provided, limit the screenshot to the frame of the element. Default is the whole screen.
  </ResponseField>
</Expandable>

### ReadFile

Read the contents of a file whose location is specified by `path`.

Returns: Contents of the file as a String

<CodeGroup>
  ```javascript function theme={null}
  function ReadFile({
      path: String
  })
  ```

  ```javascript read the file named results.json theme={null}
  var results = ReadFile({path: "results.json"})
  ```

  ```javascript get contents of file /Users/somebody/Documents/project/links.txt theme={null}
  var links = ReadFile({path: "/Users/somebody/Documents/project/links.txt"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="path">
    Either an absolute path to a file, or a name of a file (assumed to be in the default app cache directory).
  </ResponseField>
</Expandable>

### WriteToFile

Writes the given text to a file. If the file already exists, then appends text to it, with an option to overwrite the existing content.
Unless specified path, writes to /Library/Caches/com.simular.Simular-Pro/SimularActionResult/
Will throw an error if there is an existing non-folder file named SimularActionResult

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function WriteToFile({
      text: String,
      path: String? = "SimularActionResult.txt",
      overwrite: Bool = false
  })
  ```

  ```javascript Append jsonResult to /User/somebody/Documents/result.json theme={null}
  WriteToFile({text: jsonResult, path: "/User/somebody/Documents/result.json"})
  ```

  ```javascript Write jsonResult to /User/someone/Desktop/result.json, overwrite existing file. theme={null}
  WriteToFile({text: jsonResult, path: "/User/someone/Desktop/result.json", overwrite: true})
  ```

  ```javascript Write jsonResult to default action result file, overwrite existing file. theme={null}
  WriteToFile({text: jsonResult, overwrite: true})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="text">
    Text to write to a file.
  </ResponseField>

  <ResponseField name="path">
    path of the file, default at /Library/Caches/com.simular.Simular-Pro/SimularActionResult/{path}.txt. If path contains "/", treat it as full path
  </ResponseField>

  <ResponseField name="overwrite">
    Whether or not to overwrite the contents if filePath points to an existing file.
  </ResponseField>
</Expandable>

## Google Sheet control

### GetGoogleSheetCellValue

Gets the value of a cell in a Google Sheet.

Returns: Value of the cell

<CodeGroup>
  ```javascript function theme={null}
  function GetGoogleSheetCellValue({
      cell: String
  })
  ```

  ```javascript get the description of cell B42. theme={null}
  var cellValue = GetGoogleSheetCellValue({cell: "B42"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="cell">
    Label of a cell. Column is indicated by a capital letter and row is indicated by a number.
    For example "B42" is the cell at column B row 42.
  </ResponseField>
</Expandable>

### SetGoogleSheetCellValue

Sets the value of a Google Sheet cell.

Returns: None

<CodeGroup>
  ```javascript function theme={null}
  function SetGoogleSheetCellValue({
      cell: String, value: String
  })
  ```

  ```javascript write "Simular" into cell B42 theme={null}
  SetGoogleSheetCellValue({cell: "B42", value: "Simular"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="cell">
    Label of a cell. Column is indicated by a capital letter and row is indicated by a number. For example "B42"
    is the cell at column B row 42.
  </ResponseField>

  <ResponseField name="value">
    value to write to the cell
  </ResponseField>
</Expandable>

### GetGoogleSheetColumns

Gets the column ids of each header in a given array of column headers in a Google Sheet.
For example, if the sheet has column headers "website", "description", "date" in cells A1, B1, C1, respectively, then `GetGoogleSheetColumns(headers: ["website", "description", "date"])` returns \["A", "B", "C"]
Note: This function currently assumes that the table headers are on row 1.

Returns: Array of column id, each is a capital letter from A to Z

<CodeGroup>
  ```javascript function theme={null}
  function GetGoogleSheetColumns({
      headers: [String]
  })
  ```

  ```javascript get the columns for the headers "description" and "website" theme={null}
  var columns = GetGoogleSheetColumns({headers: ["description", "website"]})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="headers">
    Array of column header
  </ResponseField>
</Expandable>

## Advanced GUI functions

### GetElements

Get elements that satisfy some conditions inside the current frontmost application or inside a root element (if given).
For disambiguation, one can constrain the search to elements that satisfy certain spatial relations to anchor elements.
This function supports multiple return types according to `returnType`.

Returns: Depending on returnType: \[UIElement], String, \[String], \[String: UIElement]

<CodeGroup>
  ```javascript function theme={null}
  function GetElements({
      elementRoles: [String] = [],
      elementOverallDescription: String = "",
      threshold: Double = 0.75,
      root: UIElement = null,
      spatialRelation: String = "",
      anchorRole: String = "",
      anchorOverallDescription: String = "",
      anchorElements: [UIElement] = [],
      horizontalRank: Int = null,
      verticalRank: Int = null,
      sortBy: String = "",
      useNeighborForMissingDescription: Bool = false,
      returnType: String = "elementArray"
  })
  ```

  ```javascript get all links from the page theme={null}
  var allLinks = GetElements({elementRoles: ["link"]})
  ```

  ```javascript Get all comboBox elements to the right of text "state selection" theme={null}
  var comboBoxes = GetElements({elementRoles: ["comboBox"], spatialRelation: "right", anchorRole: "staticText", anchorOverallDescription: "state selection"})
  ```

  ```javascript Get all cells in the table and return as dictionary theme={null}
  var cellDict = GetElements({elementRoles: ["cell"], spatialRelation: "containedIn", anchorRole: "table", returnType: "strToElemDict"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="elementRoles">
    Constrains the search to elements whose role is included in this array of roles.
    Required if elementOverallDescription is not given.
  </ResponseField>

  <ResponseField name="elementOverallDescription">
    Description of elements to get from the page. Required if elementRoles are not provided.
  </ResponseField>

  <ResponseField name="threshold">
    If `elementOverallDescription` is given, then accept candidate elements whose normalized string
    similarity to `elementOverallDescription` is above this threshold value.
  </ResponseField>

  <ResponseField name="root">
    If given, then the search is limited to elements contained within this root element.
  </ResponseField>

  <ResponseField name="spatialRelation">
    A comma-separated String of spatial relationships between the target elements and the anchor.
    Available options are: "closest", "furthest", "above", "right", "below", "left", "contains", "containedIn", "sameRow", "sameColumn"
  </ResponseField>

  <ResponseField name="anchorRole">
    Role of element(s) used as anchor for spatial relation.
  </ResponseField>

  <ResponseField name="anchorOverallDescription">
    Description of an object used as an anchor with spatialRelation.
  </ResponseField>

  <ResponseField name="anchorElements">
    Elements to use as anchor for spatial relation constraints.
    If `anchorElements` is provided, then anchorRole and anchorOverallDescription are ignored.
  </ResponseField>

  <ResponseField name="horizontalRank">
    If given, sorts the elements by x-coordinate of frame midpoint and returns the element with this rank.
    Left-most element has rank 1.
  </ResponseField>

  <ResponseField name="verticalRank">
    If given, sorts the elements by y-coordinate of frame midpoint and returns the element with this rank.
    Top-most element has rank 1.
  </ResponseField>

  <ResponseField name="sortBy">
    Returns the found elements in sorted order, by "x" (left to right) or "y" (top to bottom).
    Used only if `returnType` is "elementArray".
  </ResponseField>

  <ResponseField name="useNeighborForMissingDescription">
    Whether or not to use the description of an element's neighbor
    as a substitute if the element's description is empty. This is only used if returnType involves returning element descriptions.
  </ResponseField>

  <ResponseField name="returnType">
    Options are: "elementArray" (default), "string", "stringArray", "strToElemDict".

    * elementArray: returns an array of UIElements
    * string: returns a semicolon-separated string of descriptions of found elements
    * stringArray: returns an array of String descriptions of found elements
    * strToElemDict: returns a \[String: Element] dictionary with element description as keys and corresponding element as value
  </ResponseField>
</Expandable>

### GetAttributeOfElement

Searches for an element that matches the input criteria and gets the element's value for a specified attribute.

Returns: String value of an attribute of an element

<CodeGroup>
  ```javascript function theme={null}
  function GetAttributeOfElement({
      elementRole: String = "",
      elementOverallDescription: String = "",
      attribute: String = "",
      threshold: Double = 0.75,
      root: UIElement = null,
      spatialRelation: String = "",
      anchorRole: String = "",
      anchorOverallDescription: String = "",
      anchorElements: [UIElement] = [],
      horizontalRank: Int = null,
      verticalRank: Int = null
  })
  ```

  ```javascript Get the value of the radioButton element with description "radioButton tab point & click" theme={null}
  var value = GetAttributeOfElement({elementRole: "radioButton", elementOverallDescription: "radioButton tab point & click", attribute: "value"})
  ```

  ```javascript Get the value of the valueIndicator element closest to and on the right of "statictext text double-click speed" theme={null}
  var value = GetAttributeOfElement({elementRole: "valueIndicator", attribute: "value", spatialRelation: "closest,right", anchorOverallDescription: "statictext text double-click speed"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="elementRole">
    Role of the target element. Required if elementOverallDescription is not given.
  </ResponseField>

  <ResponseField name="elementOverallDescription">
    Description of the element. Required if elementRoles are not provided.
  </ResponseField>

  <ResponseField name="attribute">
    Valid options are: "role", "description", "title", "value". For example, use "value" to get the value of text elements.
  </ResponseField>

  <ResponseField name="threshold">
    If `elementOverallDescription` is given, then accept candidate elements whose normalized string similarity with `elementOverallDescription` is above this threshold value.
  </ResponseField>

  <ResponseField name="root">
    If given, then the search is limited to elements contained within this root element.
  </ResponseField>

  <ResponseField name="spatialRelation">
    A comma-separated String of spatial relationships between the target elements and the anchor.
  </ResponseField>

  <ResponseField name="anchorRole">
    Role of element(s) used as anchor for spatial relation.
  </ResponseField>

  <ResponseField name="anchorOverallDescription">
    Description of an object used as an anchor with spatialRelation.
  </ResponseField>

  <ResponseField name="anchorElements">
    Elements to use as anchor for spatial relation constraints. If `anchorElements` is provided, then anchorRole and anchorOverallDescription are ignored.
  </ResponseField>

  <ResponseField name="horizontalRank">
    If given, sorts the elements by x-coordinate of frame midpoint and returns the element with this rank. Left-most element has rank 1.
  </ResponseField>

  <ResponseField name="verticalRank">
    If given, sorts the elements by y-coordinate of frame midpoint and returns the element with this rank. Top-most element has rank 1.
  </ResponseField>
</Expandable>

### GetContent

Get text content from the current frontmost window or a region corresponding to the provided concept or element.

Returns: If `inElement` argument is given or the frontmost window was used (because neither `inConcept` nor
`inElement` was given), then returns a single String. Otherwise, returns a \[String] array with one String per root element.

<CodeGroup>
  ```javascript function theme={null}
  function GetContent({
      inConcept: String = "",
      inElement: UIElement = null,
      format: String = "flat"
  })
  ```

  ```javascript get content from page in json format theme={null}
  var pageContent = GetContent({format: "json"})
  ```

  ```javascript get content from the table element in XML slim format theme={null}
  var tableContent = GetContent({inElement: table, format: "xmlSlim"})
  ```

  ```javascript get content inside group job post details theme={null}
  var groupContent = GetContent({inConcept: "group job post details"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="inConcept">
    Gets content in elements that match this concept.
  </ResponseField>

  <ResponseField name="inElement">
    Get content in this element.
  </ResponseField>

  <ResponseField name="format">
    Format of the returned content. Options are: "flat" (unformatted text), "json", "xml", "xmlSlim" (same as XML, with empty tags removed)
  </ResponseField>
</Expandable>

### GetCells

Get all cells from a row or column element. Either row or column must be given.

Returns: An array of cell elements contained in the given row or column. If input is a row, the output array is sorted by
increasing x-coordinate (left to right). If input is a column, the output array is sorted by increasing y-coordinate (top to bottom).

<CodeGroup>
  ```javascript function theme={null}
  function GetCells({
      row: UIElement = null, column: UIElement = null
  })
  ```

  ```javascript get all cells in the first row theme={null}
  var rows = GetElements({elementRoles: ["row"], sortBy: "y"})
  var cells = GetCells({row: rows[0]})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="row">
    A row element that contains one or more cells.
  </ResponseField>

  <ResponseField name="column">
    A column element that contains one or more cells.
  </ResponseField>
</Expandable>

### GetCellValue

Get the value of a given cell element.

Returns: Value contained in the cell.

<CodeGroup>
  ```javascript function theme={null}
  function GetCellValue({
      cell: UIElement
  })
  ```

  ```javascript Get the value of the cell theme={null}
  var cellValue = GetCellValue({cell: cell})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="cell">
    A cell element.
  </ResponseField>
</Expandable>

### GetCellLabel

Get the label of the given cell element in Excel.

Returns: cell's label String. Example: "A1"

<CodeGroup>
  ```javascript function theme={null}
  function GetCellLabel({
      cell: UIElement
  })
  ```

  ```javascript Get the label of the cell theme={null}
  var label = GetCellLabel({cell: cell})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="cell">
    A cell element
  </ResponseField>
</Expandable>

### GetCellIndices

Given an array of table cell values, return a corresponding array of cell indices.
For example, suppose the table has value1 in cell A10, then `GetCellIndices(cellValues: ["value1"])` returns \["A10"]

Returns: \[String] array of cell indices

<CodeGroup>
  ```javascript function theme={null}
  function GetCellIndices({
      cellValues: [String]
  })
  ```

  ```javascript Get the indices of the cells containing value1 and value2 theme={null}
  var cellIndices = GetCellIndices({cellValues: ["value1", "value2"]})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="cellValues">
    values of the cell
  </ResponseField>
</Expandable>

### GetTableColumn

Given a header or  a index String, return the column under it as \[index: Element] dictionary
If the table has a column with header "Website" in cell A1, and elements elem1 and elem2 under it, then this
function returns \["A2": elem1, "A3": elem2].

Returns: Dictionary of \[String: UIElement] pair for all information in the column under header

<CodeGroup>
  ```javascript function theme={null}
  function GetTableColumn({
      header: String = null, index: String = null
  })
  ```

  ```javascript Get the columns under Website theme={null}
  var websiteColumn = GetTableColumn({header: "Website"})
  ```

  ```javascript Get the columns under index A1 theme={null}
  var A1Column = GetTableColumn({index: "A1"})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="header">
    value of column header.
  </ResponseField>

  <ResponseField name="index">
    index of column header, e.g. "B42".
  </ResponseField>
</Expandable>

### GetStructuredDescription

Gets XML-formatted description of the contents in each element.

Returns: An array of String `[s_1, ..., s_n]`, where each `s_i` is an XML-formatted description of the contents
rooted at `u_i`.

<CodeGroup>
  ```javascript function theme={null}
  function GetStructuredDescription({
      fromElements: [UIElement]
  })
  ```

  ```javascript get the elements with role "group" and description "group under plan progress", then get description of the elements in XML format theme={null}
  var elements = GetElements({elementRoles: ["group"], elemOverallDescription: "group under plan progress"})
  var description = GetStructuredDescription({fromElements: elements})
  ```
</CodeGroup>

<Expandable title="Parameters">
  <ResponseField name="fromElements">
    An array of UIElements `[u_1, ..., u_n]`.
  </ResponseField>
</Expandable>