class Eagle::Control

Overview

The base class of every UI widget. A control has a size, reacts to the mouse and keyboard, can hold keyboard focus, and is laid out by containers.

Build UIs from widgets (Label, Button, CheckBox, Slider, ProgressBar, TextInput, ImageControl) arranged by containers (VBox, HBox, GridContainer, Panel). Put the UI on a CanvasLayer so it ignores the game camera.

hud = CanvasLayer.new
menu = Panel.new(size: v2(260, 0))
menu.anchor = Anchor::Center
menu.fit_content = true

list = VBox.new(size: v2(240, 0))
list.position = v2(10, 10)
list.fit_content = true
list.add(Label.new("Settings"),
  Slider.new(0, 100, 50).tap { |s| s.on_value_changed { |v| Audio.volume = v / 100 } },
  CheckBox.new("Fullscreen").tap { |c| c.on_toggled { |on| Window.fullscreen = on } },
  Button.new("Play") { puts "start!" })

menu.add(list)
hud.add(menu)
SceneTree.root.add(hud)

Tab and Shift+Tab move focus between focusable controls, Enter and Space activate buttons, and Escape clears focus. Style controls with a Theme.

Direct Known Subclasses

Defined in:

eagle/ui/control.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Eagle::Node2D

direction_to(other : Node2D) : Vec2 direction_to, distance_to(other : Node2D) : Float32 distance_to, down : Vec2 down, forward : Vec2 forward, global_position : Vec2 global_position, global_position=(p : Vec2) global_position=, global_rotation : Float32 global_rotation, global_scale : Vec2 global_scale, global_transform : Transform2D global_transform, look_at(target : Vec2) : Nil look_at, modulate : Color modulate, modulate=(modulate : Color) modulate=, parent_2d : Node2D | Nil parent_2d, position : Vec2 position, position=(p : Vec2) position=, right : Vec2 right, rotate(rad : Number) : Nil rotate, rotation : Float32 rotation, rotation=(rotation : Float32) rotation=, rotation_degrees : Float32 rotation_degrees, rotation_degrees=(d : Number) rotation_degrees=, scale : Vec2 scale, scale=(s : Vec2)
scale=(s : Number) scale=, to_global(local : Vec2) : Vec2 to_global, to_local(global : Vec2) : Vec2 to_local, top_level=(top_level : Bool) top_level=, top_level? : Bool top_level?, transform : Transform2D transform, transform=(t : Transform2D) transform=, translate(x : Number, y : Number) : Nil
translate(v : Vec2) : Nil translate, x : Float32 x, x=(v : Number) x=, y : Float32 y, y=(v : Number) y=

Constructor methods inherited from class Eagle::Node2D

new(name : String = "", position : Eagle::Vec2 = Vec2::ZERO, rotation : Float32 = 0_f32, scale : Eagle::Vec2 = Vec2::ONE) new

Instance methods inherited from class Eagle::Node

<<(child : Node) : self <<, [](path : String) : Node [], []?(path : String) : Node | Nil []?, add(child : Node) : Node
add(*children : Node) : Nil add, add_child(child : Node) : Node add_child, add_to_group(group : String) : self add_to_group, ancestor_of?(node : Node) : Bool ancestor_of?, can_process? : Bool can_process?, child?(name : String) : Node | Nil child?, child_added : Eagle::Emitter(Node) child_added, child_count : Int32 child_count, child_removed : Eagle::Emitter(Node) child_removed, children : Array(Eagle::Node) children, children_of(type : T.class) : Array(T) forall T children_of, clear_children : Nil clear_children, draw(g : Graphics) : Nil draw, dump(io : IO = STDOUT, indent = 0) : Nil dump, each_ancestor(& : Node -> ) : Nil each_ancestor, each_child(& : Node -> ) : Nil each_child, each_descendant(&block : Node -> ) : Nil each_descendant, emit_child_added(*args) : Nil emit_child_added, emit_child_removed(*args) : Nil emit_child_removed, emit_tree_entered(*args) : Nil emit_tree_entered, emit_tree_exited(*args) : Nil emit_tree_exited, enter_tree : Nil enter_tree, exit_tree : Nil exit_tree, find(name : String) : Node | Nil find, find_all(type : T.class) : Array(T) forall T find_all, first_child : Node | Nil first_child, free : Nil free, get_node(path : String, type : T.class) : T forall T
get_node(path : String) : Node get_node, get_node?(path : String) : Node | Nil get_node?, groups : Set(String) groups, in_group?(group : String) : Bool in_group?, in_tree? : Bool in_tree?, input(event : Event) : Nil input, name : String name, name=(name : String) name=, on_child_added(&block : Node -> Nil) : Proc(Node, Nil) on_child_added, on_child_removed(&block : Node -> Nil) : Proc(Node, Nil) on_child_removed, on_tree_entered(&block : -> Nil) : Proc(Nil) on_tree_entered, on_tree_exited(&block : -> Nil) : Proc(Nil) on_tree_exited, parent : Node | Nil parent, path : String path, physics_process(dt : Float32) : Nil physics_process, process(dt : Float32) : Nil process, process_mode : Eagle::Node::ProcessMode process_mode, process_mode=(process_mode : Eagle::Node::ProcessMode) process_mode=, queue_free : Nil queue_free, queued_free? : Bool queued_free?, ready : Nil ready, ready_called? : Bool ready_called?, remove(child : Node) : Nil remove, remove_child(child : Node) : Nil remove_child, remove_from_group(group : String) : Nil remove_from_group, remove_from_parent : Nil remove_from_parent, resized(width : Int32, height : Int32) : Nil resized, root : Node root, to_s(io : IO) : Nil to_s, tree_entered : Eagle::Emitter() tree_entered, tree_exited : Eagle::Emitter() tree_exited, visible=(visible : Bool) visible=, visible? : Bool visible?, z_index : Int32 z_index, z_index=(z_index : Int32) z_index=

Constructor methods inherited from class Eagle::Node

new(name : String = "") new

Constructor Detail

def self.new(name : String = "", position : Vec2 = Vec2::ZERO, size : Vec2 | Nil = nil) #

Creates a control.


Class Method Detail

def self.focusable_controls(root : Node = SceneTree.root) : Array(Control) #

Every visible, enabled, focusable control under root, in tree order.


def self.focused : Control | Nil #

The control with keyboard focus, or nil.


def self.handle_focus_navigation(ev : Event) : Nil #

Handles Tab, Shift+Tab and Escape. The engine calls it for key events nothing else handled.


Instance Method Detail

def anchor : Anchor #

Where the control sits in its parent when no container arranges it.


def anchor=(anchor : Anchor) #

Where the control sits in its parent when no container arranges it.


def apply_anchor : Nil #

Positions the control from its anchor and margin.


def contains_global?(p : Vec2) : Bool #

True when a screen point is over the control.


def content_min_size : Vec2 #

The smallest size the content needs. Widgets override it.


def disabled=(disabled : Bool) #

Disabled controls are drawn grayed out and ignore input.


def disabled? : Bool #

Disabled controls are drawn grayed out and ignore input.


def effective_min_size : Vec2 #

The larger of #min_size and #content_min_size.


def emit_focus_entered(*args) : Nil #

Emitted when the control gains keyboard focus.


def emit_focus_exited(*args) : Nil #

Emitted when the control loses keyboard focus.


def emit_mouse_entered(*args) : Nil #

Emitted when the mouse moves over the control. Connect with on_mouse_entered { ... }.


def emit_mouse_exited(*args) : Nil #

Emitted when the mouse leaves the control.


def emit_resized(*args) : Nil #

Emitted when the control's size changes, with the new size.


def exit_tree : Nil #

Releases focus when removed.


def focus_entered : Eagle::Emitter() #

Emitted when the control gains keyboard focus.


def focus_exited : Eagle::Emitter() #

Emitted when the control loses keyboard focus.


def focus_next : Nil #

Moves focus to the next focusable control.


def focusable=(focusable : Bool) #

Whether the control can hold keyboard focus.


def focusable? : Bool #

Whether the control can hold keyboard focus.


def focused? : Bool #

True when this control has keyboard focus.


def font : Font #

The font this control draws with.


def global_rect : Rect #

The control's area in screen space.


def grab_focus : Nil #

Takes keyboard focus, if the control is focusable.


def gui_input(event : Event) : Bool #

Handles input for this widget. Return true when the event was used. Override it in custom widgets.


def height : Float32 #

Height in points.


def height=(v : Number) #

Sets the height.


def hovered? : Bool #

True while the mouse is over the control.


def input(event : Event) : Nil #

Routes mouse and keyboard events to #gui_input, tracking hover, press and focus.


def layout : Nil #

Updates layout before drawing. Containers override it to place children.


def margin : Vec4 #

Offset from the anchor point as x and y. With Anchor::Fill, the four components are the left, top, right and bottom insets. With the default Anchor::TopLeft, position is used as is and the margin is ignored.


def margin=(margin : Vec4) #

Offset from the anchor point as x and y. With Anchor::Fill, the four components are the left, top, right and bottom insets. With the default Anchor::TopLeft, position is used as is and the margin is ignored.


def min_size : Vec2 #

Smallest size the control accepts, combined with what its content needs.


def min_size=(min_size : Vec2) #

Smallest size the control accepts, combined with what its content needs.


def mouse_enabled=(mouse_enabled : Bool) #

When false, mouse events pass through to what's behind.


def mouse_enabled? : Bool #

When false, mouse events pass through to what's behind.


def mouse_entered : Eagle::Emitter() #

Emitted when the mouse moves over the control. Connect with on_mouse_entered { ... }.


def mouse_exited : Eagle::Emitter() #

Emitted when the mouse leaves the control.


def on_focus_entered(&block : -> Nil) : Proc(Nil) #

Emitted when the control gains keyboard focus.


def on_focus_exited(&block : -> Nil) : Proc(Nil) #

Emitted when the control loses keyboard focus.


def on_mouse_entered(&block : -> Nil) : Proc(Nil) #

Emitted when the mouse moves over the control. Connect with on_mouse_entered { ... }.


def on_mouse_exited(&block : -> Nil) : Proc(Nil) #

Emitted when the mouse leaves the control.


def on_resized(&block : Vec2 -> Nil) : Proc(Vec2, Nil) #

Emitted when the control's size changes, with the new size.


def parent_bounds : Rect #

The area anchors are measured against: the parent control, or the window.


def parent_control : Control | Nil #

The nearest ancestor that is a control, if any.


def parent_rect : Rect #

The control's area in its parent's space.


def pressed? : Bool #

True while a mouse button is held down on the control.


def process(dt : Float32) : Nil #

Runs layout. Called by the engine.


def rect : Rect #

The control's area in its own space, from (0, 0).


def release_focus : Nil #

Gives up keyboard focus.


def resized : Eagle::Emitter(Vec2) #

Emitted when the control's size changes, with the new size.


def set_size(w : Number, h : Number) : self #

Sets the size and returns self, for chaining.


def size : Vec2 #

Width and height in points.


def size=(v : Vec2) #

Sets the size and emits #resized.


def size_flags : SizeFlags #

Whether the control expands to take spare space in a box container.


def size_flags=(size_flags : SizeFlags) #

Whether the control expands to take spare space in a box container.


def theme : Theme | Nil #

A theme for this control and its descendants. nil inherits from the parent.


def theme=(theme : Theme | Nil) #

A theme for this control and its descendants. nil inherits from the parent.


def theme_or_inherited : Theme #

The theme in effect: this control's, the nearest ancestor's, or Theme.default.


def to_local_point(p : Vec2) : Vec2 #

Converts a screen point to this control's space.


def tooltip : String #

Text for a tooltip. Stored for your own tooltip display.


def tooltip=(tooltip : String) #

Text for a tooltip. Stored for your own tooltip display.


def width : Float32 #

Width in points.


def width=(v : Number) #

Sets the width.