UI Subsystem - Grisgram/gml-raptor GitHub Wiki

With Release 3.0 of raptor, a complete rewrite of the UI took place. All controls, windows and MessageBoxes have been rewritten and now offer functionality that you know from Windows Development (if you ever did that...)

First thing to know is, that there are two layers of controls available in raptor.
There are the base controls, which reside in UI\controls folder of raptor and are all prefixed with "Raptor" in their name (like RaptorLabel, RaptorTextButton,...).
⛔ You should not modify these controls!

The second layer, are "your" controls, which are located in the _gml_raptor_ui_ folder in the root of your project.
✅ These controls are here, to be adapted to your own needs.

They are all "empty" child object of the Raptor* internal controls. Change variables, sprites, behavior, add code, do whatever you need to do with these controls.

Why are there two layers?
With 3.0, raptor was split into several smaller packages. The raptor core contains everything raptor, as it always has been. In addition to that, there are now some smaller packages available, that are safe from being changed through a raptor update. So far, when you tinkered with the internal controls of raptor, you were always at risk, when updating, that I might have changed something in the controls and maybe your work gets overwritten.
With the new system, you are safe. You can update raptor any time, but your controls will not be affected.

With that being said, let's take a look at what is contained in the raptor UI subsystem:

• All controls are implemented to auto-resolve strings through the LG Localization subsystem and format text through Scribble
• All controls can be docked, aligned, anchored or positioned freely in their container
• Available containers are the desktop/game ui layer, the Window control or the invisible Panel control
• You add controls in one of these ways:
  • Create your hierarchy/layout through the ControlTree in code (this is the new recommended way since 3.0)
  • Add them to the "desktop" of your game by adding controls to the UI_ROOT panel, which is available globally in every room (Each room has its own UI_ROOT), declared in the RoomController
  • Place them freely in the Room Editor, as you always did
  • Future Feature: Use the UI Designer tool (working on it, not yet released)

Also, new with release 3.0, there's theming and skins implemented in raptor. Basically, this is a set of predefined colors you want to use throughout your game's ui. All controls are set up to use the app theme through defined constants, which you set in the Game_Configuration.

UI Themes and UI Skins tell you everything, you need to know about this feature.

The controls are built object-oriented (as far as GML allows this) and follow this hierarchy:

Control	Description
Base Controls
Label	The most basic UI element, just a scribble string (text)
Containers
Panel	An invisible container that helps you aligning your layout
Window	A very powerful, movable, sizable dynamic window which can be used for every dialog
WindowXButton	A special ImageButton, used by the Window object
MessageBoxWindow	A special Window, used by the MessageBox Functions
MessageBoxWindowXButton	A special WindowXButton, used by the MessageBoxWindow object
Tooltips
Tooltip	Little info-tag when hovering the mouse over a control
Clickable Controls
TextButton	A standard button, containing a scribble-string as caption (text)
ImageButton	A standard button, containing a scribble-string as caption (text) and an image as icon (sprite_to_use)
Slider	A highly configurable value slider control
Checkable Controls
CheckBox	A standard checkbox
RadioButton	A standard radiobutton. You can have multiple radio groups in one container
Input Controls
InputBox	A comfortable text input control with lots of features. This control offers so much functionality, that I spent it its own InputBox sub page
Mouse Cursor
MouseCursor	A sprite-based mouse cursor replacement for the standard mouse cursor. Just drag one into your room in any layer. It works transparently and fully automated
MouseCursorCompanion	An attachment-object for your MouseCursor

I have created some lightweight controls, which help a bit with common tasks. Nothing too special, but still things, you do over and over again, especially when you do game jams and create new games frequently.

They can be found in the _gml_raptor_ui_\helpers folder of the project template and are ready-to-use, without any configuration needed.

Control	Description
GameVersionLabel	Child of Label which reads the version information from the game's version.json file and sets this as its text. This is the most easy way to display your version/build at the main screen
CopyrightLabel	Also a child of Label, with text set to =legal/copyright, so it will display copyright information from the localization file
FPSTracker	A simple control that measures the render time of frames and displays a text like 60 FPS
StoryTeller	A child of Label which utilizes scribble's Typist, to slowly write text, as if some character would be talking

When you start the Example Project Demo, you see these objects in action.

---

Read on in UI Themes or UI Skins or head directly to Base Controls.