App¶

The main application class for Nib menu bar applications. App manages the entire lifecycle of a Nib application, including window configuration, view rendering, event handling, system integration, and communication with the Swift runtime.

Constructor¶

nib.App(title=None, icon=None, identifier=None)

Parameters¶

Properties¶

Window and Appearance¶

Menu and Fonts¶

Lifecycle Callbacks¶

Settings¶

Service Properties (read-only)¶

Methods¶

View Management¶

build(view)¶

Set the root view of the application. If the app is already running, triggers an immediate re-render.

app.build(view: View) -> None

body()¶

Override this method in a subclass to define the UI. Returns the root view. Only used in the class-based approach.

app.body() -> View

update()¶

Manually trigger a UI re-render. Use this to force an update when the automatic reactivity system might not detect a change, or to batch multiple changes into a single render pass.

app.update() -> None

Application Lifecycle¶

run()¶

Start the application. Connects to the Swift runtime, performs the initial render, and enters the main event loop. Blocks until the app quits.

app.run() -> None

quit()¶

Quit the application and clean up resources.

app.quit() -> None

Notifications¶

notify(title, body, subtitle, sound, identifier)¶

Send a macOS system notification.

app.notify(
    title: str,
    body: str | None = None,
    subtitle: str | None = None,
    sound: bool = True,
    identifier: str | None = None,
) -> None

Clipboard¶

get_clipboard(callback)¶

Read clipboard content asynchronously. The callback receives the clipboard string.

app.get_clipboard(callback: Callable[[str], None]) -> None

set_clipboard(content)¶

Set clipboard content. Equivalent to app.clipboard = content.

app.set_clipboard(content: str) -> None

Hotkeys¶

on_hotkey(shortcut, callback)¶

Register a global keyboard shortcut.

app.on_hotkey(shortcut: str, callback: Callable[[], None]) -> None

hotkey(shortcut)¶

Decorator form of on_hotkey.

@app.hotkey("cmd+shift+n")
def show_window():
    pass

System Events¶

event(name)¶

Decorator form of the on_<event> lifecycle properties, the way hotkey is for on_hotkey. Assigning the property and using the decorator do the same thing; each event holds one callback.

@app.event("wake")
def refresh():
    pass

@app.event("appearance")
def themed(dark: bool):
    pass

An unknown name raises ValueError. Callbacks run on the event thread like actions; an exception is logged and never stops the app. See the System Events guide.

Settings¶

register_settings(settings)¶

Register a Settings object for persistence. Connects the settings to UserDefaults and waits for initial values to load.

app.register_settings(settings: Settings) -> None

open_settings()¶

Open the settings window programmatically.

app.open_settings() -> None

close_settings()¶

Close the settings window programmatically.

app.close_settings() -> None

Class Methods¶

set_assets_dir(path)¶

Set the assets directory for the application. Relative paths are resolved from the main script directory.

App.set_assets_dir(path: str | Path | None) -> None

resolve_asset(relative_path)¶

Resolve a relative asset path to an absolute path. Returns the input unchanged for absolute paths and URLs. Returns an empty string if the asset is not found.

App.resolve_asset(relative_path: str) -> str

Examples¶

Function-based app (recommended)¶

import nib

def main(app: nib.App):
    app.title = "Counter"
    app.icon = nib.SFSymbol("number.circle")
    app.width = 280
    app.height = 150

    label = nib.Text("0", font=nib.Font.TITLE)

    def increment():
        label.content = str(int(label.content) + 1)

    app.build(
        nib.VStack(
            controls=[
                label,
                nib.Button("Increment", action=increment),
            ],
            spacing=12,
            padding=20,
        )
    )

nib.run(main)

Class-based app¶

import nib

class CounterApp(nib.App):
    count = nib.State(0)

    def body(self):
        return nib.VStack(
            controls=[
                nib.Text(f"Count: {self.count}", font=nib.Font.TITLE),
                nib.Button("Increment", action=self.increment),
            ],
            spacing=12,
            padding=20,
        )

    def increment(self):
        self.count += 1

CounterApp(title="Counter", icon="number.circle").run()

View as the menu bar icon¶

Any view works as the icon, and it stays reactive. Full demo: examples/features/custom_icon.py.

import random
import nib

def main(app: nib.App):
    chart = nib.Chart(
        data=[{"x": i, "y": v} for i, v in enumerate([4, 6, 12, 14, 10, 8, 11, 9])],
        marks=[nib.LineMark(x="x", y="y", foreground_style="#ffffff", line_width=1.0)],
        x_axis=nib.ChartAxis(hidden=True),
        y_axis=nib.ChartAxis(hidden=True),
        legend=nib.ChartLegend(hidden=True),
        width=30,
        height=16,
    )
    app.icon = chart

    def randomize():
        chart.data = [{"x": i, "y": random.randint(4, 16)} for i in range(8)]

    app.build(nib.Button("Randomize", action=randomize, padding=20))

nib.run(main)

Related¶

• run(): Recommended entry point for function-based apps
• SFSymbol: Menu bar icons
• MenuItem & MenuDivider: Context menu items
• Settings: Persistent settings
• SettingsPage: Preferences window
• Architecture: process model
• Reactivity: patch model
• Context Menu
• Hotkeys and Clipboard
• System Events
• Services: app.battery, app.keychain, ...