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.

Tree style
Group box style
Button style

Root

  • style - string, Defines the type of layout
    • tree - Show extra settings as a table of settings
    • groupbox - Show extra settings as GUI elements
    • button - Show extra settings as GUI elements with using of expandable / collapsable blocks
  • 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/decial, Initial value of this control
  • value-min - [Optional], integer/decial, Minimal allowed value
  • value-max - [Optional], integer/decial, Maximal allowed value
  • single-step - [Optional], integer/decial, 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

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

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 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.


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.
  • title - [REQUIRED], 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 that fields are not appearing in this dump on first change only.

{
    "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
    }
}