Extra Settings JSON Layout

From PGE Wiki
Jump to navigation Jump to search

Extra Settings JSON Layout - Is a special file which is used to declare set of extra propertes for your element in the config pack.

Specification

The full specification of Extra Settings Layout. JSON file you are creating must be saved in UTF8 encoding.

Group box style

Root

  • style - string, Defines the type of layout
    • frame - Same as groupbox, but without border and without title
    • groupbox - Show extra settings as GUI elements
  • title - string, Defines the title of extra settings layout box
  • layout - array, Contains list of control elements are will be presented on the layout

Control element

  • control - [REQUIRED], string, type of control.
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover

Control: spinBox

Gives integer or decimal setting.

  • control - must be set to "spinBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • type - [REQUIRED], string, Type of value: integer or decimal:
    • int - Integer type
    • double - Decimal type
  • value-default - [REQUIRED], integer/decimal, Initial value of this control
  • value-min - [Optional], integer/decimal, Minimal allowed value
  • value-max - [Optional], integer/decimal, Maximal allowed value
  • single-step - [Optional], integer/decimal, Size of one value change step, done by mouse wheel or arrow buttons on the control
  • decimals - [Optional], integer, Precission of the decimal number value


Control: checkBox

Gives boolean settings.

  • control - must be set to "checkBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], boolean (`true` or `false`), Initial value of this control
  • text-at-left - [Optional], boolean (`true` or `false`), Show the text at the left side of a checkbox

Control: color

Gives color settings.

  • control - must be set to "color" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], a hex color (`#RRGGBB`, or `#RRGGBBAA`, or constant color name, etc. that approvable by QColor), Initial value of this control
  • alpha-channel - [Optional], boolean (`true` or `false`), Enable or disable using of an alpha-channel (true by default)
  • placeholder - [Optional], string, a gray text shown in the empty field

Quote from Qt documentation related to color string format

Sets the RGB value of this QColor to name, which may be in one of these formats:

  • #RGB (each of R, G, and B is a single hex digit)
  • #RRGGBB
  • #AARRGGBB (Since 5.2)
  • #RRRGGGBBB
  • #RRRRGGGGBBBB
  • A name from the list of colors defined in the list of SVG color keyword names provided by the World Wide Web Consortium; for example, "steelblue" or "gainsboro". These color names work on all platforms. Note that these color names are not the same as defined by the Qt::GlobalColor enums, e.g. "green" and Qt::green does not refer to the same color.
  • transparent - representing the absence of a color.

The color is invalid if name cannot be parsed.

Control: comboBox

Gives an indexed labeled list of settings.

  • control - must be set to "comboBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • elements - [REQUIRED], array of strings, Elements for choice.
  • value-default - [REQUIRED], integer, Initial value of this control, index of element in the given list


Control: flagBox

Gives a group of boolean settings are stored as integer and indexed bitwisely per bit at left.

  • control - must be set to "flagBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • elements - [REQUIRED], array of strings, Elements for choice.
  • value-default - [REQUIRED], integer, Initial value of this control, a bitwise mask of all flags are set or unset.


Control: lineEdit

Gives a single-line text string setting.

  • control - must be set to "lineEdit" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • max-length - [Optional], integer, String length limitation. If not defined, string length is not limited.
  • validator - [Optional], string, Regular Expression which stricts specific string format that must be typed into this field.
  • placeholder - [Optional], string, a gray text shown in the empty field
  • read-only - [Optional], boolean (`true` or `false`), set this field as read-only


Control: multiLineEdit

Gives a multi-line text string setting.

  • control - must be set to "multiLineEdit" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • read-only - [Optional], boolean (`true` or `false`), set this field as read-only


Control: file

Gives a string field with a file choosing button

  • control - must be set to "file" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • directory - [Optional], "episode" or "data", a root directory to list files: episode or level/world data (episode is a default), file browser can't go upper than this directory
  • directory-relative - [Optional], "episode" or "data", an initial root directory to list files (data is a default), it should be equal or lower than root
  • dialog-title - [Optional], string, Title of the file selection dialog
  • dialog-description - [Optional], string, Description label on the file selection dialog
  • filters - [Optional]', array of strings, A list of filename filters to show (default is ["*.*"])

Control: musicFile

Gives a string field with a music file choosing button and play button for a preview

  • control - must be set to "musicFile" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • directory - [Optional], "episode" or "data", a root directory to list files: episode or level/world data (episode is a default), file browser can't go upper than this directory
  • directory-relative - [Optional], "episode" or "data", an initial root directory to list files (data is a default), it should be equal or lower than root
  • dialog-title - [Optional], string, Title of the file selection dialog
  • dialog-description - [Optional], string, Description label on the file selection dialog
  • filters - [Optional]', array of strings, A list of filename filters to show (default is a built-in list of supported music formats)


Control: soundFile

Gives a string field with a sound effect file choosing button and play button for a preview

  • control - must be set to "soundFile" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • directory - [Optional], "episode" or "data", a root directory to list files: episode or level/world data (episode is a default), file browser can't go upper than this directory
  • directory-relative - [Optional], "episode" or "data", an initial root directory to list files (data is a default), it should be equal or lower than root
  • dialog-title - [Optional], string, Title of the file selection dialog
  • dialog-description - [Optional], string, Description label on the file selection dialog
  • filters - [Optional]', array of strings, A list of filename filters to show (default is a built-in list of supported SFX formats)


Control: levelFile

Gives a string field with a level file choosing button

  • control - must be set to "levelFile" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • value-default - [REQUIRED], string, Initial value of this control.
  • directory - [Optional], "episode" or "data", a root directory to list files: episode or level/world data (episode is a default), file browser can't go upper than this directory
  • directory-relative - [Optional], "episode" or "data", an initial root directory to list files (episode is a default), it should be equal or lower than root
  • dialog-title - [Optional], string, Title of the file selection dialog
  • dialog-description - [Optional], string, Description label on the file selection dialog
  • filters - [Optional]', array of strings, A list of filename filters to show (default is a built-in list of supported level file formats)


Control: itemSelect

Gives a button to select one of game elements

  • control - must be set to "itemSelect" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • type - [REQUIRED], "block", "bgo", "npc", "terrain", "scenery", "path", "level", A type of a game element to select.
  • value-default - [REQUIRED], string, Initial value of this control.


Control: description

A non-editable block of HTML-formatted text

  • control - must be set to "description" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • text - [REQUIRED], string, An HTML text that will be shown on the box. Any clickable URLs can be added here.


Control: sizeBox

Gives a group of two integer or decimal settings are labeled as Width and Height.

  • control - must be set to "sizeBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • type - [REQUIRED], string, Type of value: integer or decimal:
    • int - Integer type
    • double - Decimal type
  • value-default - [REQUIRED], object, Initial value of this control
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value
  • value-min - [Optional], object, Minimal allowed value
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value
  • value-max - [Optional], object, Maximal allowed value
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value


Control: pointBox

Gives a group of two integer or decimal settings are labeled as X and Y.

  • control - must be set to "pointBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • type - [REQUIRED], string, Type of value: integer or decimal:
    • int - Integer type
    • double - Decimal type
  • value-default - [REQUIRED], object, Initial value of this control
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value
  • value-min - [Optional], object, Minimal allowed value
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value
  • value-max - [Optional], object, Maximal allowed value
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value


Control: rectBox

Gives a group of four integer or decimal settings are labeled as X, Y, Width, and Height.

  • control - must be set to "rectBox" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
  • title - [REQUIRED], string, Understandible name of field will be shown in the Editor.
  • tooltip - [Optional], string, Pop-up hint that appears on mouse hover
  • type - [REQUIRED], string, Type of value: integer or decimal:
    • int - Integer type
    • double - Decimal type
  • value-default - [REQUIRED], object, Initial value of this control
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value
  • value-min - [Optional], object, Minimal allowed value
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value
  • value-max - [Optional], object, Maximal allowed value
    • x - [REQUIRED], integer/decimal, X position value
    • y - [REQUIRED], integer/decimal, Y position value
    • w - [REQUIRED], integer/decimal, Width value
    • h - [REQUIRED], integer/decimal, Height value


Control: Group of controls (sub-tree)

Gives you a sub-tree of elements.

  • control - must be set to "group" (case insensitive)
  • name - [REQUIRED], string, Name of data field accessible from the Lua API.
Note: If you will set the name field to have the two dots value "..", all children settings data will be recorded in a dump in a current branch without creation of a new named branch.
  • title - [REQUIRED] (optional when "name" is equal to ".."), string, Understandible name of field will be shown in the Editor.
  • children - [REQUIRED], array, Child controls are included into this group.

Example layout

An example layout

{
	"style" : "tree",
	"title" : "Sample setup",
	"layout": [{
			"control": "spinBox",
			"type": "int",
			"name": "testNumber",
			"title": "Test integer number value",
			"tooltip": "Testing integer value number to test this control",
			"value-default": 5,
			"value-min": -42,
			"value-max": 42,
			"single-step": 2
		},
		{
			"control": "checkbox",
			"name": "checkMe",
			"title": "Check me",
			"tooltip": "It's one best control to check it",
			"value-default": false
		},
		{
			"control": "checkbox",
			"name": "checkMeNot",
			"title": "Don't check me, jerk",
			"tooltip": "Oh, no, suggested to never touch this...",
			"value-default": true
		},
		{
			"control": "combobox",
			"name": "choice",
			"title": "Choose me",
			"elements": ["zero", "one", "two", "three", "four"],
			"value-default": 1
		},
		{
			"control": "flagbox",
			"name": "choice2",
			"title": "Choose of:",
			"elements": ["zero", "one", "two", "three", "four"],
			"value-default": 21
		},
		{
			"control": "sizebox",
			"name": "sizeOfMyPlant",
			"title": "Size of?",
			"value-min": {"w": 2, "h" : 2},
			"value-max": {"w": 42,  "h": 42},
			"value-default": {"w": 41, "h" : 34}
		},
		{
			"control": "sizebox",
			"type": "double",
			"decimals": 4,
			"name": "floatingBrick",
			"title": "Floating brick",
			"value-min": {"w": 2.2, "h" : 2.0},
			"value-max": {"w": 42.0,  "h": 42.1},
			"value-default": {"w": 41.52, "h" : 34.2}
		},
		{
			"control": "pointBox",
			"name": "whereIsMySombrero",
			"title": "Where?",
			"value-default" : {"x":12, "y":12}
		},
		{
			"control": "pointBox",
			"type": "double",
			"decimals": 3,
			"name": "floatOfWhere",
			"title": "Float Where?",
			"value-default" : {"x":12.02, "y":-12.1}
		},
		{
			"control": "rectBox",
			"name": "iCanSeeYou",
			"title": "Rects, Rects.... rects!!!",
			"value-default": {"x":-12, "y":34, "w":12, "h":12}
		},
		{
			"control": "rectBox",
			"type": "double",
			"decimals": 5,
			"name": "fanSeeYou",
			"title": "Floating rects!",
			"value-default": {"x":-1.02, "y":34.0, "w":12.054, "h":12.11}
		},
		{
			"control": "spinBox",
			"type": "double",
			"name": "floatTest",
			"title": "Test floating number value",
			"value-default": 5.0,
			"value-min": -42.0,
			"value-max": 42.0,
			"single-step": 0.1,
			"decimals" : 3
		},
		{
			"control": "group",
			"name": "alienTrash",
			"title": "Some alien trash",
			"children": [{
					"control": "spinBox",
					"type": "int",
					"name": "child1",
					"title" : "Kek",
					"value-default": 5,
					"value-min": -42,
					"value-max": 42
				},
				{
					"control": "lineEdit",
					"type": "string",
					"name": "child2",
					"title" : "Pek",
					"value-default": "",
					"max-length": 42,
					"validator": "^a\\ me\\dw$"
				},
				{
					"control": "lineEdit",
					"name": "child3",
					"title" : "Tek",
					"value-default": "",
					"max-length": 5
				}
			]
		},
		{
			"control": "group",
			"name": "someAnother",
			"title": "Another...",
			"children": [{
					"control": "spinBox",
					"type": "int",
					"name": "kekVision",
					"title" : "Kek",
					"value-default": 5,
					"value-min": -42,
					"value-max": 42
				}
			]
		}
	]
}

Example of settings dump

An example settings dump generated from given sample.

Note:

Keep an attention that fields are not appearing in this dump until a first change in a settings was made. So, to deal with these values, follow next tips:

  • If dump is blank - treat all values by their defaults
  • When dump is here and it has missing fields - treat any missing fields by their defaults
  • Please validate values in the dump to avoid errors caused by old dumps are left after changes without field renaming
{
    "alienTrash": {
        "child1": 12,
        "child2": "a me9w",
        "child3": "1t4t1"
    },
    "checkMe": true,
    "checkMeNot": false,
    "choice": 3,
    "choice2": 24,
    "fanSeeYou": {
        "h": 12.11,
        "w": 12.054,
        "x": -1.05224,
        "y": 34
    },
    "floatOfWhere": {
        "x": 12.02,
        "y": -12.104
    },
    "floatTest": 3.6999999999999993,
    "floatingBrick": {
        "h": 34.2,
        "w": 40.22
    },
    "iCanSeeYou": {
        "h": 18,
        "w": 11,
        "x": 38,
        "y": -64
    },
    "sizeOfMyPlant": {
        "h": 21,
        "w": 4
    },
    "someAnother": {
        "kekVision": 5
    },
    "testNumber": 27,
    "whereIsMySombrero": {
        "x": 6,
        "y": -35
    }
}