Skip to main content

Stopwatch

Observable

Inherits Observable

Observable which counts up to a max value in realtime whenever played via Stopwatch:Play.

Includes utility methods for mapping this "elapsed time" value into more complex animationed sequences.

Includes utility methods for mapping this "remaining time" value into more complex animationed sequences.

Constructor

Dex.Stopwatch

Dex.Stopwatch({
    duration: number?,
    isPlaying: CanBeObservable<boolean>?,
    playOnChange: Observable<any>?,
}?) -> Stopwatch

Creates a new Stopwatch Observable, which simulates in realtime while subscribed.

Props:

duration is an optional prop that specifies the end time of the stopwatch. Defaults to math.huge.

isPlaying specifies that stopwatch should play and stop depending on an observable boolean value. If set to true, the stopwatch will immediately start playing.

playOnChange specifies that the stopwatch should restart whenever an input observable changes.

Stopwatches can safely be garbage collected while dereferenced, unsubscribed, and unused by a VirtualInstance.

INFO

Stopwatches must currently be Subscribed or Mounted to exhibit expected behavior. This is a requirement for all realtime-simulated observables, which enables safe garbage collection when writing Dex components.

Usage Example:

local stopwatch = Dex.Stopwatch({
    duration = 10,
    isPlaying = true,
})
local frame = Dex.New("Frame")({
    -- Opaque for 5 seconds, then fades to Transparent over 5 seconds:
    BackgroundTransparency = stopwatch:Alpha(5, 10),
})

Types​

StopwatchProps​

</>
interface StopwatchProps {
duration: number
isPlaying: CanBeObservable<boolean>?,
playOnChange: Observable<any>?,
}

Type that specifies the props for constructing a Stopwatch observable (via Dex.Stopwatch)

duration is an optional prop that specifies the end time of the stopwatch. Defaults to math.huge.

isPlaying specifies that stopwatch should play and stop depending on an observable boolean value. If set to true, the stopwatch will immediately start playing.

playOnChange specifies that the stopwatch should restart whenever an input observable changes.

Functions​

Play​

</>
Stopwatch:Play() → ()

Starts the Stopwatch Observable. The observable will update with new values every heartbeat in real-time until it is stopped.

Stop​

</>
Stopwatch:Stop() → ()

Stops the Stopwatch Observable, reseting the elapsed time.

Pause​

</>
Stopwatch:Pause() → ()

Pauses the Stopwatch Observable at its current elapsed time position.

Pause​

</>
Stopwatch:Pause() → ()

Sets the current elapsed time of the Stopwatch.

Lerp​

</>
Stopwatch:Lerp() → Observable<T>

Creates an observable that outputs an interpolated value between the start value and end value based on the current elapsed time.

Alpha​

</>
Stopwatch:Alpha(
startTime: number,
endTime: number
) → Alpha

Derives an observable number that maps the elasped time from 0 at the provided start time, and 1 at the provided end time.

Show raw api
{
    "functions": [
        {
            "name": "Play",
            "desc": "Starts the Stopwatch Observable. The observable will update with new\nvalues every heartbeat in real-time until it is stopped.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 15,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "Stops the Stopwatch Observable, reseting the elapsed time.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 35,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Pauses the Stopwatch Observable at its current elapsed time position.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 53,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Sets the current elapsed time of the Stopwatch.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 81,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Lerp",
            "desc": "Creates an observable that outputs an interpolated value between\nthe start value and end value based on the current elapsed time.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 107,
                "path": "src/Observables/Stopwatch.luau"
            }
        },
        {
            "name": "Alpha",
            "desc": "Derives an observable number that maps the elasped time from 0 at the\nprovided start time, and 1 at the provided end time.",
            "params": [
                {
                    "name": "startTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "endTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Alpha"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 132,
                "path": "src/Observables/Stopwatch.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "StopwatchProps",
            "desc": "Type that specifies the props for constructing a [Stopwatch] observable (via\n[Dex.Stopwatch])\n\n`duration` is an optional prop that specifies the end time of the stopwatch.\nDefaults to `math.huge`.\n\n`isPlaying` specifies that stopwatch should play and stop depending on an\nobservable boolean value. If set to `true`, the stopwatch will immediately\nstart playing.\n\n`playOnChange` specifies that the stopwatch should restart whenever an input\nobservable changes.",
            "fields": [
                {
                    "name": "duration",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "isPlaying",
                    "lua_type": "CanBeObservable<boolean>?,",
                    "desc": ""
                },
                {
                    "name": "playOnChange",
                    "lua_type": "Observable<any>?,",
                    "desc": ""
                }
            ],
            "source": {
                "line": 170,
                "path": "src/Observables/Stopwatch.luau"
            }
        }
    ],
    "name": "Stopwatch",
    "desc": "#### Inherits [Observable]\n\nObservable which counts up to a max value in realtime whenever played\nvia [Stopwatch:Play].\n\nIncludes utility methods for mapping this \"elapsed time\" value into more\ncomplex animationed sequences.\n\nIncludes utility methods for mapping this \"remaining time\" value into more\ncomplex animationed sequences.\n\n## Constructor\n\n---\n\n### Dex.Stopwatch\n```lua\nDex.Stopwatch({\n    duration: number?,\n    isPlaying: CanBeObservable<boolean>?,\n    playOnChange: Observable<any>?,\n}?) -> Stopwatch\n```\n\nCreates a new [Stopwatch] Observable, which simulates in realtime while\nsubscribed.\n\n#### Props:\n\n`duration` is an optional prop that specifies the end time of the stopwatch.\nDefaults to `math.huge`.\n\n`isPlaying` specifies that stopwatch should play and stop depending on an\nobservable boolean value. If set to `true`, the stopwatch will immediately\nstart playing.\n\n`playOnChange` specifies that the stopwatch should restart whenever an input\nobservable changes.\n\n----\nStopwatches can safely be garbage collected while dereferenced, unsubscribed,\nand unused by a VirtualInstance.\n\n:::info\nStopwatches must currently be ***Subscribed*** or ***Mounted*** to exhibit\nexpected behavior. This is a requirement for all realtime-simulated\nobservables, which enables safe garbage collection when writing Dex\ncomponents.\n:::\n\nUsage Example:\n```lua\nlocal stopwatch = Dex.Stopwatch({\n    duration = 10,\n    isPlaying = true,\n})\nlocal frame = Dex.New(\"Frame\")({\n    -- Opaque for 5 seconds, then fades to Transparent over 5 seconds:\n    BackgroundTransparency = stopwatch:Alpha(5, 10),\n})\n```",
    "tags": [
        "Observable"
    ],
    "source": {
        "line": 80,
        "path": "src/Observables/Stopwatch.luau"
    }
}