> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/object-apis/user-parameter.md).

# User Parameter

### Accessing User Parameters

The User Parameter Container is available under:

```python
sp.<ObjectID>.general.userParameter
```

For example:

```python
userParams = sp.Tracker1.general.userParameter
```

The returned object is an:

```
sp.ControllableContainer
```

### Creating a User Parameter

Use `addUserdata()` to create a new User Parameter.

#### Syntax

```python
userParams.addUserdata(name, type, initialValue)
```

#### Example

```python
userParams = sp.Tracker1.general.userParameter

result = userParams.addUserdata(
    "Counter",
    "int",
    13
)
```

#### Returns

A successful creation returns:

```
True
```

### Supported Types

The following type strings have been verified for `addUserdata()`:

| Type String | Initial Value | Parameter Value |
| ----------- | ------------- | --------------- |
| `"bool"`    | `bool`        | `bool`          |
| `"float"`   | `float`       | `float`         |
| `"int"`     | `int`         | `int`           |
| `"string"`  | `str`         | `str`           |
| `"text"`    | `str`         | `str`           |

#### Boolean

```python
userParams.addUserdata(
    "Enabled",
    "bool",
    True
)
```

#### Float

```python
userParams.addUserdata(
    "Distance",
    "float",
    12.5
)
```

#### Integer

```python
userParams.addUserdata(
    "Counter",
    "int",
    13
)
```

#### String

```python
userParams.addUserdata(
    "Device Name",
    "string",
    "Camera A"
)
```

#### Text

```python
userParams.addUserdata(
    "Description",
    "text",
    "Longer text content"
)
```

{% hint style="info" %}
Grid Studio provides additional User Parameter types in the UI. Only the type strings listed above have currently been verified for creation through `addUserdata()`.
{% endhint %}

### User Parameter Names

When a User Parameter is created, Grid Studio generates a scripting `shortName` from its display name.

For example:

```
Display Name     → Short Name

API Int          → apiInt
Immediate Test   → immediateTest
```

The generated `shortName` is used when accessing the User Parameter through scripting.

For example:

```python
sp.Tracker1.general.userParameter.apiInt
```

### Accessing the Parameter Handle

A created User Parameter behaves like a normal Grid Studio Parameter.

For example:

```python
parameter = sp.Tracker1.general.userParameter.apiInt
```

The current value is available through `.value`:

```python
value = sp.Tracker1.general.userParameter.apiInt.value
```

Values can also be changed normally:

```python
sp.Tracker1.general.userParameter.apiInt.value = 25
```

### `hasUserdata()`

Checks whether a User Parameter exists.

Use the Parameter's generated `shortName`.

#### Syntax

```python
userParams.hasUserdata(shortName)
```

#### Returns

`bool`

#### Example

```python
userParams = sp.Tracker1.general.userParameter

exists = userParams.hasUserdata(
    "apiInt"
)

print(exists)
```

### `getUserdata()`

Returns the current value of a User Parameter.

Use the Parameter's generated `shortName`.

#### Syntax

```python
userParams.getUserdata(shortName)
```

#### Example

```python
userParams = sp.Tracker1.general.userParameter

value = userParams.getUserdata(
    "apiFloat"
)

print(value)
```

`getUserdata()` returns the Parameter value directly rather than the Parameter handle.

{% hint style="info" %}
For Integer User Parameters, the Parameter's `.value` is an `int`, while `getUserdata()` currently returns the value as a `float`.

For example, an Integer value of `13` is returned by `getUserdata()` as `13.0`.
{% endhint %}

### Direct Access vs. `getUserdata()`

Use direct Parameter access when the Parameter handle itself is required:

```python
parameter = sp.Tracker1.general.userParameter.apiInt
```

Read or write its value using:

```python
parameter.value
```

Use `getUserdata()` when only the current value is required:

```python
value = sp.Tracker1.general.userParameter.getUserdata(
    "apiInt"
)
```

### Quick Reference

| API                                              | Description                              |
| ------------------------------------------------ | ---------------------------------------- |
| `object.general.userParameter`                   | Returns the User Parameter Container     |
| `addUserdata(name, type, initialValue)`          | Creates a User Parameter                 |
| `hasUserdata(shortName)`                         | Checks whether a User Parameter exists   |
| `getUserdata(shortName)`                         | Returns the current User Parameter value |
| `object.general.userParameter.<shortName>`       | Returns the User Parameter handle        |
| `object.general.userParameter.<shortName>.value` | Reads or writes the Parameter value      |