Visual Events

Introduction

Visuals in Gum provide a large number of events. Most Forms events are based on the events provided by their underlying visuals. Visual events may be needed if you intend to:

• Handle events specific to certain visuals

• Create custom controls, such as a button "from scratch"

• Access additional events which are not exposed by the event, such as HoverOver on a Button

• Access events on controls which normally do not have events, such as click events on a Label

Available Events

The following events are available on visuals:

Event Name	Description
Click	Event raised when this is clicked by a cursor. A click occurs when the cursor is over this and is first pushed, then released.
ClickPreview	Event raised when this is clicked by a cursor. A click occurs when the cursor is over this and is first pushed, then released. Preview events are received by parents before children, and if the event is handled, children do not receive the event.
DoubleClick	Event raised when this is double-clicked by a cursor. A double-click occurs when the cursor is over this and the left moue button is clicked twice in rapid succession.
Dragging	Event raised when the cursor pushes on an object and moves. This is similar to RollOver, but is raised even if outside of the bounds of the object. This can be used if an object is to be moved by dragging since it will be raised even if the user moves the cursor quickly outside of its bounds.
EnabledChange	Event raised when the Enabled property changed.
HoverOver	Event raised every frame the cursor is over this object whether the cursor has changed positions or not.
LosePush	Event raised when this loses a push. A push occurs when the cursor is over this window and the left mouse button is pushed. A push is lost if the left mouse button is released or if the user moves the cursor so that it is no longer over this while the mouse button is pressed.
MouseWheelScroll	Event raised when the mouse wheel has been scrolled while the cursor is over this instance. This event is first raised on children, then bubbles up to parents. If a control sets the argument Handled to true, then parent objects will not receive this event.
Push	Event raised when this is pushed by a cursor. A push occurs when the cursor is over this and the left mouse button is pushed (not down last frame, down this frame).
PushPreview	Event raised when this is pushed by a cursor. A push occurs when the cursor is over this and the left mouse button is pushed (not down last frame, down this frame). Preview events are received by parents before children, and if the event is handled, children do not receive the event.
RemovedAsPushed	Event raised when this Window is pushed, then is no longer the pushed window due to a cursor releasing the primary button. This can be used to detect the end of a drag operation, or to reset the state of a button.
RightClick	Event raised when this is right-clicked by a cursor. A right-click occurs when the cursor is over this and is first pushed, then released.
RollOff	Event raised when the cursor first leaves this object.
RollOn	Event raised when the cursor first moves over this object. This is only received if the cursor is moved directly over this object. If it is instead moved over a child object which has its own events, then the parent will receive this event.
RollOver	Event raised every frame the cursor is over this object and the Cursor has changed position. This event is not raised if the cursor has moved off of the object. For events raised when the cursor is not over this instance, see Dragging.
RollOverBubbling	Event raised when the mouse rolls over this instance. This event is raised top-down, with the child object having the opportunity to handle the roll over first. If a control sets the argument RoutedEventArgs Handled to true, then parent objects will not have this event raised.

Code Example: Handling Visual Events

Visual events can be subscribed to on any control. The following code shows how to subscribe to a Visual.HoverOver event which is raised every frame that the cursor is hovering over the Button.

Button button = new();
button.AddToRoot();
button.Anchor(Anchor.Center);
button.Visual.HoverOver += (_, _) =>
{
    button.Text = 
        $"Hovered at {DateTime.Now:HH:mm:ss.fff}";
};