Simple controls

Common properties of all simple controls

Description

A lot of controls in BlockOut use a common properties scheme. Meaning that if they share a lot of the same traits they will have the same set of properties. Internally controls are divided into two categories: Simple and Hosting. This division is made to control the position calculation logic when BlockOut updates the controls.

Simple controls

Simple controls do not posses child controls, but usually fulfill a specific purpose, like a button or a textbox. Even though it seems like that a button and a textbox do not have much in common, from BlockOut's perspective they do. They both have an id, a style, a parent, etc.

To make it easier for you, these controls have largely the same scheme which we will describe on this page. There are properties where it makes more sense to set them in code, and there is at least one property you can not set directly: parent. This property, which represents the control, the targeted control is in, is determined by the engine during parsing and construction of the UI and is automatically set for you. ##Properties

Required

Some properties listed here are not strictly required, but the without setting them, controls might work properly, but things will look a bit weird.

Property	Descriptor	Description	Examples
Type	type	The type of the control	root, button, label, region, etc
Id	id	This is the id of the control in the UI.	button_accept, label_username, slot_1
Style	style	The style id of the control.	blockout:default, minecolonies:citizen
Alignments	alignment	The alignment of the control	"TOP", "TOP, LEFT", "t", "tl"
Dock	dock	The place where the control is docked	"NONE", "TOP"
Margin	margin	The margin of this control relative to its parents child control box	"0", "1, 2", "1, 2, 3, 4"
Size	size	The size of the control. If a dock / alignment is set, then that might influence the size as well	"10", "10, 11"
Visible	visible	Indicates if the control should accept input and should be rendered	true, false
Enabled	enabled	Indicates if the control should accept input	true, false

Details

In this section you will find a detailed description of what each property does and how it behaves when a certain value is set. Each property is either marked with Required or Recommended. If the property is recommended then the default value is specified with it.

Type (Required)

See the individual controls for their type markers. Certain languages allow for the embedding of type markers into their language. The default UI language, json, does not however and the type of control has to be specified like any other normal property. See below for an example.

Id (Required)

The id of the control allows the backing code systems to find the control in the UI, in case some modification needs to be made. During construction of the UI this id is also used to bind the event-handlers (like click) or properties (setting them via code) to this control. So a mismatched id is the most likely cause of the code-behind-systems not working properly.

Style (Recommended: blockout:default)

The style id of a control indicates which style to ask for a resource first. If the style that corresponds with the given id is not found, or does not have the resource requested by the control, then all other styles are asked for the resource, possible in a random order.

Alignment (Recommended: Top,Left)

This indicates where the margin property of this control anchors. Options are:

• Top, anchor to the top
• Left, anchor to the left
• Right, anchor to the right
• Bottom, anchor to the bottom
• None, anchor nowhere. Only sometimes useful in combination with other properties like Dock

Dock (Recommended: None)

This overrides the Alignment and Size properties to stretch a element to its parent. Options are:

• TOP, stretches the control over the top of the parent, leaving its y-size intact.
• LEFT, stretches the control over the left side of the parent, leaving its x-size intact.
• RIGHT, stretches the control over the right side of the parent, leaving its x-size intact, but inverted.
• BOTTOM, stretches the control over the bottom side of the parent, leaving its y-size intact, but inverted.

Margin (Recommended: 0,0,0,0)

Depending on the Alignment property this control the distance between the controls anchor position and the parents children box. So 0,0,0,0 with a TOP,LEFT alignment would move the control to the top left corner of the parents children box.

Size (Required)

The size of the control. Period.

Optional

Property	Descriptor	Description	Examples
Visible	visible	Indicates if the control should accept input and should be rendered	true, false
Enabled	enabled	Indicates if the control should accept input	true, false

Details

Visible (Default: true)

Indicates if this control is visible or not. An invisible control can not accept any input.

Enabled (Default: true)

Indicates if this control can accept input, if it is visible.

Definition

JSON

See the individual controls for more details. Json property order does not matter.

{
  "type": "blockout:dummy",
  "id": "dummy",
  "size": "15,12",
  "alignment": "RIGHT,BOTTOM"
}

{
  "type": "blockout:another_dummy_control_type",
  "id": "dummy_the_second_with_dock",
  "size": "90,12",
  "dock": "TOP"
}