Castle Game Engine features a number of user interface (2D) controls. You can build a complete user interface in the CGE editor, you can also build and modify the whole UI using our Pascal API. Our UI controls have parents, anchoring, UI scaling. If you set the anchors right, our UI will "just work" at various screen resolutions, aspect ratios and platforms, and can seamlessly adjust to any desktop or mobile screen.
As an example, take a look at this design that is used for our inspector (see the Inspector invoked by F8 movie). Coupled with the right code, this design implements a non-trivial UI with toggable panels, scrollable list box, minimal scrollable object inspector, custom-drawn profiler and more.
cgeimg::block[inspector_design.png|Inspector UI,inspector_running.png|Inspector visible at runtime]
The basic usage of UI controls inside the CGE editor is explained in the chapter Designing user interface and handling events (press, update) within the view. It shows how to use cgeref:TCastleImageControl[] — but the workflow shown there applies to all other UI controls too. It comes down to:
-
Using "Add User Interface" menu item in the CGE editor to choose a component. It will be added to the view. It’s usually most comfortable to use "Add User Interface" by right-clicking on the parent component in the editor hierarchy.
-
After adding, you want to adjust basic component properties, like
Name
, position and size. -
To access the component from code, you need to declare it in the
published
section of your view, likeMyLabel: TCastleLabel
. The fieldMyLabel
will then be automatically initialized when view starts. You can modify this component from code however you want, e.g. doMyLabel.Caption := 'something'
.
In general, all the descendants of cgeref:TCastleUserInterface[] defined in the engine are UI controls. This page lists the most important ones.
See the component_gallery demo for a showcase of our most important components. You can run that example and explore its UI designs in CGE editor.
cgeref:TCastleUserInterface[] is a base UI class. It is an ancestor of all other UI classes, and as such implements common features like anchors and borders. It can be used directly too — will serve as a good parent, to organize a number of children controls or surround them with a visual frame.
cgeimg::block[ui_empty_rectangle.png|Empty rectangles]
cgeref:TCastleRectangleControl[] is a rectangle filled with simple RGBA color. Its most important property is cgeref:TCastleRectangleControl.Color[].
cgeimg::block[ui_color_rectangle.png|Color rectangles]
cgeref:TCastleLabel[] is the simplest way to display text in our engine. Its most important property is cgeref:TCastleLabel.Caption[] (or, if you want access the multi-line string list, cgeref:TCastleLabel.Text[]).
cgeimg::block[ui_label.png|Labels]
cgeref:TCastleImageControl[] displays an image. It can be scaled, preserving the aspect ratio or ignoring the aspect ratio, if needed. Its most important property is cgeref:TCastleImageControl.Url[].
cgeimg::block[ui_image.png|Images]
Note
|
Drag-and-drop image from the "Files" panel (at the bottom) over a UI design to create a cgeref:TCastleImageControl[] component easily. |
cgeref:TCastleButton[] is a clickable UI element. The look can be incredibly customized to match the style of your game. Its most important properties are cgeref:TCastleButton.Caption[] and (assign here your event, in code) cgeref:TCastleButton.OnClick[].
cgeimg::block[ui_button_1.png|Buttons,ui_button_2.png|Buttons]
cgeref:TCastleCheckbox[] allows user to check/uncheck a checkbox, to make a Boolean choice. Its most important properties are cgeref:TCastleCheckbox.Caption[] and (assign here your event, in code) cgeref:TCastleCheckbox.Checked[].
cgeimg::block[ui_checkbox.png|Checkboxes]
cgeref:TCastleEdit[] allows to edit a single-line text. Its most important property is cgeref:TCastleEdit.Text[].
It has simple descendants cgeref:TCastleIntegerEdit[] and cgeref:TCastleFloatEdit[] to edit numbers. Their most important properties are, respectively, cgeref:TCastleIntegerEdit.Value[] and cgeref:TCastleFloatEdit.Value[].
cgeimg::block[ui_edit.png|Edit fields]
cgeref:TCastleHorizontalGroup[] and cgeref:TCastleVerticalGroup[] automatically layout their controls in a horizontal and vertical fashion.
cgeimg::block[ui_group.png|Groups]
cgeref:TCastleScrollView[] allows to scroll a large (tall) area with a vertical scrollbar. Its most important property is cgeref:TCastleScrollView.ScrollArea[], this is where you should add children that should scroll.
cgeimg::block[ui_scroll_view.png|Scroll View]
cgeref:TCastleShape[] displays since shapes, like circles and triangles.
cgeimg::block[ui_shape.png|Shape]
cgeref:TCastleDesign[] inserts a UI design from another xxx.castle-user-interface
file. This allows to reuse the same UI design multiple times. Editing the original xxx.castle-user-interface
will update all instances where this design is used.
cgeimg::block[ui_design.png|Design (refer to another UI design)]
Note
|
Drag-and-drop xxx.castle-user-interface from the "Files" panel (at the bottom) over a UI design to create a cgeref:TCastleDesign[] component easily.
|
cgeref:TCastleMask[] allows to define a mask (using an arbitrary UI control) and use this mask to limit rendering the children.
The mask may be any UI control (or a composition of it). The colors do not matter, only which pixels are drawn by the mask. E.g. you can define a mask using
-
An image (cgeref:TCastleImageControl[]) with alpha channel. Be sure to set cgeref:TCastleImageControl.AlphaChannel[] to cgeref:acTest[].
-
A viewport (cgeref:TCastleViewport[]), maybe even with something animated and/or 3D. Be sure to set cgeref:TCastleViewport.Transparent[] to
true
. -
A shape (like cgeref:TCastleRectangleControl[], cgeref:TCastleShape[]).
The masked children, in turn, can also be any UI control. So you can filter rendering of anything, even if it’s interactive (like a button) or 3D (like a viewport).
cgeref:TCastleMask.MaskRendering[] determines if the children are rendered where the mask is visible or (on the contrary) where the mask is not visible.
See the example examples/user_interface/mask for demonstration.
cgeimg::block[ui_mask.png|Mask,ui_mask_editor.png|Mask in editor]