Struct fruitbasket::FruitApp

pub struct FruitApp { /* fields omitted */ }

Main interface for controlling and interacting with the AppKit app

FruitApp is an instance of an AppKit app, equivalent to (and containing) the NSApplication singleton that is responsible for the app's lifecycle and participation in the Mac app ecosystem.

You must initialize a single instance of FruitApp before using any Apple frameworks, and after creating it you must regularly pump its event loop.

You must follow all of the standard requirements for NSApplication. Most notably: FruitApp must be created on your app's main thread, and must be pumped from the same main thread. Doing otherwise angers the beast.

An application does not need to be in a Mac app bundle to run, so this can be created in any application with FruitApp::new. However, many Apple frameworks do require the application to be running from a bundle, so you may want to consider creating your FruitApp instance from the Trampoline struct's builder instead.

Methods

impl FruitApp

pub fn new() -> FruitApp

Initialize the Apple app environment

Initializes the NSApplication singleton that initializes the Mac app environment and creates a memory pool for Objective-C allocations on the main thread.

Returns

A newly allocated FruitApp for managing the app

pub fn register_callback(
    &mut self,
    key: FruitCallbackKey,
    cb: FruitObjcCallback
)

Register to receive a callback when the ObjC runtime raises one

ObjCCallbackKey is used to specify the source of the callback, which must be something registered with the ObjC runtime.

pub fn register_apple_event(&mut self, class: u32, id: u32)

Register application to receive Apple events of the given type

Register with the underlying NSAppleEventManager so this application gets events matching the given Class/ID tuple. This causes the internal ObjC delegate to receive handleEvent:withReplyEvent: messages when the specified event is sent to your application.

This registers the event to be received internally. To receive it in your code, you must use register_callback to listen for the selector by specifying key:

FruitCallbackKey::Method("handleEvent:withReplyEvent:")

pub fn set_activation_policy(&self, policy: ActivationPolicy)

Set the app "activation policy" controlling what UI it does/can present.

pub fn terminate(exit_code: i32)

Cleanly terminate the application

Terminates a running application and its event loop, and terminates the process. This function does not return, so perform any required cleanup of your Rust application before calling it.

You should call this at the end of your program instead of simply exiting from main() to ensure that OS X knows your application has quit cleanly and can immediately inform any subsystems that are monitoring it.

This can be called from any thread.

Arguments

exit_code - Application exit code. '0' is success.

pub fn stop(stopper: &FruitStopper)

Stop the running app run loop

If the run loop is running (run()), this stops it after the next event finishes processing. It does not quit or terminate anything, and the run loop can be continued later. This can be used from callbacks to interrupt a run loop running in 'Forever' mode and return control back to Rust's main thread.

This can be called from any thread.

Arguments

stopper - A thread-safe FruitStopper object returned by stopper()

pub fn run(&mut self, period: RunPeriod) -> Result<(), ()>

Runs the main application event loop

The application's event loop must be run frequently to dispatch all events generated by the Apple frameworks to their destinations and keep the UI updated. Take care to keep this running frequently, as any delays will cause the UI to hang and cause latency on other internal operations.

Arguments

period - How long to run the event loop before returning

Returns

Ok on natural end, Err if stopped by a Stopper.

pub fn stopper(&self) -> FruitStopper

Create a thread-safe object that can interrupt the run loop

Returns an object that is safe to pass across thread boundaries (i.e. it implements Send and Sync), and can be used to interrupt and stop the run loop, even when running in 'Forever' mode.

This makes it convenient to implement the common strategy of blocking the main loop forever on the Apple run loop, until some other UI or processing thread interrupts it and lets the main thread handle cleanup and graceful shutdown.

Returns

A newly allocated object that can be passed across thread boundaries and cloned infinite times..

pub fn bundled_resource_path(name: &str, extension: &str) -> Option<String>

Locate a resource in the executing Mac App bundle

Looks for a resource by name and extension in the bundled Resources directory.

Arguments

name - Name of the file to find, without the extension

extension - Extension of the file to find. Can be an empty string for files with no extension.

Returns

The full, absolute path to the resource, or None if not found.