Struct nannou::window::Window

pub struct Window { /* fields omitted */ }

A nannou window.

The Window acts as a wrapper around the winit::window::Window and the wgpu::Surface types. It also manages the associated swap chain, providing a more nannou-friendly API.

Implementations

impl Window

pub fn id(&self) -> Id

A unique identifier associated with this window.

pub fn scale_factor(&self) -> Default

Returns the scale factor that can be used to map logical pixels to physical pixels and vice versa.

Throughout nannou, you will see “logical pixels” referred to as “points”, and “physical pixels” referred to as “pixels”.

This is typically 1.0 for a normal display, 2.0 for a retina display and higher on more modern displays.

You can read more about what this scale factor means within winit’s dpi module documentation.

Platform-specific

• X11: This respects Xft.dpi, and can be overridden using the WINIT_X11_SCALE_FACTOR environment variable.
• Android: Always returns 1.0.
• iOS: Can only be called on the main thread. Returns the underlying UiView’s contentScaleFactor.

pub fn outer_position_pixels(&self) -> Result<(i32, i32), NotSupportedError>

The position of the top-left hand corner of the window relative to the top-left hand corner of the desktop.

Note that the top-left hand corner of the desktop is not necessarily the same as the screen. If the user uses a desktop with multiple monitors, the top-left hand corner of the desktop is the top-left hand corner of the monitor at the top-left of the desktop.

The coordinates can be negative if the top-left hand corner of the window is outside of the visible screen region.

Platform-specific

• iOS: Can only be called on the main thread. Returns the top left coordinates of the window in the screen space coordinate system.
• Web: Returns the top-left coordinates relative to the viewport.

pub fn set_outer_position_pixels(&self, x: i32, y: i32)

Modifies the position of the window.

See outer_position_pixels for more information about the returned coordinates. This automatically un-maximizes the window if it is maximized.

Platform-specific

• iOS: Can only be called on the main thread. Sets the top left coordinates of the window in the screen space coordinate system.
• Web: Sets the top-left coordinates relative to the viewport.

pub fn inner_size_pixels(&self) -> (u32, u32)

The width and height in pixels of the client area of the window.

The client area is the content of the window, excluding the title bar and borders.

pub fn inner_size_points(&self) -> (Default, Default)

The width and height in points of the client area of the window.

The client area is the content of the window, excluding the title bar and borders.

This is the same as dividing the result of inner_size_pixels() by scale_factor().

pub fn set_inner_size_pixels(&self, width: u32, height: u32)

Modifies the inner size of the window.

See the inner_size methods for more informations about the values.

pub fn set_inner_size_points(&self, width: f32, height: f32)

Modifies the inner size of the window using point values.

See the inner_size methods for more informations about the values.

pub fn outer_size_pixels(&self) -> (u32, u32)

The width and height of the window in pixels.

These dimensions include title bar and borders. If you don’t want these, you should use inner_size_pixels instead.

pub fn outer_size_points(&self) -> (f32, f32)

The width and height of the window in points.

These dimensions include title bar and borders. If you don’t want these, you should use inner_size_points instead.

This is the same as dividing the result of outer_size_pixels() by scale_factor().

pub fn set_min_inner_size_points(&self, size: Option<(f32, f32)>)

Sets a minimum size for the window.

pub fn set_max_inner_size_points(&self, size: Option<(f32, f32)>)

Sets a maximum size for the window.

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

Modifies the title of the window.

This is a no-op if the window has already been closed.

pub fn set_visible(&self, visible: bool)

Set the visibility of the window.

Platform-specific

• Android: Has no effect.
• iOS: Can only be called on the main thread.
• Web: Has no effect.

pub fn set_resizable(&self, resizable: bool)

Sets whether the window is resizable or not.

Note that making the window unresizable doesn’t exempt you from handling Resized, as that event can still be triggered by DPI scaling, entering fullscreen mode, etc.

pub fn set_minimized(&self, minimized: bool)

Sets the window to minimized or back.

pub fn set_maximized(&self, maximized: bool)

Sets the window to maximized or back.

pub fn set_fullscreen(&self, fullscreen: bool)

Set the window to fullscreen on the primary monitor.

true enables fullscreen, false disables fullscreen.

See the set_fullscreen_with method for more options and details about behaviour related to fullscreen.

pub fn set_fullscreen_with(&self, fullscreen: Option<Fullscreen>)

Set the window to fullscreen.

Call this method again with None to revert back from fullscreen.

Platform-specific

• macOS: Fullscreen::Exclusive provides true exclusive mode with a video mode change. Caveat! macOS doesn’t provide task switching (or spaces!) while in exclusive fullscreen mode. This mode should be used when a video mode change is desired, but for a better user experience, borderless fullscreen might be preferred.

  Fullscreen::Borderless provides a borderless fullscreen window on a separate space. This is the idiomatic way for fullscreen games to work on macOS. See WindowExtMacOs::set_simple_fullscreen if separate spaces are not preferred.

  The dock and the menu bar are always disabled in fullscreen mode.

• iOS: Can only be called on the main thread.

• Wayland: Does not support exclusive fullscreen mode.

• Windows: Screen saver is disabled in fullscreen mode.

pub fn fullscreen(&self) -> Option<Fullscreen>

Gets the window’s current fullscreen state.

Platform-specific

• iOS: Can only be called on the main thread.

pub fn set_decorations(&self, decorations: bool)

Turn window decorations on or off.

Platform-specific

• iOS: Can only be called on the main thread. Controls whether the status bar is hidden via setPrefersStatusBarHidden.
• Web: Has no effect.

pub fn set_always_on_top(&self, always_on_top: bool)

Change whether or not the window will always be on top of other windows.

pub fn set_window_icon(&self, window_icon: Option<Icon>)

Sets the window icon. On Windows and X11, this is typically the small icon in the top-left corner of the titlebar.

Platform-specific

This only has effect on Windows and X11.

On Windows, this sets ICON_SMALL. The base size for a window icon is 16x16, but it’s recommended to account for screen scaling and pick a multiple of that, i.e. 32x32.

X11 has no universal guidelines for icon sizes, so you’re at the whims of the WM. That said, it’s usually in the same ballpark as on Windows.

pub fn set_ime_position_points(&self, x: f32, y: f32)

Sets the location of IME candidate box in client area coordinates relative to the top left.

Platform-specific

• iOS: Has no effect.
• Web: Has no effect.

pub fn set_cursor_icon(&self, state: CursorIcon)

Modifies the mouse cursor of the window.

Platform-specific

• iOS: Has no effect.
• Android: Has no effect.

pub fn set_cursor_position_points(
    &self,
    x: f32,
    y: f32
) -> Result<(), ExternalError>

Changes the position of the cursor in logical window coordinates.

Platform-specific

• iOS: Always returns an Err.
• Web: Has no effect.

pub fn set_cursor_grab(&self, grab: bool) -> Result<(), ExternalError>

Grabs the cursor, preventing it from leaving the window.

Platform-specific

• macOS: Locks the cursor in a fixed location.
• Wayland: Locks the cursor in a fixed location.
• Android: Has no effect.
• iOS: Always returns an Err.
• Web: Has no effect.

pub fn set_cursor_visible(&self, visible: bool)

Set the cursor’s visibility.

If false, hides the cursor. If true, shows the cursor.

Platform-specific

On Windows, X11 and Wayland, the cursor is only hidden within the confines of the window.

On macOS, the cursor is hidden as long as the window has input focus, even if the cursor is outside of the window.

This has no effect on Android or iOS.

pub fn current_monitor(&self) -> Option<MonitorHandle>

The current monitor that the window is, on or the primary monitor if nothing matches. If there’s neither a current nor a primary monitor, returns none.

pub fn surface(&self) -> &Surface

Returns a reference to the window’s wgpu swap chain surface.

pub fn swap_chain_descriptor(&self) -> &SwapChainDescriptor

The descriptor for the swap chain associated with this window’s wgpu surface.

pub fn swap_chain_device(&self) -> &Device

The wgpu logical device on which the window’s swap chain is running.

This is shorthand for DeviceOwned::device(window.swap_chain()).

pub fn swap_chain_queue(&self) -> &Queue

The wgpu graphics queue on which the window swap chain work is run.

The queue is guarded by a Mutex in order to synchronise submissions of command buffers in cases that the queue is shared between more than one window.

pub fn swap_chain_device_queue_pair(&self) -> &Arc<DeviceQueuePair>

Provides access to the device queue pair and the Arc behind which it is stored. This can be useful in cases where using references provided by the swap_chain_device or swap_chain_queue methods cause awkward ownership problems.

pub fn msaa_samples(&self) -> u32

The number of samples used in the MSAA for the image associated with the view function’s Frame type.

Note: If the user specified a raw_view function rather than a view function, this value will always return 1.

pub fn is_fullscreen(&self) -> bool

Attempts to determine whether or not the window is currently fullscreen.

pub fn elapsed_frames(&self) -> u64

The number of times view has been called with a Frame for this window.

pub fn rect(&self) -> Rect

The rectangle representing the position and dimensions of the window.

The window’s position will always be [0.0, 0.0], as positions are generally described relative to the centre of the window itself.

The dimensions will be equal to the result of inner_size_points. This represents the area of the that we can draw to in a DPI-agnostic manner, typically useful for drawing and UI positioning.

pub fn capture_frame<P>(&self, path: P) where
    P: AsRef<Path>, 

Capture the next frame right before it is drawn to this window and write it to an image file at the given path. If a frame already exists, it will be captured before its submit method is called or before it is dropped.

The destination image file type will be inferred from the extension given in the path.

pub fn await_capture_frame_jobs(
    &self
) -> Result<(), TextureCapturerAwaitWorkerTimeout<()>>

Block and wait for all active capture frame jobs to complete.

This is called implicitly when the window is dropped to ensure any pending captures complete.

Trait Implementations

impl Debug for Window

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Window

fn drop(&mut self)

Executes the destructor for this type.