GPUI

Global

Global's are used when you need to share some state with your whole application. A common example of a global state is the application's settings. Any type that implements the Global marker trait can be stored as a global, similar to Entity they are owned by GPUI.

Marking a type as a Global

Before you can set some type as a global it must implement the Global marker trait.

use gpui::Global;

pub struct SomeState {
    some_value: bool,
}

// Global marker trait
impl Global for SomeState {}

Setting a Global

This will set the global for the given type. The type must implement Global.

use gpui::{Application, Global, UpdateGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        // OR

        SomeState::set_global(app, SomeState { some_value: true });
    });
}

Accessing a Global

This will give you a reference to the global. Accessing a global that has not been set will cause a panic.

use gpui::{Application, Global, ReadGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.global::<SomeState>();

        // OR

        let some_state = SomeState::global(app);
    });
}

Mutably Accessing a Global

This will give you a mutable reference to the global. Accessing a global that has not been set will cause a panic.

use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.global_mut::<SomeState>();
        some_state.some_value = false;
    });
}

Attempt to access a Global

This will give you a reference to the global wrapped in a Option<T>.

use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let some_state = app.try_global::<SomeState>();
    });
}

Check whether a Global has been set

This will check if the global has been set for the given type.

use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let is_set_bool = app.has_global::<SomeState>();
    });
}

Removing a Global

This will remove the global for the given type.

use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.remove_global::<SomeState>();
    });
}

Mutably Accessing a Global with Default fallback

This will give you a mutable reference to the global. If the global has not already been set it wil set it to the default given by the type's Default trait implementation.

use gpui::{Application, Global};

#[derive(Default)]
pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.default_global::<SomeState>();
    });
}

Updating a Global

This will update the global for the given type.

use gpui::{Application, BorrowAppContext, Global, UpdateGlobal};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        app.update_global::<SomeState, _>(|some_state, _app| {
            some_state.some_value = false;
        });

        // OR

        SomeState::update_global(app, |some_state, _app| {
            some_state.some_value = false;
        });
    });
}

Observing a Global

This will register a callback that will be called when the global is updated.

use gpui::{Application, Global};

pub struct SomeState {
    some_value: bool,
}

impl Global for SomeState {}

fn main() {
    Application::new().run(|app| {
        app.set_global::<SomeState>(SomeState { some_value: true });

        let subscription = app.observe_global::<SomeState>(|_app| {
            // Global update callback
        });

        // OR

        app.observe_global::<SomeState>(|_app| {
            // Global update callback
        })
        .detach();
    });
}