struct Espresso::Mouse

Overview

Information about the mouse that is associated with a window. Each Window has its own mouse instance with properties specific to that window. To retrieve a mouse instance, use Window#mouse.

Included Modules

Extended Modules

Defined in:

espresso/input/mouse.cr
espresso/input/mouse/events.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.raw_motion_supported? #

Checks whether raw mouse motion is supported on the current system. This status does not change after GLFW has been initialized so you only need to check this once. If you attempt to enable raw motion on a system that does not support it, a PlatformError will be raised.

Raw mouse motion is closer to the actual motion of the mouse across a surface. It is not affected by the scaling and acceleration applied to the motion of the desktop cursor. That processing is suitable for a cursor while raw motion is better for controlling for example a 3D camera. Because of this, raw mouse motion is only provided when the cursor is disabled.


[View source]

Instance Method Detail

def button(button : MouseButton) : ButtonState #

Returns the last state reported for the specified mouse button to the window. The returned state is one of the values from ButtonState.

If the #sticky? input mode is enabled, this method returns ButtonState::Pressed the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def button?(button : MouseButton) #

Determines whether the last state reported for the specified mouse button is pressed.

If the #sticky? input mode is enabled, this method returns true the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def cursor=(cursor) #

Sets the cursor image to be used when the cursor is over the content area of the associated window. The set cursor will only be visible when the cursor #mode is CursorMode::Normal.

On some platforms, the set cursor may not be visible unless the window also has input focus.

Possible errors that could be raised are: NotInitializedError and PlatformError.


[View source]
def disable : Nil #

Hides and grabs the cursor, providing virtual and unlimited cursor movement. This is useful for implementing for example 3D camera controls.

This will hide the cursor and lock it to the window. GLFW will then take care of all the details of cursor re-centering and offset calculation and providing the application with a virtual cursor position. This virtual position is provided normally via #on_move and #position.

If you only wish the cursor to become hidden when it is over a window but still want it to behave normally, use #hide.

Possible errors that could be raised are: NotInitializedError and PlatformError.

See also: #disabled?


[View source]
def disabled? #

Checks whether the cursor is hidden and locked.

See also: #disable


[View source]
def hidden? #

Checks whether the cursor is invisible when it is over the content area of the window.

See also: #hide


[View source]
def hide : Nil #

Makes the cursor invisible when it is over the content area of the window but does not restrict the cursor from leaving.

Possible errors that could be raised are: NotInitializedError and PlatformError.

See also: #hidden?


[View source]
def left : ButtonState #

Returns the last state reported for the left (primary) mouse button to the window. The returned state is one of the values from ButtonState.

If the #sticky? input mode is enabled, this method returns ButtonState::Pressed the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def left? #

Determines whether the last state reported for the left (primary) mouse button is pressed.

If the #sticky? input mode is enabled, this method returns true the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def middle : ButtonState #

Returns the last state reported for the middle mouse button to the window. The returned state is one of the values from ButtonState.

If the #sticky? input mode is enabled, this method returns ButtonState::Pressed the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def middle? #

Determines whether the last state reported for the middle mouse button is pressed.

If the #sticky? input mode is enabled, this method returns true the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def mode : CursorMode #

Retrieves the current cursor mode for the mouse. This will be one of the values from CursorMode.

By default, the cursor mode is CursorMode::Normal, meaning the regular arrow cursor (or another cursor set with #cursor=) is used and cursor motion is not limited.


[View source]
def move(x, y) : Nil #

Sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the content area of the window. The window must have input focus. If the window does not have input focus when this method is called, it fails silently.

Do not use this method to implement things like camera controls. GLFW already provides the #disable cursor mode that hides the cursor, transparently re-centers it and provides unconstrained cursor motion.

If the cursor mode is #disabled? then the cursor position is unconstrained and limited only by the minimum and maximum values of a Float64.

Possible errors that could be raised are: NotInitializedError and PlatformError.

Wayland: This method will only work when the cursor mode is #disabled?, otherwise it will do nothing.


[View source]
def on_button(&block : Espresso::MouseButtonEvent -> ) #

Registers a listener to respond when a mouse button is pressed or released. The block of code passed to this method will be invoked when the event occurs. A MouseButtonEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_button_listener with the proc returned by this method.

When a window loses input focus, it will generate synthetic mouse button release events for all pressed mouse buttons. You can tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the Window#on_focus event has been triggered.


[View source]
def on_enter(&block : Espresso::MouseEnterEvent -> ) #

Registers a listener to respond when the mouse enters or leaves the window's content area. The block of code passed to this method will be invoked when the event occurs. A MouseEnterEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_enter_listener with the proc returned by this method.


[View source]
def on_move(&block : Espresso::MouseMoveEvent -> ) #

Registers a listener to respond when the mouse moves. The block of code passed to this method will be invoked when the event occurs. A MouseMoveEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_move_listener with the proc returned by this method.

The block is provided with the position, in screen coordinates, relative to the upper-left corner of the content area of the window.


[View source]
def on_scroll(&block : Espresso::MouseScrollEvent -> ) #

Registers a listener to respond when the mouse is scrolled. The block of code passed to this method will be invoked when the event occurs. A MouseScrollEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_scroll_listener with the proc returned by this method.

The scroll callback receives all scrolling input, like that from a mouse wheel or a touchpad scrolling area.


[View source]
def position : Coordinates #

Returns the position of the cursor, in screen coordinates, relative to the upper-left corner of the content area of the window.

If the cursor is disabled (with #disable) then the cursor position is unbounded and limited only by the minimum and maximum values of a double.

The coordinate can be converted to their integer equivalents with the floor function. Casting directly to an integer type works for positive coordinates, but fails for negative ones.

Possible errors that could be raised are: NotInitializedError and PlatformError.


[View source]
def position=(position : Tuple(Float64, Float64)) #

Sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the content area of the window. The window must have input focus. If the window does not have input focus when this method is called, it fails silently.

Do not use this method to implement things like camera controls. GLFW already provides the #disable cursor mode that hides the cursor, transparently re-centers it and provides unconstrained cursor motion.

If the cursor mode is #disabled? then the cursor position is unconstrained and limited only by the minimum and maximum values of a Float64.

Possible errors that could be raised are: NotInitializedError and PlatformError.

Wayland: This method will only work when the cursor mode is #disabled?, otherwise it will do nothing.


[View source]
def position=(position : NamedTuple(x: Float64, y: Float64)) #

Sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the content area of the window. The window must have input focus. If the window does not have input focus when this method is called, it fails silently.

Do not use this method to implement things like camera controls. GLFW already provides the #disable cursor mode that hides the cursor, transparently re-centers it and provides unconstrained cursor motion.

If the cursor mode is #disabled? then the cursor position is unconstrained and limited only by the minimum and maximum values of a Float64.

Possible errors that could be raised are: NotInitializedError and PlatformError.

Wayland: This method will only work when the cursor mode is #disabled?, otherwise it will do nothing.


[View source]
def position=(position) #

Sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the content area of the window. The window must have input focus. If the window does not have input focus when this method is called, it fails silently.

Do not use this method to implement things like camera controls. GLFW already provides the #disable cursor mode that hides the cursor, transparently re-centers it and provides unconstrained cursor motion.

If the cursor mode is #disabled? then the cursor position is unconstrained and limited only by the minimum and maximum values of a Float64.

Possible errors that could be raised are: NotInitializedError and PlatformError.

Wayland: This method will only work when the cursor mode is #disabled?, otherwise it will do nothing.


[View source]
def remove_button_listener(listener : Espresso::MouseButtonEvent -> ) : Nil #

Removes a previously registered listener added with #on_button. The proc argument should be the return value of the #on_button method.


[View source]
def remove_enter_listener(listener : Espresso::MouseEnterEvent -> ) : Nil #

Removes a previously registered listener added with #on_enter. The proc argument should be the return value of the #on_enter method.


[View source]
def remove_move_listener(listener : Espresso::MouseMoveEvent -> ) : Nil #

Removes a previously registered listener added with #on_move. The proc argument should be the return value of the #on_move method.


[View source]
def remove_scroll_listener(listener : Espresso::MouseScrollEvent -> ) : Nil #

Removes a previously registered listener added with #on_scroll. The proc argument should be the return value of the #on_scroll method.


[View source]
def reset_cursor : Nil #

Resets the cursor for the associated window back to the default arrow.

Possible errors that could be raised are: NotInitializedError and PlatformError.


[View source]
def right : ButtonState #

Returns the last state reported for the right (secondary) mouse button to the window. The returned state is one of the values from ButtonState.

If the #sticky? input mode is enabled, this method returns ButtonState::Pressed the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def right? #

Determines whether the last state reported for the right (secondary) mouse button is pressed.

If the #sticky? input mode is enabled, this method returns true the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.


[View source]
def show : Nil #

Makes the cursor visible and behave normally.

Possible errors that could be raised are: NotInitializedError and PlatformError.

See also: #visible?


[View source]
def sticky=(flag) #

Enables or disables sticky mouse buttons. If sticky mouse buttons are enabled, a mouse button press will ensure that #button (and variants) returns ButtonState::Pressed the next time it is called even if the mouse button had been released before the call. This is useful when you are only interested in whether mouse buttons have been pressed but not when or in which order.

Whenever you poll state (via #button), you risk missing the state change you are looking for. If a pressed mouse button is released again before you poll its state, you will have missed the button press. The recommended solution for this is to use #on_button, but there is also the sticky mouse buttons input mode.

Possible errors that could be raised are: NotInitializedError and PlatformError.

See also: #sticky?


[View source]
def sticky? #

Indicates whether stick mouse buttons is enabled. If sticky mouse buttons are enabled, a mouse button press will ensure that #button (and variants) returns ButtonState::Pressed the next time it is called even if the mouse button had been released before the call. This is useful when you are only interested in whether mouse buttons have been pressed but not when or in which order.

See also: #sticky=


[View source]
def to_unsafe : LibGLFW::Window #

Retrieves the underlying window pointer.


[View source]
def visible? #

Checks whether the cursor is visible and behaving normally.

See also: #show


[View source]