Application API

Create an application with app = CryKit::Application.new. Use its managers for native APIs, and the methods below for setup and lifecycle.

Lifecycle

Method or property	Behavior
app.run(log_level: :info)	Run startup hooks, open initial windows and start the UI loop
app.quit	Request application shutdown; window close listeners can cancel it
app.log_level	Read the selected Log::Severity
app.quit_on_last_window_closed?	Read the application's last-window lifetime policy
app.macos	Read immutable macOS activation options

Call run on the OS main thread. Application instances are single-use. Live native operations run on the UI context, such as a mounted view callback. See startup, shutdown, and logging for lifecycle details.

Native managers

Property	Methods and controls
app.windows	create, [], []?, each; window geometry, visibility, focus, events and file interaction
app.dialogs	open_file, open_files, open_directory, save_file, info, warning, error, confirm, question
app.menus	register, create, [], []?, find_by; menu items and action events
app.trays	register, create, [], []?, find_by, remove; status items and click events
app.system	os, screen_info, accent_color, open_in_file_manager, reveal_in_file_manager

Constructor options

Keyword	Default	Purpose
quit_on_last_window_closed:	true	Set false for an application that runs with zero windows
macos:	MacOSOptions.new	Set activation_policy: :regular or :accessory
worker_parallelism:	max(1, System.cpu_count - 1)	Number of worker threads
worker_capacity:	Execution::WorkerExecutor::DEFAULT_CAPACITY	Maximum outstanding jobs
executor:	Worker executor	Inject a JobExecutor
window_backend:	Native backend	Inject a window backend
dialog_backend:	Native backend	Inject a dialog backend
menu_backend:	Native backend	Inject a menu backend
tray_backend:	Native backend	Inject a tray backend
system_backend:	Native backend	Inject a system backend

An optional positional scheduler defaults to PeriodicScheduler.new. Backend and executor injection support windowless tests.

app = CryKit::Application.new(
  macos: CryKit::Application::MacOSOptions.new(activation_policy: :accessory),
  quit_on_last_window_closed: false)

See activation and windowless lifetime for Dock visibility and resident applications.

Startup hooks

Override these protected methods in an application subclass. run calls them once, in this order, before native startup.

Order	Hook	Typical setup
1	configure : Nil	Assets and application configuration
2	register_handlers : Nil	handlers.register AppHandler
3	register_menus : Nil	menus.register AppMenu
4	register_trays : Nil	trays.register TrayMenu
5	register_windows : Nil	windows.create(id: :main, path: "/")

Setup directly on app before run is also supported. See the startup hook example.

Routes and handlers

API	Behavior
app.routes.draw { ... }	Declare routes with get "/path", as: :name do ... end
app.routes[:name]	Find a named Route; raises KeyError if absent
app.routes[:name]?	Find a named Route, or return nil
app.handlers.register AppHandler, OtherHandler	Register handler classes with access to the application
app.content_url("/path")	Resolve a local path to its app://crykit URL

Routes match exact GET paths. Route exposes path : String and name : Symbol?. /assets is reserved; duplicate paths and names are rejected. See routes and handlers and shared state.

Assets and content

API	Behavior
app.assets = CryKit::Assets.directory("assets")	Declare assets relative to the declaring Crystal source file
app.asset_path("main.css")	Build the /assets/ URL for an asset
app.assets.path = directory	Select a disk asset directory before startup
app.assets.hot_reload?, app.assets.hot_reload = enabled	Read or set development asset reloading before startup
app.content	Access the application's local content dispatcher
app.views	Access the application's view registry

crykit dev serves declared assets from disk; crykit build embeds them. See assets for paths, caching and range requests.

Background work and notifications

API	Behavior
app.async { |job| ... }	Start application-owned work; returns AppJob, cancelled on shutdown
app.broadcast_to(:channel, value)	Publish a typed value; returns whether delivery was accepted
app.notifications	Access the application's event bus
app.executor	Access the application's job executor

Application jobs publish through app.broadcast_to; views declare notification handlers with subscribe_to. View-owned jobs use job.notify for UI updates. See application jobs and channels.