Styled UI - coldrockgames/gml-raptor GitHub Wiki

At the starting page of the UI Subsystem, the style-array is mentioned as one of four ways to create your UI.

This page takes a closer look at this feature.

A style-array looks like this:

[
  [ Panel, { min_height: 144, dock: dock.top, padding: 12 } ,
      [ Label, struct_join(label_struct, { text: "[scale,1.5][ci_accent]UTE - raptor Unit Test Engine", position: [48,32]}) ],
      [ Label, struct_join(label_struct, { text: "[scale,1.5]Discovered Test Suites", position: [48,84]}) ],
      [ Label, struct_join(label_struct, { text: "[scale,1.5]Detailled Test Results", position: [968, 84]}) ],
  ],

  [ ScrollPanel, struct_join(scrpanel_struct, { 
      min_width:         1000, 
      dock:              dock.right,
      content_autofill:  [true, 4],
      content_object:    [UnitTestResultsViewer, { detail_mode: true, }]
    })
  ],

  [ ScrollPanel, struct_join(scrpanel_struct, { 
      dock:              dock.fill,
      content_autofill:  [true, 4],
      content_object:    [UnitTestResultsViewer, { detail_mode: false, }]
    })
  ]
]

Let's go through this, step by step.

• It must be an array (and not a struct) because the order matters and structs can not guarantee to have a constant order of items.
• You always create one single array which contains several sub-arrays. Speaking of json or GML, you always create
  [ ...content... ].
• Each of the sub-arrays follows this structure:
  • [ type_to_create, <style_struct> ] for any non-container item (like the Label objects above) or
  • [ type_to_create, <style_struct>, [ next-level-subarray], ... ] ] for containers (like the Panel above, which contains the Labels)
• So you create any hierarchy in the form of array containing a type, init/style structs and another inner array for the elements of the container

• You do not have to deal with the ControlTree itself, no need to care about when and what to .build(), no need to call all those functions.
• Just pure content, pure data.
• Highly dynamic, as you could even build such an array at runtime of your game and create dynamic UIs (like windows for inventories and similar things) specialized for the view you want to show.
• It can be "put together" like Lego pieces at runtime.
• It is compatible with the json format, so you can define your UI freely in your game configuration files, hence you could even "drop" parts of those array from your Race query to create custom details/properties views based on the dropped item from a loot table.

Behind the scenes, raptor executes a function which iterates recursively through this array and does all the .add_control(...) and .build() calls for you.

On every ] end-of-array, if it contained sub-arrays (i.e. if it was a container), .build() is invoked to make sure, the container has done all the calculations.

When reaching the end of the top-level array, .build() is invoked on the master container, finishing the UI layout process.

With this feature, you can create UIs without any knowledge about the ControlTree itself, aside of knowing the functions, that are supported for the style_struct.

Raptor offers two public functions, that will render this style-array for you:

/// @func	styled_ui_create_room(_style_array)
/// @desc	Submit a style_array to the UI_ROOT for the
///		main ui of the current room.
///		UI_ROOT.clear_children() is invoked, before the
///		array gets applied.
///		This function always returns the UI_ROOT for chainability.
function styled_ui_create_room(_style_array) {

/// @func	styled_ui_create(_container_or_tree, _layer_or_depth, _init_struct, _style_array)
/// @desc	Submit a style_array to any styleable control (i.e. any _baseContainerControl).
///			You can create panels or windows or any other container.
///			instance_create(...) is called for you and the created control will be returned.
function styled_ui_create(_container_or_tree, _layer_or_depth, _init_struct, _style_array) {

In short terms, every set_* function in ControlTree can be used as a property in the style-struct. You do not have to write "set_". When you write dock: dock.fill, raptor translates this into a call to set_dock(dock.fill).

Available commands in a standard ControlTree

Additional Commands available in a ScrollPanelControlTree