Struct druid_shell::WindowHandle

pub struct WindowHandle(_);

A handle to a platform window object.

Implementations

impl WindowHandle

pub fn show(&self)

Make this window visible.

This is part of the initialization process; it should only be called once, when a window is first created.

pub fn close(&self)

Close the window.

pub fn resizable(&self, resizable: bool)

Set whether the window should be resizable

pub fn set_window_state(&mut self, state: WindowState)

Sets the state of the window.

pub fn get_window_state(&self) -> WindowState

Gets the state of the window.

pub fn handle_titlebar(&self, val: bool)

Informs the system that the current location of the mouse should be treated as part of the window’s titlebar. This can be used to implement a custom titlebar widget. Note that because this refers to the current location of the mouse, you should probably call this function in response to every relevant WinHandler::mouse_move.

This is currently only implemented on Windows.

pub fn show_titlebar(&self, show_titlebar: bool)

Set whether the window should show titlebar.

pub fn set_position(&self, position: impl Into<Point>)

Sets the position of the window in display points, relative to the origin of the virtual screen.

pub fn get_position(&self) -> Point

Returns the position of the top left corner of the window in display points, relative to the origin of the virtual screen.

pub fn content_insets(&self) -> Insets

Returns the insets of the window content from its position and size in display points.

This is to account for any window system provided chrome, e.g. title bars. For example, if you want your window to have room for contents of size contents, then you should call WindowHandle::get_size with an argument of (contents.to_rect() + insets).size(), where insets is the return value of this function.

The details of this function are somewhat platform-dependent. For example, on Windows both the insets and the window size include the space taken up by the title bar and window decorations; on GTK neither the insets nor the window size include the title bar or window decorations.

pub fn set_size(&self, size: impl Into<Size>)

Set the window’s size in display points.

The actual window size in pixels will depend on the platform DPI settings.

This should be considered a request to the platform to set the size of the window. The platform might choose a different size depending on its DPI or other platform-dependent configuration. To know the actual size of the window you should handle the WinHandler::size method.

pub fn get_size(&self) -> Size

Gets the window size, in display points.

pub fn set_level(&self, level: WindowLevel)

Sets the WindowLevel, the z-order in the Window system / compositor

We do not currently have a getter method, mostly because the system’s levels aren’t a perfect one-to-one map to druid_shell’s levels. A getter method may be added in the future.

pub fn bring_to_front_and_focus(&self)

Bring this window to the front of the window stack and give it focus.

pub fn request_anim_frame(&self)

Request that prepare_paint and paint be called next time there’s the opportunity to render another frame. This differs from invalidate and invalidate_rect in that it doesn’t invalidate any part of the window.

pub fn invalidate(&self)

Request invalidation of the entire window contents.

pub fn invalidate_rect(&self, rect: Rect)

Request invalidation of a region of the window.

pub fn set_title(&self, title: &str)

Set the title for this menu.

pub fn set_menu(&self, menu: Menu)

Set the top-level menu for this window.

pub fn text(&self) -> PietText

Get access to a type that can perform text layout.

pub fn add_text_field(&self) -> TextFieldToken

Register a new text input receiver for this window.

This method should be called any time a new editable text field is created inside a window. Any text field with a TextFieldToken that has not yet been destroyed with remove_text_field must be ready to accept input from the platform via WinHandler::text_input at any time, even if it is not currently focused.

Returns the TextFieldToken associated with this new text input.

pub fn remove_text_field(&self, token: TextFieldToken)

Unregister a previously registered text input receiver.

If token is the text field currently focused, the platform automatically sets the focused field to None.

pub fn set_focused_text_field(&self, active_field: Option<TextFieldToken>)

Notify the platform that the focused text input receiver has changed.

This must be called any time focus changes to a different text input, or when focus switches away from a text input.

pub fn update_text_field(&self, token: TextFieldToken, update: Event)

Notify the platform that some text input state has changed, such as the selection, contents, etc.

This method should never be called in response to edits from a InputHandler; only in response to changes from the application: scrolling, remote edits, etc.

pub fn request_timer(&self, deadline: Duration) -> TimerToken

Schedule a timer.

This causes a WinHandler::timer call at the deadline. The return value is a token that can be used to associate the request with the handler call.

Note that this is not a precise timer. On Windows, the typical resolution is around 10ms. Therefore, it’s best used for things like blinking a cursor or triggering tooltips, not for anything requiring precision.

pub fn set_cursor(&mut self, cursor: &Cursor)

Set the cursor icon.

pub fn make_cursor(&self, desc: &CursorDesc) -> Option<Cursor>

pub fn open_file(
    &mut self,
    options: FileDialogOptions
) -> Option<FileDialogToken>

Prompt the user to choose a file to open.

This won’t block immediately; the file dialog will be shown whenever control returns to druid-shell, and the WinHandler::open_file method will be called when the dialog is closed.

pub fn save_as(&mut self, options: FileDialogOptions) -> Option<FileDialogToken>

Prompt the user to choose a path for saving.

This won’t block immediately; the file dialog will be shown whenever control returns to druid-shell, and the WinHandler::save_as method will be called when the dialog is closed.

pub fn show_context_menu(&self, menu: Menu, pos: Point)

Display a pop-up menu at the given position.

pos is in the coordinate space of the window.

pub fn get_idle_handle(&self) -> Option<IdleHandle>

Get a handle that can be used to schedule an idle task.

pub fn get_scale(&self) -> Result<Scale, Error>

Get the DPI scale of the window.

The returned Scale is a copy and thus its information will be stale after the platform DPI changes. This means you should not stash it and rely on it later; it is only guaranteed to be valid for the current pass of the runloop.

Trait Implementations

impl Clone for WindowHandle

fn clone(&self) -> WindowHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for WindowHandle

fn default() -> WindowHandle

Returns the “default value” for a type.