# cp.ui.ScrollArea
A `ScrollArea` represents an `AXScrollArea`. They primarily function as a "portal"
to view a larger area of the contained `axuielement` within (accessed via the `AXContents` attribute),
and also provide access to the vertical and horizontal scroll bars (accessed via the
`verticalScrollBar` and `horizontalScrollBar` properties).
The class that wraps the `AXContents` attribute can be provided via the `contentsInit` parameter in the
constructor. If not provided it defaults to [Element](cp.ui.Element.md).
The `ScrollArea` also delegates to the `contents` property, so you can access
any properties of the contained [Element](cp.ui.Element.md) directly.
For example, if you have a `ScrollArea` with a `contents` of a [TextField](cp.ui.TextField.md),
you can normally access the text value via the [TextField.value](cp.ui.TextField.md#value) property.
However, if you want to access the text value via the `ScrollArea` itself, you can do so
via the `ScrollArea.value` property, like so:
```lua
local scrollArea = ScrollArea(parent, ui, TextArea)
-- via `contents`:
local value = scrollArea.contents:value()
--- via delegation:
local value = scrollArea:value()
```
It also has a [Builder](cp.ui.ScrollArea.Builder.md) that supports customising an `Element` [Builder](cp.ui.Builder.md)
to create a `ScrollArea` with a specified `contents` `Element` type. For example, another way to
define our `ScrollArea` that contains a `TextField` is:
```lua
local scrollAreaWithTextField = ScrollArea:containing(TextField)
local scrollArea = scrollAreaWithTextField(parent, ui)
```
The main advantage of this style is that you can pass the `Builder` in to other `Element` types
that require an "`Element` init" that will only be provided a parent and UI finder.
This is a subclass of [Element](cp.ui.Element.md).
---
## Submodules
* [cp.ui.ScrollArea.Builder](cp.ui.ScrollArea.Builder.md)
---
## API Overview
**Functions** - _API calls offered directly by the extension_
* [containing](#containing)
* [matches](#matches)
**Constructors** - _API calls which return an object, typically one that offers API methods_
* [ScrollArea](#scrollarea)
**Fields** - _Variables which can only be accessed from an object returned by a constructor_
* [contents](#contents)
* [contentsUI](#contentsui)
* [horizontalScrollBar](#horizontalscrollbar)
* [selectedChildrenUI](#selectedchildrenui)
* [verticalScrollBar](#verticalscrollbar)
* [viewFrame](#viewframe)
**Methods** - _API calls which can only be made on an object returned by a constructor_
* [childrenUI](#childrenui)
* [deselectAll](#deselectall)
* [loadLayout](#loadlayout)
* [saveLayout](#savelayout)
* [selectAll](#selectall)
* [selectChild](#selectchild)
* [selectChildAt](#selectchildat)
* [shiftHorizontalBy](#shifthorizontalby)
* [shiftHorizontalTo](#shifthorizontalto)
* [shiftVerticalBy](#shiftverticalby)
* [shiftVerticalTo](#shiftverticalto)
* [showChild](#showchild)
* [showChildAt](#showchildat)
---
## API Documentation
#### Functions
### [containing](#containing)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:containing(elementInit) -> cp.ui.ScrollArea.Builder` |
| **Type** | Function |
| **Description** | A static method that returns a new `ScrollArea.Builder`. |
| **Parameters** | - elementInit - An `Element` initializer.
|
| **Returns** | - A new `ScrollArea.Builder` instance.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 71](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L71) |
---
### [matches](#matches)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.matches(element) -> boolean` |
| **Type** | Function |
| **Description** | Checks to see if an element matches what we think it should be. |
| **Parameters** | - element - An `axuielementObject` to check.
|
| **Returns** | - `true` if matches otherwise `false`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 85](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L85) |
---
#### Constructors
### [ScrollArea](#scrollarea)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea(parent, uiFinder[, contentsInit]) -> cp.ui.ScrollArea` |
| **Type** | Constructor |
| **Description** | Creates a new `ScrollArea`. |
| **Parameters** | - parent - The parent object.
- uiFinder - A `function` or `cp.prop` which will return the `hs.axuielement` when available.
- contentsInit - An optional function to initialise the `contentsUI`. Uses `cp.ui.Element` by default.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 96](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L96) |
---
#### Fields
### [contents](#contents)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.contents ` |
| **Type** | Field |
| **Description** | Returns the `Element` representing the `ScrollArea` Contents. |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 119](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L119) |
---
### [contentsUI](#contentsui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.contentsUI ` |
| **Type** | Field |
| **Description** | Returns the `axuielement` representing the Scroll Area Contents, or `nil` if not available. |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 112](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L112) |
---
### [horizontalScrollBar](#horizontalscrollbar)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.horizontalScrollBar ` |
| **Type** | Field |
| **Description** | The horizontal [ScrollBar](cp.ui.ScrollBar.md). |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 133](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L133) |
---
### [selectedChildrenUI](#selectedchildrenui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.selectedChildrenUI ` |
| **Type** | Field |
| **Description** | Returns the `axuielement` representing the Scroll Area Selected Children, or `nil` if not available. |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 140](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L140) |
---
### [verticalScrollBar](#verticalscrollbar)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.verticalScrollBar ` |
| **Type** | Field |
| **Description** | The vertical [ScrollBar](cp.ui.ScrollBar.md). |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 126](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L126) |
---
### [viewFrame](#viewframe)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea.viewFrame ` |
| **Type** | Field |
| **Description** | A `cp.prop` reporting the Scroll Area frame as a table containing `{x, y, w, h}`. |
| **Notes** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 171](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L171) |
---
#### Methods
### [childrenUI](#childrenui)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:childrenUI(filterFn) -> hs.axuielement | nil` |
| **Type** | Method |
| **Description** | Returns the list of `axuielement`s representing the Scroll Area Contents, sorted top-down, or `nil` if not available. |
| **Parameters** | - filterFn - The function which checks if the child matches the requirements.
|
| **Returns** | - The `axuielement` or `nil`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 153](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L153) |
---
### [deselectAll](#deselectall)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:deselectAll() -> self` |
| **Type** | Method |
| **Description** | Deselect all children in a scroll area. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 305](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L305) |
---
### [loadLayout](#loadlayout)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:loadLayout(layout) -> none` |
| **Type** | Method |
| **Description** | Loads a Scroll Area layout. |
| **Parameters** | - layout - A table containing the ScrollArea layout settings, typically created using [saveLayout](#saveLayout).
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 393](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L393) |
---
### [saveLayout](#savelayout)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:saveLayout() -> table` |
| **Type** | Method |
| **Description** | Saves the current Scroll Area layout to a table. |
| **Parameters** | |
| **Returns** | - A table containing the current Scroll Area Layout.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 374](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L374) |
---
### [selectAll](#selectall)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:selectAll(childrenUI) -> self` |
| **Type** | Method |
| **Description** | Select all children in a scroll area. |
| **Parameters** | - childrenUI - A table of `hs.axuielement` objects.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 286](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L286) |
---
### [selectChild](#selectchild)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:selectChild(childUI) -> self` |
| **Type** | Method |
| **Description** | Select a specific child within a Scroll Area. |
| **Parameters** | - childUI - The `hs.axuielement` object of the child you want to select.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 250](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L250) |
---
### [selectChildAt](#selectchildat)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:selectChildAt(index) -> self` |
| **Type** | Method |
| **Description** | Select a child element in a Scroll Area given a specific index. |
| **Parameters** | - index - The index of the child you want to select.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 269](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L269) |
---
### [shiftHorizontalBy](#shifthorizontalby)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:shiftHorizontalBy(amount) -> number` |
| **Type** | Method |
| **Description** | Attempts to shift the horizontal scroll bar by the specified amount. |
| **Parameters** | - amount - The amount to shift
|
| **Returns** | - The actual value of the horizontal scroll bar.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 322](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L322) |
---
### [shiftHorizontalTo](#shifthorizontalto)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:shiftHorizontalTo(value) -> number` |
| **Type** | Method |
| **Description** | Attempts to shift the horizontal scroll bar to the specified value. |
| **Parameters** | - value - The new value (typically between `0` and `1`).
|
| **Returns** | - The actual value of the horizontal scroll bar.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 335](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L335) |
---
### [shiftVerticalBy](#shiftverticalby)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:shiftVerticalBy(amount) -> number` |
| **Type** | Method |
| **Description** | Attempts to shift the vertical scroll bar by the specified amount. |
| **Parameters** | - amount - The amount to shift
|
| **Returns** | - The actual value of the vertical scroll bar.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 348](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L348) |
---
### [shiftVerticalTo](#shiftverticalto)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:shiftVerticalTo(value) -> number` |
| **Type** | Method |
| **Description** | Attempts to shift the vertical scroll bar to the specified value. |
| **Parameters** | - value - The new value (typically between `0` and `1`).
|
| **Returns** | - The actual value of the vertical scroll bar.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 361](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L361) |
---
### [showChild](#showchild)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:showChild(childUI) -> self` |
| **Type** | Method |
| **Description** | Show's a child element in a Scroll Area. |
| **Parameters** | - childUI - The `hs.axuielement` object of the child you want to show.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 195](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L195) |
---
### [showChildAt](#showchildat)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.ui.ScrollArea:showChildAt(index) -> self` |
| **Type** | Method |
| **Description** | Show's a child element in a Scroll Area given a specific index. |
| **Parameters** | - index - The index of the child you want to show.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/ui/ScrollArea.lua line 233](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/ScrollArea.lua#L233) |
---
---