Struct APP 

pub struct APP;

Start and manage an app process.

Implementations

impl APP

pub fn multi_app_enabled(&self) -> bool

If the crate was built with feature="multi_app".

If true multiple apps can run in the same process, but only one app per thread at a time.

pub fn is_started(&self) -> bool

If an app started building or is running in the current thread.

This is true as soon as APP.minimal() or APP.defaults() is called.

You can use app_local! to create static resources that live for the app lifetime, these statics can be used as soon as this is true.

pub fn is_running(&self) -> bool

If an app is running in the current thread.

Apps are running as soon as run, run_headless or run_window are called. This will remain true until run returns or the HeadlessApp is dropped.

pub fn id(&self) -> Option<AppId>

Gets the unique ID of the current app.

This ID usually does not change as most apps only run once per process, but it can change often during tests. Resources that interact with app_local! values can use this ID to ensure that they are still operating in the same app.

pub fn window_mode(&self) -> WindowMode

Returns a WindowMode value that indicates if the app is headless, headless with renderer or headed.

Note that specific windows can be in headless mode even if the app is headed.

pub fn device_events_filter(&self) -> Var<DeviceEventsFilter>

Defines what raw device events the view-process instance should monitor and notify.

Raw device events are global and can be received even when the app has no visible window.

These events are disabled by default as they can impact performance or may require special security clearance, depending on the view-process implementation and operating system.

impl APP

pub fn minimal(&self) -> AppBuilder

Starts building an application with only the minimum required config and resources.

This is the recommended builder for tests, it signal init handlers to only load required resources.

pub fn defaults(&self) -> AppBuilder

Starts building an application with all compiled config and resources.

This is the recommended builder for apps, it signals init handlers to setup all resources upfront, on run, for example, register icon sets, default settings views and more. Note that you can still define a lean app by managing the compile time feature flags, and you can also override any default resource on run.

impl APP

pub fn on_init( &self, handler: Box<dyn FnMut(&AppInitArgs) -> HandlerResult + Send>, )

Register a handler to be called when the app starts.

In single app builds (without "multi_app" feature) the handler is called only once and dropped.

In "multi_app" builds the handler can be called more than once. The handler is called in the new app context, but it lives in the app process lifetime, you can unsubscribe from the inside or just use hn_once! to drop on init.

This method must be called before any other APP method, the handler is not called for an already running app.

Async handlers are fully supported, the code before the first .await runs blocking the rest runs in the UPDATES service.

pub fn on_deinit(&self, handler: impl FnOnce(&AppDeinitArgs) + Send + 'static)

Register a handler to be called when the app exits.

The handler is called only once, it runs in the app context and is dropped, any async tasks or requests that require app updates will not work, the app will exit just after calling the handler.

This method must be called in the app context.

impl APP

pub fn exit(&self) -> ResponseVar<ExitCancelled>

Register a request for process exit with code 0 in the next update.

The EXIT_REQUESTED_EVENT will notify, and if propagation is not cancelled the app process will exit.

Returns a response variable that is updated once with the unit value ExitCancelled if the exit operation is cancelled.

See also the EXIT_CMD.

pub fn is_suspended(&self) -> Var<bool>

Gets a variable that tracks if the app is suspended by the operating system.

Suspended apps cannot create graphics contexts and are likely to be killed if the user does not return. Operations that persist data should flush on suspension.

App suspension is controlled by the view-process, the VIEW_PROCESS_SUSPENDED_EVENT notifies on suspension and the VIEW_PROCESS_INITED_EVENT notifies a “respawn” on resume.

impl APP

App time control.

The manual time methods are only recommended for headless apps. These methods apply immediately, there are not like service methods that only apply after current update.

pub fn pause_time_for_update(&self) -> Var<bool>

Gets a variable that configures if INSTANT.now is the same exact value during each update, info, layout or render pass.

Time is paused by default, setting this to false will cause INSTANT.now to read the system time for every call.

pub fn start_manual_time(&self)

Pause the INSTANT.now value, after this call it must be updated manually using advance_manual_time or set_manual_time. To resume normal time use end_manual_time.

pub fn advance_manual_time(&self, advance: Duration)

Adds the advance to the current manual time.

Note that you must ensure an update reaches the code that controls manual time, otherwise the app loop may end-up stuck on idle or awaiting a timer that never elapses.

Panics

Panics if called before start_manual_time.

pub fn set_manual_time(&self, now: DInstant)

Set the current INSTANT.now.

Panics

Panics if called before start_manual_time.

pub fn end_manual_time(&self)

Resumes normal time.