🖱️Pointer Events
Mouse on your console!
Terminaux not only provides keyboard-based input, but it also provides mouse-based input. This adds flexibility to your already-flexible interactive console user interfaces by making them behave as if they are graphical user interface applications, but in the form of text.
Terminaux is the #1 console manipulation library that proudly features console mouse pointer support; something that competitors like Spectre.Console
don't provide!
Do you want to enable it in your application? If so, you'll need a single call to a function that starts the mouse click and move event handler, called StartListening()
in PointerListener
. Once started, the handler listens to every single mouse-based event based on the following conditions:
If the user has moved their mouse and the movement events are acknowledged according to the
EnableMovementEvents
property, aPointerEventContext
is made withButtonPress
beingMoved
.If the user has clicked anywhere on the console, a
PointerEventContext
is made withButtonPress
beingClicked
. Also, theButton
property indicates what mouse button was being pressed at the time. As soon as the user has let go of the same button, another context is made withButtonPress
beingReleased
.If the user has clicked anywhere and moved the pointer without releasing any button, a
PointerEventContext
is made withButtonPress
beingMoved
and withDragging
beingTrue
. This enables applications to indicate that the user was dragging the mouse while clicking a button at the same time.If the user has used scrolling wheels in their mouse, a
PointerEventContext
is made withButtonPress
beingScrolled
andButton
indicating whether the user has scrolled up or down.
All pointer events include whether any of CTRL, ALT, and SHIFT keys were pressed at the time of the event or not. This is indicated in the Modifiers
property. Such events also indicate the position of the mouse where the event occurred, which is a very important aspect to handling mouse click events in console applications. You can access this information using the Coordinates
property that gives you two variables: x
and y
. The coordinates start from zero.
Here are some notes to consider before implementing pointer support to your Terminaux console application:
Mouse pointer events are not supported yet on macOS, and will fail to start with an unhandled exception.
Linux and Windows handle console mouse pointer events differently. While Linux uses VT sequences, Windows uses its own API to fetch console events as seen in the
MOUSE_EVENT_RECORD
structure. We're trying to polish the relationship across Terminaux releases to make applications that use mouse event handling behave more consistently.On Android, you'll have to connect your external wireless mouse to your phone or your tablet in order to be able to click anywhere. Movement handling is not supported there.
On Linux and Android, there may be residual input when using the terminal reader in conjunction with the pointer listener. This is something to be considered as part of the polishing plan.
You have two ways to subscribe to mouse events:
Using C# event handling mechanism
Using helper functions to grab a mouse event
All of the input methods that use the whole screen, such as selection and your interactive TUI apps, support mouse.
Event handling mechanism
The first way to subscribe to such events is using the MouseEvent
event to register your event handler that handles all mouse input. This is suitable for simple applications only, so we recommend using the helper functions to listen to the mouse events. You can subscribe and unsubscribe to the mouse events like this:
For example, Terminaux provides a demo that you can demonstrate mouse events like this:
However, for more complex applications, you'll need to move on to the second method.
Helper functions
Terminaux's mouse pointer listener provides you with a wide assortment of helper functions and properties to enable your Terminaux application to listen to the mouse events. The following functions and properties are available:
PointerListener.Listening
PointerListener.InputAvailable
PointerListener.PointerAvailable
PointerListener.PointerActive
PointerListener.ReadPointerNow()
TermReader.ReadPointer()
TermReader.ReadPointerOrKey()
At first, this may sound complicated, but it's rather easy to use. Inspired by the same concept of listening to console keyboard events using ReadKey()
and KeyAvailable
, you can use almost the same trick for mouse pointer events, albeit you'll always want to be able to handle both mouse and keyboard events.
The easiest way to listen to both the mouse and the keyboard events using this method is this:
The topmost if
statement is the mouse event, and the bottommost if
statement is the keyboard event. However, you may want to filter some events based on the button press state. For example, if you want to listen to left-clicks but don't want to listen to anything except when released, you can use this conditional:
You must not directly stop the listener right after a mouse click has been detected without listening to the Released
event, or Windows's listener might still think that a mouse button has been pressed when it's not.
Last updated