# Control

This type represents an abstract GUI control.

## id <a href="#id" id="id"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1][<kbd><mark style="background-color:orange;">**Read only**<mark style="background-color:orange;"></kbd>](#user-content-fn-2)[^2]

Type: `int`

Control ID.

***

## idString <a href="#id-string" id="id-string"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1][<kbd><mark style="background-color:orange;">**Read only**<mark style="background-color:orange;"></kbd>](#user-content-fn-2)[^2]

Type: `string`

String representation of control's ID. This may be empty for some controls.

***

## isVisible <a href="#is-visible" id="is-visible"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1][<kbd><mark style="background-color:orange;">**Read only**<mark style="background-color:orange;"></kbd>](#user-content-fn-2)[^2]

Type: `bool`

Control's visibility state.

***

## parent <a href="#parent" id="parent"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1][<kbd><mark style="background-color:orange;">**Read only**<mark style="background-color:orange;"></kbd>](#user-content-fn-2)[^2]

Type: `control?`

Parent control. Might be `nil` on some controls.

***

## type <a href="#type" id="type"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1][<kbd><mark style="background-color:orange;">**Read only**<mark style="background-color:orange;"></kbd>](#user-content-fn-2)[^2]

Type: [`ControlType`](/api/instances/gui/control/controltype.md)

Control's type.

***

## inactive <a href="#inactive" id="inactive"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `bool`

If set to `true`, will mark this control to the inactive state.

***

## inactiveText <a href="#inactive-text" id="inactive-text"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `string`

Tooltip replacement to show when control is inactive.

***

## inactiveColor <a href="#inactive-color" id="inactive-color"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: [`Color`](/api/instances/draw/types/color.md)

Label color override for inactive controls.

***

## tooltip <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `string`

Tooltip text.

***

## pos <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: [`Vec2`](/api/instances/draw/types/vec2.md)

Relative position of this control

***

## size <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: [`Vec2`](/api/instances/draw/types/vec2.md)

Total size of this control

***

## sizeToParentW <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

Whether or not the width of this control is locked to it's parent container

***

## sizeToParentH <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

Whether or not the height of this control is locked to it's parent container

***

## isTakingInput <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

{% hint style="warning" %}
May not be available for all controls.
{% endhint %}

Whether or not this control handles input in any way.

***

## isTakingKeys <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

{% hint style="warning" %}
May not be available for all controls.
{% endhint %}

Whether or not this control is listening to generic key presses.

***

## isTakingText <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

{% hint style="warning" %}
May not be available for all controls.
{% endhint %}

Whether or not this control is listening and handling text input.

***

## margin <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `rect`

The margin/offset to the parent container. Left, top, right and bottom, respectively.

***

## isMouseOnMe <a href="#tooltip" id="tooltip"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `boolean`

{% hint style="warning" %}
May not be available for all controls.
{% endhint %}

Whether or not the user is hovering this control.

***

## aliases <a href="#aliases" id="aliases"></a>

[<kbd><mark style="background-color:purple;">**Field**<mark style="background-color:purple;"></kbd>](#user-content-fn-1)[^1]

Type: `table[string]`

Alias list for this control. Used in search box to support different naming (e.g. if a user searches for "Double tap", will find "Rapid fire" instead).

***

## GetPosAbs <a href="#get-pos-abs" id="get-pos-abs"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns this control's position relative to the screen origin (`0, 0`).

**Arguments**

None.

**Returns**

| Type                                        | Description                        |
| ------------------------------------------- | ---------------------------------- |
| [`Vec2`](/api/instances/draw/types/vec2.md) | Absolute position of this control. |

**Example**

```lua
local screen_pos = ctrl:GetPosAbs();
```

***

## GetArea <a href="#get-area" id="get-area"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns a rectangle containing the area of this control relative to the current container.

**Arguments**

| Name            | Type      | Description                                       |
| --------------- | --------- | ------------------------------------------------- |
| `includeMargin` | `boolean` | Whether or not to include the margin in the area. |

**Returns**

| Type                                        | Description                              |
| ------------------------------------------- | ---------------------------------------- |
| [`Rect`](/api/instances/draw/types/rect.md) | Area of this control in container space. |

**Example**

```lua
local area = ctrl:GetArea();
```

***

## GetAreaAbs <a href="#get-area-abs" id="get-area-abs"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns a rectangle containing the area of this control relative to the screen origin (`0, 0`).

**Arguments**

| Name            | Type      | Description                                       |
| --------------- | --------- | ------------------------------------------------- |
| `includeMargin` | `boolean` | Whether or not to include the margin in the area. |

**Returns**

| Type                                        | Description                           |
| ------------------------------------------- | ------------------------------------- |
| [`Rect`](/api/instances/draw/types/rect.md) | Area of this control in screen space. |

**Example**

```lua
local screen_area = ctrl:GetAreaAbs();
```

***

## GetLabel <a href="#get-label" id="get-label"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns the label of this control in the menu.

{% hint style="warning" %}
This does not work for [`label`](/api/instances/gui/control/label.md) types. Use the `text` field instead.
{% endhint %}

**Arguments**

None.

**Returns**

| Type                                           | Description            |
| ---------------------------------------------- | ---------------------- |
| [`Label`](/api/instances/gui/control/label.md) | Control label, if any. |

**Example**

```lua
local text = ctrl:GetLabel().text;
```

***

## GetHotkeyState <a href="#get-hotkey-state" id="get-hotkey-state"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns `true` if any of the control's hotkeys are active.

**Arguments**

None.

**Returns**

| Type   | Description                     |
| ------ | ------------------------------- |
| `bool` | `true` if any hotkey is active. |

**Example**

```lua
if ctrl:GetHotkeyState() then
    -- ...
end
```

***

## HasHotkeys <a href="#get-hotkey-state" id="get-hotkey-state"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Returns `true` if this control has any hotkeys.

**Arguments**

None.

**Returns**

| Type   | Description                    |
| ------ | ------------------------------ |
| `bool` | `true` if control has hotkeys. |

**Example**

```lua
if ctrl:HasHotkeys() then
    -- ...
end
```

***

## SetDimensions <a href="#for-each" id="for-each"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Overrides the offset and size for this control.

{% hint style="info" %}
This method does not override `sizeToParentW` and `sizeToParentH`.
{% endhint %}

**Arguments**

| Name       | Type                                        | Description |
| ---------- | ------------------------------------------- | ----------- |
| `position` | [`Vec2`](/api/instances/draw/types/vec2.md) | Offset      |
| `size`     | [`Vec2`](/api/instances/draw/types/vec2.md) | Size        |

**Returns**

Nothing.

**Example**

```lua
control:SetDimensions(draw.Vec2(), draw.Vec2(100, 24))
```

## SetVisible <a href="#set-visible" id="set-visible"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Changes visibility state for this control.

{% hint style="danger" %}
Calling this method on controls that are located in layouts with large amount of other controls will inevitably cause performance issues due to auto-stacking.
{% endhint %}

**Arguments**

| Name  | Type   | Description       |
| ----- | ------ | ----------------- |
| `val` | `bool` | Visibility state. |

**Returns**

Nothing.

**Example**

```lua
ctrl:SetVisible(false);
```

***

## AddCallback <a href="#add-callback" id="add-callback"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Adds a callback to this control.

**Arguments**

| Name  | Type       | Description |
| ----- | ---------- | ----------- |
| `cbk` | `function` | Callback.   |

**Returns**

Nothing.

**Example**

```lua
ctrl:AddCallback(function ()
    print('Callback invoked!');
end);
```

***

## Cast <a href="#cast" id="cast"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Attempts to downcast the control to the correct type.

{% hint style="success" %}
Due to Lua engine's limitations, it is impossible to automatically downcast variables. Usually there is no need to call this method, unless you found some control that wasn't somehow already cast to the desired type. `find()` methods automatically perform the cast to the correct type.
{% endhint %}

**Arguments**

None.

**Returns**

| Type        | Description       |
| ----------- | ----------------- |
| `<control>` | New type, if any. |

**Example**

```lua
local checkbox = maybe_checkbox:Cast();
```

***

## Reset <a href="#reset" id="reset"></a>

[<kbd><mark style="background-color:purple;">**Method**<mark style="background-color:purple;"></kbd>](#user-content-fn-3)[^3]

Resets control's state. This action is usually required if you change control's value directly by interacting with [`ValueParam`](/api/instances/gui/control/valueparam.md).

You also should call this method on layouts if you add multiple controls into them.

**Arguments**

None.

**Returns**

Nothing.

**Example**

```lua
ctrl:Reset();
```

***

[^1]: This field is a regular field that must be accessed using a dot (.)

[^2]: This field is a read only field, and you cannot change its value. This does not apply to child fields, if any.

[^3]: This field is a method and must be invoked using a colon (:)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lua2.fatality.win/api/instances/gui/control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.