mirror of
https://github.com/britzl/monarch.git
synced 2025-06-27 10:27:49 +02:00
266 lines
10 KiB
Markdown
266 lines
10 KiB
Markdown
|
|
# Monarch API
|
|
|
|
## monarch.show(screen_id, [options], [data], [callback])
|
|
Show a Monarch screen. Note that the screen must be registered before it can be shown. The `init()` function of the screen script (either `screen_proxy.script` or `screen_factory.script`) takes care of registration. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to show.
|
|
* `options` (table) - Options when showing the new screen (see below).
|
|
* `data` (table) - Optional data to associate with the screen. Retrieve using `monarch.data()`.
|
|
* `callback` (function) - Optional function to call when the new screen is visible.
|
|
|
|
The options table can contain the following fields:
|
|
|
|
* `clear` (boolean) - If the `clear` flag is set Monarch will search the stack for the screen that is to be shown. If the screen already exists in the stack and the clear flag is set Monarch will remove all screens between the current top and the screen in question.
|
|
* `reload` (boolean) - If the `reload` flag is set Monarch will reload the collection proxy if it's already loaded (this can happen if the previous screen was a popup).
|
|
* `no_stack` (boolean) - If the `no_stack` flag is set Monarch will load the screen without adding it to the screen stack.
|
|
* `sequential` (boolean) - If the `sequential` flag is set Monarch will start loading the screen only after the previous screen finished transitioning out.
|
|
* `pop` (number) - If `pop` is set to a number, Monarch will pop that number of screens from the stack before adding the new one.
|
|
|
|
## monarch.replace(screen_id, [options], [data], [callback])
|
|
Replace the top of the stack with a new screen. Equivalent to calling `monarch.show()` with `pop = 1`. It takes the same parameters as `monarch.show()`.
|
|
|
|
|
|
## monarch.hide(screen_id, [callback])
|
|
Hide a screen that has been shown using the `no_stack` option. If used on a screen that was shown without the `no_stack` option it will only hide it if the screen is on top of the stack and the behavior will be exactly like if `monarch.back()` had been called. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to hide.
|
|
* `callback` (function) - Optional function to call when the screen has been hidden.
|
|
|
|
**RETURN**
|
|
* `success` (boolean) - True if the process of hiding the screen was started successfully.
|
|
|
|
|
|
## monarch.clear([callback])
|
|
Clear the stack of screens completely. Any visible screen will be hidden by navigating back out from them. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `callback` (function) - Optional function to call when the stack has been cleared.
|
|
|
|
|
|
## monarch.back([options], [data], [callback])
|
|
Go back to a previous Monarch screen. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `options` (table) - Options when showing the new screen (see below).
|
|
* `data` (table) - Optional data to associate with the screen you are going back to. Retrieve using `monarch.data()`.
|
|
* `callback` (function) - Optional function to call when the previous screen is visible.
|
|
|
|
The options table can contain the following fields:
|
|
|
|
* `sequential` (boolean) - If the `sequential` flag is set Monarch will start loading the screen only after the previous screen finished transitioning out.
|
|
|
|
|
|
## monarch.preload(screen_id, [options], [callback])
|
|
Preload a Monarch screen. This will load but not enable the screen. This is useful for content heavy screens that you wish to be able to show without having to wait for it load. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to preload.
|
|
* `options` (table)
|
|
* `callback` (function) - Optional function to call when the screen is preloaded.
|
|
|
|
The options table can contain the following fields:
|
|
|
|
* `keep_loaded` (boolean) - If the `keep_loaded` flag is set Monarch will keep the screen preloaded even after a `hide()` or `back()` navigation event that normally would unload the screen.
|
|
|
|
|
|
## monarch.is_preloading(screen_id)
|
|
Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to check
|
|
|
|
**RETURN**
|
|
* `preloading` (boolean) - True if the screen is preloading.
|
|
|
|
|
|
## monarch.when_preloaded(screen_id, callback)
|
|
Invoke a callback when a screen has been preloaded.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to check
|
|
* `callback` (function) - Function to call when the screen has been preloaded.
|
|
|
|
|
|
## monarch.unload(screen_id, [callback])
|
|
Unload a preloaded Monarch screen. A preloaded screen will automatically get unloaded when hidden, but this function can be useful if a screen has been preloaded and it needs to be unloaded again without actually hiding it. This operation will be added to the queue if Monarch is busy.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to unload.
|
|
* `callback` (function) - Optional function to call when the screen is unloaded.
|
|
|
|
|
|
## monarch.top([offset])
|
|
Get the id of the screen at the top of the stack.
|
|
|
|
**PARAMETERS**
|
|
* `offset` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
|
|
|
|
**RETURN**
|
|
* `screen_id` (string|hash) - Id of the requested screen
|
|
|
|
|
|
## monarch.bottom([offset])
|
|
Get the id of the screen at the bottom of the stack.
|
|
|
|
**PARAMETERS**
|
|
* `offset` (number) - Optional offset from the bottom of the stack
|
|
|
|
**RETURN**
|
|
* `screen_id` (string|hash) - Id of the requested screen
|
|
|
|
|
|
## monarch.data(screen_id)
|
|
Get the data associated with a screen (from a call to `monarch.show()` or `monarch.back()`).
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to get data for
|
|
|
|
**RETURN**
|
|
* `data` (table) - Data associated with the screen.
|
|
|
|
|
|
## monarch.screen_exists(screen_id)
|
|
Check if a Monarch screen exists.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to get data for
|
|
|
|
**RETURN**
|
|
* `exists` (boolean) - True if the screen exists.
|
|
|
|
|
|
## monarch.is_busy()
|
|
Check if Monarch is busy showing and/or hiding a screen.
|
|
|
|
**RETURN**
|
|
* `busy` (boolean) - True if busy hiding and/or showing a screen.
|
|
|
|
|
|
## monarch.is_top(screen_id)
|
|
Check if a Monarch screen is at the top of the view stack.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to check
|
|
|
|
**RETURN**
|
|
* `exists` (boolean) - True if the screen is at the top of the stack.
|
|
|
|
|
|
## monarch.is_visible(screen_id)
|
|
Check if a Monarch screen is visible.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to check
|
|
|
|
**RETURN**
|
|
* `exists` (boolean) - True if the screen is visible.
|
|
|
|
|
|
## monarch.set_timestep_below_popup(screen_id, timestep)
|
|
Set the timestep to apply for a screen when below a popup.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to change timestep setting for
|
|
* `timestep` (number) - Timestep to apply
|
|
|
|
|
|
## monarch.add_listener([url])
|
|
Add a URL that will be notified of navigation events.
|
|
|
|
**PARAMETERS**
|
|
* `url` (url) - URL to send navigation events to. Will use current URL if omitted.
|
|
|
|
|
|
## monarch.remove_listener([url])
|
|
Remove a previously added listener.
|
|
|
|
**PARAMETERS**
|
|
* `url` (url) - URL to remove. Will use current URL if omitted.
|
|
|
|
|
|
## monarch.post(screen_id, message_id, [message])
|
|
Post a message to a visible screen. The screen must have set a message listener using `monarch.on_post()`.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen to post message to
|
|
* `message_id` (string|hash) - Id of the message to send
|
|
* `message` (table|nil) - Optional message data to send
|
|
|
|
**RETURN**
|
|
* `result` (boolean) - True if the message was sent
|
|
* `error` (string|nil) - Error message if unable to send message
|
|
|
|
|
|
## monarch.on_transition(screen_id, fn)
|
|
Set a function to be called when a screen should transition in our out. The function will receive (message_id, message, sender) with `message_id` being one of the transition constants.
|
|
IMPORTANT! You must call `monarch.on_message(message_id, message, sender)` from the same script as this function was called.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen
|
|
* `fn` (function) - The function to call when a transition should start
|
|
|
|
|
|
## monarch.on_focus_change(screen_id, fn)
|
|
Set a function to be called when a screen gains or loses focus. The function will receive (message_id, message, sender) with `message_id` being one of the focus change constants.
|
|
IMPORTANT! You must call `monarch.on_message(message_id, message, sender)` from the same script as this function was called.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen
|
|
* `fn` (function) - The function to call screen focus changes
|
|
|
|
|
|
## monarch.on_post(screen_id, fn_or_url)
|
|
Set either a function to be called when `msg.post()` is called on a specific screen or a URL where the message is sent.
|
|
|
|
IMPORTANT! If you provide a function you must also make sure to call `monarch.on_message(message_id, message, sender)` from the same script as this function was called.
|
|
|
|
**PARAMETERS**
|
|
* `screen_id` (string|hash) - Id of the screen
|
|
* `fn_or_url` (function) - The function to call or URL to send message to
|
|
|
|
|
|
## monarch.has_missing_resources(screen_id)
|
|
Check if a screen has any missing resources. If the screen is loaded by a collection proxy with Load Dynamically this will use `collectionproxy.missing_resources()`. For other cases this function will always return false.
|
|
|
|
**RETURN**
|
|
* `result` (boolean) - true if the screen has missing resources
|
|
|
|
|
|
## monarch.debug()
|
|
Enable verbose logging of the internals of Monarch.
|
|
|
|
|
|
## monarch.SCREEN_TRANSITION_IN_STARTED
|
|
Message sent to listeners added using `monarch.add_listener()` when a screen has started to transition in.
|
|
|
|
**PARAMETERS**
|
|
* `screen` (hash) - Id of the screen
|
|
* `previous_screen` (hash) - Id of the previous screen (if any)
|
|
|
|
|
|
## monarch.SCREEN_TRANSITION_IN_FINISHED
|
|
Message sent to listeners added using `monarch.add_listener()` when a screen has finished to transition in.
|
|
|
|
**PARAMETERS**
|
|
* `screen` (hash) - Id of the screen
|
|
* `previous_screen` (hash) - Id of the previous screen (if any)
|
|
|
|
|
|
## monarch.SCREEN_TRANSITION_OUT_STARTED
|
|
Message sent to listeners added using `monarch.add_listener()` when a screen has started to transition out.
|
|
|
|
**PARAMETERS**
|
|
* `screen` (hash) - Id of the screen
|
|
* `next_screen` (hash) - Id of the next screen (if any)
|
|
|
|
|
|
## monarch.SCREEN_TRANSITION_OUT_FINISHED
|
|
Message sent to listeners added using `monarch.add_listener()` when a screen has finished to transition out.
|
|
|
|
**PARAMETERS**
|
|
* `screen` (hash) - Id of the screen
|
|
* `next_screen` (hash) - Id of the next screen (if any)
|