Mouse

Mouse events are received through the trait OnMouseEvent defined as follows:

pub trait OnMouseEvent {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        EventProcessStatus::Ignored
    }
}

where MouseEvent is defined as follows:

#[derive(Copy, Clone, Debug, PartialEq)]
pub enum MouseEvent {
    Enter,
    Leave,
    Over(Point),
    Pressed(MouseEventData),
    Released(MouseEventData),
    DoubleClick(MouseEventData),
    Drag(MouseEventData),
    Wheel(MouseWheelDirection)
}

where MouseEventData is defined as follows:

#[derive(Copy, Clone, Debug, PartialEq)]
pub struct MouseEventData {
    pub x: i32,
    pub y: i32,
    pub button: MouseButton,
    pub modifier: KeyModifier
}

and MouseButton is an enum with the following values:

• Left - indicates that the left mouse button was pressed
• Right - indicates that the right mouse button was pressed
• Center - indicates that the center mouse button was pressed
• None - indicates that no button was pressed

MouseWheelDirection is an enum with the following values:

• Up - indicates that the mouse wheel was rotated up
• Down - indicates that the mouse wheel was rotated down
• Left - indicates that the mouse wheel was rotated left
• Right - indicates that the mouse wheel was rotated right
• None - indicates that the mouse wheel was not rotated

These events are reflect the following actions:

• MouseEvent::Enter - the mouse cursor entered the control
• MouseEvent::Leave - the mouse cursor left the control
• MouseEvent::Over(Point) - the mouse cursor was moved over the control and it is now at a the specified point
• MouseEvent::Pressed(MouseEventData) - a mouse button was pressed over the control
• MouseEvent::Released(MouseEventData) - a mouse button was released. If a mouse button was pressed over the control and the control can receive input, then all of the following mouse events will be send to the control (even if the mouse cursor is outside the control) until the mouse button is released.
• MouseEvent::DoubleClick(MouseEventData) - a mouse button was double clicked over the control
• MouseEvent::Drag(MouseEventData) - a mouse button was pressed over the control and the mouse cursor was moved while keeping the button pressed
• MouseEvent::Wheel(MouseWheelDirection) - the mouse wheel was rotated

Usage

The events are generated by the system and are sent to the control that has the focus. The control can choose to ignore the event or to process it. The OnMouseEvent trait is usually used when designing a Custom Control.

A typical implementation of the OnMouseEvent trait looks like this:

impl OnMouseEvent for <MyControl> {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        // check the key
        match event {
            MouseEvent::Enter => {
                // the mouse cursor entered the control
            },
            MouseEvent::Leave => {
                // the mouse cursor left the control
            },
            MouseEvent::Over(point) => {
                // the mouse cursor is over the control
            },
            MouseEvent::Pressed(data) => {
                // a mouse button was pressed over the control
            },
            MouseEvent::Released(data) => {
                // a mouse button was released over the control
            },
            MouseEvent::DoubleClick(data) => {
                // a mouse button was double clicked over the control
            },
            MouseEvent::Drag(data) => {
                // a mouse button was pressed over the control and the mouse cursor was moved while keeping the button pressed
            },
            MouseEvent::Wheel(direction) => {
                // the mouse wheel was rotated
            }
        }
    }
}

Key modifiers

The MouseEventData structure contains a modifier field that indicates the key modifiers that were pressed when the mouse event occurred. This can be used to perform different actions based on the key modifiers (e.g., pressing Ctrl while clicking the mouse button can have a different effect than just clicking the mouse button).

impl OnMouseEvent for <MyControl> {
    fn on_mouse_event(&mut self, event: &MouseEvent) -> EventProcessStatus {
        match event {
            MouseEvent::Drag(data) => {
                if data.modifier.contains(KeyModifier::Ctrl) {
                    // the mouse button was pressed while the Ctrl key was also pressed
                } else {
                    // the mouse button was pressed without the Ctrl key being pressed 
                }
            },
            _ => {
                EventProcessStatus::Ignored
            }
        }
    }
}