Struct pugl_ui::ui::UI

pub struct UI<RW: Widget + 'static> { /* fields omitted */ }

The central interface between application, widgets and the windowing system

The UI has the following responsibilities.

• retain references to the widgets

• receive events from the windowing system and pass them to the relevant widgets

• lend widgets to the application, so the application can check the state of the widgets.

• supervise widget layouting

Event propagation

The UI receives events from the windowing system. Depending on the context (mouse cursor position, kind of event, focused widget, ...) the UI passes the event to the widget that should receive the event. If that widget does not processes the event, the event can then be passed to another widget, usually the parent of the widget. This is done by the following rules.

Keyboard events

Keyboard events are first passed to the root widget, i.e. the widget that has been passed to the constructor of the UI.

If the root widget does not process the event, the event is passed to the focused widget. There are the methods focus_widget() and focus_next_widget() to set the focus to a specific widget.

Mouse events

A mouse events goes to the widget that is under the mouse pointer. Widgets are kept in a tree of WidgetNodes. If the widget under the pointer does not process the event, it is passed to its parent.

Exeption: mouse dragging

When a mouse dragging is ongoing, the widget in which the mouse dragging started, receives, mouse events and key events first, until the dragging stops.

Implementations

impl<RW: Widget + 'static> UI<RW>

pub fn new(view: PuglViewFFI, root_widget: Box<RW>) -> UI<RW>

Creates a new UI instance from a PuglViewFFI and a heap allocated root widget

The UI instance needs a PuglViewFFI instance from the pugl-sys crate as interface to the windowing system.

pub fn new_scaled(
    view: PuglViewFFI,
    root_widget: Box<RW>,
    scale_factor: f64
) -> UI<RW>

Creates a new UI which is scaled by the scale_factor

Widgets don't know about the scale factor. They can do their drawing and event processing as if the scale_factor was 1.0. The UI everything including the cairo::Context transparently.

pub fn new_widget<W: Widget>(&mut self, widget: Box<W>) -> WidgetHandle<W>

Registers a new widget in the UI.

The instance of the widget must be passed heap allocated in a Box. Returns a WidgetHandle to the widget.

pub fn new_layouter<L>(&mut self) -> LayoutWidgetHandle<L, LayoutWidget> where
    L: Layouter, 

Creates a new LayoutingWidget for a Layouter of type L and registers it to the UI/

Returns a LayoutWidgetHandle to the Layouter` object.

pub fn add_spacer<L>(
    &mut self,
    parent: LayoutWidgetHandle<L, LayoutWidget>,
    target: L::Target
) where
    L: Layouter, 

Adds a spacing widget to a layouter.

This is a convenience function

pub fn pack_to_layout<L, W, PW>(
    &mut self,
    widget: WidgetHandle<W>,
    parent: LayoutWidgetHandle<L, PW>,
    target: L::Target
) where
    L: Layouter,
    W: Widget,
    PW: Widget, 

Adds the widget to a layout according to the layout target. The target is specific to the actual Layouter type L

pub fn do_layout(&mut self)

Performs the layouting of the widgets.

This must be done before the view is realized (or window is shown). All registered widgets should have been packed to a layout before.

pub fn fit_window_size(&self)

Sets the default window size, so that the widget layout fits into it.

pub fn fit_window_min_size(&self)

Sets the minimal window size, so that the widget layout fits into it.

pub fn close_request_issued(&self) -> bool

Returns true iff a the window has been requested to close by the windowing system

The application should check for this at every cycle of the event loop and terminate the event loop if true is returned.

pub fn layouter<L, W>(
    &mut self,
    layouter: LayoutWidgetHandle<L, W>
) -> &mut L::Implementor where
    L: Layouter,
    W: Widget, 

Returns a mutable reference to the Layouter of the passed LayoutWidgetHandle.

This can be used to borrow a handle to the layouter in order to change layouting parameters.

pub fn root_layout(&self) -> LayoutWidgetHandle<VerticalLayouter, RW>

Returns a mutable reference to the Layouter of root Layouter.

This can be used to borrow a handle to the layouter in order to change layouting parameters.

pub fn root_widget(&mut self) -> &mut RW

Returns a mutable reference to the root widget.

pub fn widget<W: Widget>(&mut self, widget: WidgetHandle<W>) -> &mut W

Returns a mutable reference to the specified by widget.

It returns a reference to the actual widget instance, so type specific methods of the widget can be used.

pub fn focus_next_widget(&mut self)

Performs a step in the cycle of the widget focus.

Can be called when the root widget received a TAB key press event.

pub fn focus_widget<W: Widget>(&mut self, widget: WidgetHandle<W>)

Focuses the widget specified by widget

pub fn has_focus(&self) -> bool

Returns true iff the window has the focus.

pub fn next_event(&mut self, timeout: f64)

Initiates the next cycle of the event loop

The application should call it at the beginning of the event loop.

From pugl documentation: If timeout is zero, then this function will not block. Plugins should always use a timeout of zero to avoid blocking the host.

If a positive timeout is given, then events will be processed for that amount of time, starting from when this function was called.

If a negative timeout is given, this function will block indefinitely until an event occurs.

For continuously animating programs, a timeout that is a reasonable fraction of the ideal frame period should be used, to minimize input latency by ensuring that as many input events are consumed as possible before drawing.

Trait Implementations

impl<RW: Widget> PuglViewTrait for UI<RW>

fn exposed(&mut self, expose: &ExposeArea, cr: &Context)

Called when a part of the view needs to be redrawn due to an exposure.

fn event(&mut self, ev: Event) -> Status

Called if an event happened that is to be processed.

fn focus_in(&mut self) -> Status

Called when the view recieves the focus

fn focus_out(&mut self) -> Status

Called when the view gives the focus away

fn resize(&mut self, size: Size)

Called when the view has been resized

fn close_request(&mut self)

Called when the view is requested to close by the window system

fn timer_event(&mut self, id: usize) -> Status

Called when a timer launched by start_timer() finished.

fn view(&self) -> PuglViewFFI

Returns a handle to the window system's view

fn world(&self) -> *mut PuglWorldImpl

Returns a pointer to the PugleWorld

fn post_redisplay(&self) -> Status

Request a redisplay for the entire view.

fn post_redisplay_rect(&self, pos: Coord, size: Size) -> Status

Request a redisplay of the given rectangle within the view.

fn get_frame(&self) -> Rect

Get the current position and size of the view.

fn set_frame(&self, frame: Rect) -> Status

Set the current position and size of the view.

fn set_default_size(&self, width: i32, height: i32) -> Status

Set the default size of the view.

fn set_min_size(&self, width: i32, height: i32) -> Status

Set the minimum size of the view.

fn set_max_size(&self, width: i32, height: i32) -> Status

Set the maximum size of the view.

fn set_aspect_ratio(
    &self,
    min_x: i32,
    min_y: i32,
    max_x: i32,
    max_y: i32
) -> Status

Set the view aspect ratio range.

fn is_resizable(&self) -> bool

Returns true iff the window is resizable

fn make_resizable(&self) -> Status

Make the view resizable.

fn is_ignoring_key_repeats(&self) -> ViewHintBool

Returns a ViewHintBool whether the view is ignoring key repeats.

fn set_ignore_key_repeats(&self, value: ViewHintBool) -> Status

Gives the view the hint whether it should ignore key repeats.

fn red_bits(&self) -> u32

Returns the number of bits for the red channel of the view

fn green_bits(&self) -> u32

Returns the number of bits for the green channel of the view

fn blue_bits(&self) -> u32

Returns the number of bits for the blue channel of the view

fn alpha_bits(&self) -> u32

Returns the number of bits for the alpha channel of the view

fn depth_bits(&self) -> u32

Returns the number of bits for the depth buffer of the view

fn stencil_bits(&self) -> u32

Returns the number of bits for the stencil buffer of the view

fn samples(&self) -> u32

Returns the number of samples per pixel

fn double_buffer(&self) -> bool

Returns true iff double buffering should be used

fn set_double_buffer(&self, yn: bool) -> Status

Sets whether double buffering should be used

fn swap_interval(&self) -> ViewHintInt

Returns number of frames between buffer swaps

fn refresh_rate(&self) -> ViewHintInt

Returns the refresh rate in Hz

fn set_window_title(&self, title: &str) -> Status

Sets the window title

fn realize(&self) -> Status

Realize a view by creating a corresponding system view or window.

fn show_window(&self) -> Status

Show the view.

fn hide_window(&self) -> Status

Hide the current window

fn is_visible(&self) -> bool

Return true iff the view is currently visible.

fn set_cursor(&self, c: Cursor) -> Status

Set the mouse cursor.

fn update(&self, timeout: f64) -> Status

Update by processing events from the window system.

fn start_timer(&self, id: usize, timeout: f64) -> Status

Activate a repeating timer event.

fn stop_timer(&self, id: usize) -> Status

Stop an active timer