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

Visual Types with Events

Not all Visual Types support events. To support events, the visual type must inherit from InteractiveGue. Furthermore, HasEvents must be set to true. The following shows which types have support for events:

Type	Supports Events	Default HasEvents
CircleRuntime	❌ Not Supported	-
ColoredRectangleRuntime	❌ Not Supported	-
ContainerRuntime	✅Supported	true
NineSliceRuntime	✅Supported	false
PolygonRuntime	✅Supported	false
RectangleRuntime	❌ Not Supported	-
SpriteRuntime	❌ Not Supported	-
TextRuntime	✅Supported	false

Note that future versions of Gum may add support for events on runtimes so the table above may change, however, if this happens the HasEvents property will still default to false as to not break existing behavior. If your project needs events on any types which are not supported, please file an issue on GitHub or let us know on Discord.

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.
ClickBubbling	Event raised when this is clicked by a cursor. Unlike Click, which is only raised on the clicked element, this event is raised first on the clicked element, then bubbles up to its parents in sequence. If a control sets the argument RoutedEventArgs Handled to true, then parent objects will not have this event raised. This is useful for responding to a click anywhere on an element's surface, even when the click lands on a child.
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 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 is pushed, then is no longer the pushed visual 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.

Event Examples

The following table provides examples on which events are raised when the user performs various actions. This can help provide context for how visual events are raised.

User Action	Events
User moves cursor over a Button, pushes, then releases the left mouse button.	RollOn is raised when the cursor moves over the button RollOver and RollOverBubbling are raised as the cursor moves over the button every frame, but are not raised if the cursor is stationary HoverOver is raised every frame the cursor is over the button, even if it is not moving PushPreview and Push are raised when the user first presses the left mouse button ClickPreview, Click, and ClickBubbling are raised when the user releases the button LosePush and RemoveAsPushed are raised when the user releases the left mouse button
User moves the cursor over a Button, pushes the left mouse button, moves the cursor off of the button while still holding the left mouse button, then releases the left mouse button.	RollOn is raised when the cursor moves over the button RollOver and RollOverBubbling are raised as the cursor moves over the button every frame, but are not raised if the cursor is stationary HoverOver is raised every frame the cursor is over the button, even if it is not moving PushPreview and Push are raised when the user first presses the left mouse button RollOver and Dragging are raised every frame as the cursor moves over the button while the button is held LosePush is raised when the cursor moves outside of the Button's bounds Dragging is still raised ever frame as the user holds the left mouse button while moving outside of the Button's bounds RemoveAsPushed is raised when the user releases the left mouse button

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.

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

Code Example: Bubbling Click Events

The Click event is only raised on the element that was clicked. If you want to respond to a click anywhere on a container's surface — even when the click lands on a child — subscribe to ClickBubbling instead. It is raised first on the clicked element, then bubbles up to each parent in sequence.

The following code subscribes to ClickBubbling on a StackPanel. The handler runs whenever either child Button is clicked, because the event bubbles from the clicked button up to the panel.

// Initialize
StackPanel panel = new();
panel.AddToRoot();
panel.Anchor(Anchor.Center);

Button first = new();
first.Text = "First";
panel.AddChild(first);

Button second = new();
second.Text = "Second";
panel.AddChild(second);

Label status = new();
status.AddToRoot();
status.Anchor(Anchor.Bottom);

// ClickBubbling is raised on the panel even though the click lands on a child Button.
panel.Visual.ClickBubbling += (sender, args) =>
{
    status.Text = "A button in the panel was clicked";
};

A handler can set args.Handled to true to stop the event from bubbling to further parents. For example, a child can mark the event handled so its parent's ClickBubbling handler does not run.