Events Reference#

Factory Events#

Factory events can be observed in their deferred or immediate forms. The deferred events are sent at a specific point during the frame (during the main RunLoop’s post_update event). The immediate events are sent immediately when the condition occurs and may imply that it is unsafe to call into the AppWindow system as it is in the middle of an operation. The deferred events are recommended in most cases and are considered safer to use.

To use the immediate event name, append Immediate to the C++ constant or _IMMEDIATE to the Python constant.

Since all events exist in a global namespace, factory event descriptors are composed as follows:

omni.appwindow:<factory event name>[:immediate]

Where <factory event name> is the event name listed below and :immediate is optionally appended for the immediate context event.

Window Created#

Dispatched when a new window is created.

Parameters:

Window Destroyed#

Dispatched when a window is destroyed.

Warning

Accessing the underlying IAppWindow through appWindowHandle is unsafe during the deferred event as the window has already been destroyed. The window has not actually been destroyed at the time of the immediate event however.

Parameters:

Window Startup#

Dispatched when an OS window is started.

Parameters:

Window Shutdown#

Dispatched when an OS window is about to shutdown.

Warning

Accessing much of the underlying IAppWindow through appWindowHandle is unsafe during the deferred event as the window has already been shut down. The window has not actually been shut down at the time of the immediate event however.

Parameters:

Window Events#

Warning

All omni.appwindow window events are global, but generally listeners are interested in only a specific window. All omni.appwindow window events have an appWindowHandle parameter that can be used to filter events for only a specific window. The IAppWindow::getEventKey() (C++) or IAppWindow.get_event_key() (Python) functions can be used to obtain the event filter criteria that can be passed as the filter parameter to carb::eventdispatcher::IEventDispatcher::observeEvent() (C++) or carb.eventdispatcher.IEventDispatcher.observe_event() (Python) functions.

Window events can be observed in their deferred or immediate forms. The deferred events are sent at a specific point during the frame (during the main RunLoop’s post_update event). The immediate events are sent immediately when the condition occurs and may imply that it is unsafe to call into the IAppWindow as it is in the middle of an operation. The deferred events are recommended in most cases and are considered safer to use.

To use the immediate event name, append Immediate to the C++ constant or _IMMEDIATE to the Python constant.

Since all events exist in a global namespace, window event descriptors are composed as follows:

omni.appwindow:window:<event name>[:immediate]

Where <event name> is the event name listed below and :immediate is optionally appended for the immediate context event.

To receive events only about a specific window, your event observer must specify a filter as described above. Otherwise, events will be observed for all windows.

Window Move#

Dispatched when a window moves.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window. 0 for a virtual window.

  • x (int) - Horizontal coordinate component. Together with y form the x,y coordinate that the window moved to.

  • y (int) - Vertical coordinate component. Together with x form the x,y coordinate that the window moved to.

Window Resize#

Dispatched when a window resizes.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window. 0 for a virtual window.

  • width (int) - The new width of the window.

  • height (int) - The new height of the window.

Window Content Scale#

Dispatched when content scale changes for a window.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window. 0 for a virtual window.

  • scaleX (float) - The x-coordinate (horizontal) scale.

  • scaleY (float) - The y-coordinate (vertical) scale.

  • scaleMultiplier (float) - The UI scale multiplier.

  • realScaleX (float) - The x-coordinate (horizontal) DPI scale.

  • realScaleY (float) - The y-coordinate (vertical) DPI scale.

Window Drop#

Dispatched when a drag-and-drop event completes for the OS window. This event does not naturally occur for virtual windows.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window.

  • paths (array of strings) - An array of file paths that have been dropped on the window.

Window Focus#

Dispatched when focus state changes for an OS window. This event is not dispatched for virtual windows.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window.

  • isFocused (bool) - The focused state of the window. true indicates that the window is focused.

Window Minimize#

Dispatched when minimize state changes for an OS window. This event is not dispatched for virtual windows.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window.

  • isMinimized (bool) - The minimized state of the window. true indicates that the window is minimized.

Window Close#

Dispatched when an OS window is closed. This event is not dispatched for virtual windows. This event is sent after the shutdown factory event.

NOTE: This event does not have a deferred form, only immediate. However, since differentiation is not required, the -Immediate (C++) and -_IMMEDIATE constants do not exist for this event.

Parameters:

  • appWindowHandle (uintptr_t) - The omni::kit::IAppWindow pointer to the created window.

  • windowHandle (uintptr_t) - The carb::windowing::Window pointer for an OS window.

Converting Legacy Events#

Previously, most event types were sent through a separate Event Stream. While still currently supported, this is now deprecated.

Converting C++#

Old:

using namespace omni::kit;

auto defaultWindow = carb::getCachedInterface<IAppWindowFactory>()->getDefaultWindow();
carb::events::IEventStream* closeEventStream = defaultWindow->getWindowCloseEventStream();
m_subscription = carb::events::createSubscriptionToPop(
    closeEventStream,
    [this](carb::events::IEvents* event) { this->onWindowClose(event); },
    carb::events::kDefaultOrder,
    "My window close handler"
);

Note that it is now important to specify an event filter to only receive events about the window in question.

New:

using namespace omni::kit;

auto defaultWindow = carb::getCachedInterface<IAppWindowFactory>()->getDefaultWindow();
auto dispatcher = carb::getCachedInterface<carb::eventdispatcher::IEventDispatcher>();
m_subscription = dispatcher->observeEvent(
    carb::RStringKey("My window close observer name"),
    carb::eventdispatcher::kDefaultOrder,
    kGlobalEventWindowClose,
    [this](const carb::eventdispatcher::Event& event) { this->onWindowClose(event); },
    defaultWindow->getEventKey() // very important to specify this filter to limit events to defaultWindow
);

Reading arguments from the event is easier with Events 2.0 as generally Event::getValueOr<>() can be used instead of reading dictionary values.

Converting Python#

Old:

import omni.appwindow
import carb.events

window = omni.appwindow.acquire_app_window_factory_interface().get_default_app_window()
stream = window.get_window_close_event_stream()

self.subscription = stream.create_subscription_to_pop(
    on_event,
    carb.events.DEFAULT_ORDER, # optional
    "My window close subscription name"
)

New:

import omni.appwindow
import carb.eventdispatcher

window = omni.appwindow.acquire_app_window_factory_interface().get_default_app_window()
self.subscription = carb.eventdispatcher.get_eventdispatcher().observe_event(
    observer_name="My observer name",
    filter=window.get_event_key(), # very important to specify this filter to limit events to `window`
    event_name=omni.appwindow.GLOBAL_EVENT_WINDOW_CLOSE,
    order=carb.eventdispatcher.DEFAULT_ORDER, # optional
    on_event=on_event
)