Skip to main content

State

This class wraps a value in getters and setters, its main purpose is to allow primatives to be passed as objects. Constructors for this class are available in Iris 

local state = Iris.State(0) -- we initialise the state with a value of 0

-- these are equivalent. Ideally you should use `:get()` and ignore `.value`.
print(state:get())
print(state.value)

state:set(state:get() + 1) -- increments the state by getting the current value and adding 1.

state:onChange(function(newValue)
    print(`The value of the state is now: {newValue}`)
end)
Caution: Callbacks

Never call :set() on a state when inside the :onChange() callback of the same state. This will cause a continous callback.

Never chain states together so that each state changes the value of another state in a cyclic nature. This will cause a continous callback.

Types​

State<T>​

</>
type State<T> = {
ID: ID,
value: T,
get: (self) → T,
set: (
self,
newValue: T
) → T,
onChange: (
self,
callback: (newValue: T) → ()
) → (),
ConnectedWidgets: {[ID]: Widget},
ConnectedFunctions: {(newValue: T) → ()}
}

Functions​

get<T>​

</>
State:get<T>() → T

Returns the states current value.

set<T>​

</>
State:set<T>(
newValue: T,
force: boolean?--

force an update to all connections

) → T

Allows the caller to assign the state object a new value, and returns the new value.

onChange<T>​

</>
State:onChange<T>(callback: (newValue: T) → ()) → () → ()

Allows the caller to connect a callback which is called when the states value is changed.

Caution: Single

Calling :onChange() every frame will add a new function every frame. You must ensure you are only calling :onChange() once for each callback for the state's entire lifetime.

changed<T>​

</>
State:changed<T>() → boolean

Returns true if the state was changed on this frame.

Show raw api
{
    "functions": [
        {
            "name": "get<T>",
            "desc": "Returns the states current value.\n    ",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 131,
                "path": "lib/Internal.lua"
            }
        },
        {
            "name": "set<T>",
            "desc": "Allows the caller to assign the state object a new value, and returns the new value.\n    ",
            "params": [
                {
                    "name": "newValue",
                    "desc": "",
                    "lua_type": "T"
                },
                {
                    "name": "force",
                    "desc": "force an update to all connections",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 144,
                "path": "lib/Internal.lua"
            }
        },
        {
            "name": "onChange<T>",
            "desc": "Allows the caller to connect a callback which is called when the states value is changed.\n\n:::caution Caution: Single\nCalling `:onChange()` every frame will add a new function every frame.\nYou must ensure you are only calling `:onChange()` once for each callback for the state's entire lifetime.\n:::\n    ",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(newValue: T) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 176,
                "path": "lib/Internal.lua"
            }
        },
        {
            "name": "changed<T>",
            "desc": "Returns true if the state was changed on this frame.\n    ",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 191,
                "path": "lib/Internal.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "State<T>",
            "desc": "",
            "lua_type": "{ ID: ID, value: T, get: (self) -> T, set: (self, newValue: T) -> T, onChange: (self, callback: (newValue: T) -> ()) -> (), ConnectedWidgets: { [ID]: Widget }, ConnectedFunctions: { (newValue: T) -> () } }",
            "source": {
                "line": 11,
                "path": "lib/WidgetTypes.lua"
            }
        }
    ],
    "name": "State",
    "desc": "This class wraps a value in getters and setters, its main purpose is to allow primatives to be passed as objects.\nConstructors for this class are available in [Iris]\n\n```lua\nlocal state = Iris.State(0) -- we initialise the state with a value of 0\n\n-- these are equivalent. Ideally you should use `:get()` and ignore `.value`.\nprint(state:get())\nprint(state.value)\n\nstate:set(state:get() + 1) -- increments the state by getting the current value and adding 1.\n\nstate:onChange(function(newValue)\n    print(`The value of the state is now: {newValue}`)\nend)\n```\n\n:::caution Caution: Callbacks\nNever call `:set()` on a state when inside the `:onChange()` callback of the same state. This will cause a continous callback.\n\nNever chain states together so that each state changes the value of another state in a cyclic nature. This will cause a continous callback.\n:::\n    ",
    "source": {
        "line": 121,
        "path": "lib/Internal.lua"
    }
}