USL

Work In Progress

USL (UI Styling Language) is an alternative for writing skin styles in JSON file for scene2d.ui.

USL syntax is very similar to JSON but it allows extending and inheriting other styles which results in much cleaner skin file. Take a look at VisUI style written in USL, the same skin in JSON

USL files are converted to JSON by vis-usl.jar you can download it here. Note that this is alpha version, please report any issues you found.
Usage: java -jar vis-usl-x.y.z.jar <input usl file path> <output json file path>

Examples

GDX default skin: gdx.usl
VisUI skin: visui.usl

Language Reference

Comment

Line comments stars with // e.g. //this is a comment. For now avoid putting comments inside styles or identifiers.

Include

Include directive allows to include other USL files in current file. For example: include "other.usl" the path is relative to current parsed file. USL comes with 2 premade styles that can be included gdx and visui, to use them you have to use <> instead of "", for example: include <visui>

include "other.usl"
include "dir/other2.usl"
include <gdx>
include <visui>

Style blocks

Style blocks contains styles definition for single class in your code. Style blocks and styles are in a very similar way as is it done in JSON. Style blocks starts with #

#Button$ButtonStyle: {
	//... styles definition
}

Style blocks may extend other blocks:

#TextButton$TextButtonStyle extends ButtonStyle: {
	//... styles definition
}

Extending other block will merge all its other styles into this style. If you add new style with the same name as in parent block then all properties from super style will by copied into new style.

#Button$ButtonStyle: {
	default: { down: default-round-down, up: default-round }
}

#TextButton$TextButtonStyle extends ButtonStyle: {
	default: { font: default-font, fontColor: white } // `down` and `up` property will be inherited from parent block
}

Styles

Styles are defined in style blocks (except global styles, see below). It doesn't differ much from json.

#Button$ButtonStyle: {
	default: { down: default-round-down, up: default-round }
	toggle inherits default: { checked: default-round-down }
}

Internal styles can inherits form each other, the toggle style will have all properties of default.

The style can be defined as meta-style. Meta-style can be inherited by other styles but the meta-style itself won't be inlcuded in output json styles. Meta-styles starts with -

#Slider$SliderStyle: {
	-base: { knob: slider-knob, disabledKnob: slider-knob-disabled }
	default-horizontal inherits base: { background: slider }
	default-vertical inherits base: { background: slider-vertical }
}

Global Styles

Global styles can be inherited by any other style or identifier. Global styles alwyas starts with . and should be placed in the top part of USL file. For example:

.font: { font: default-font, fontColor: white, disabledFontColor: grey }
.focus-border: { focusBorder: border }
.focus-border-circle: { focusBorder: border-circle }

Later you can inherit those styles, all properties from global styles will be placed inside style that inherits it:

#TextField$TextFieldStyle: {
	default inherits .font: { selection: selection, background: textfield, cursor: cursor }
}

Global style can be also inherited by nested identifiers:

#tabbedpane.TabbedPane$TabbedPaneStyle: {
	default: { background: menu-bg, bottomBar: list-selection,
	       	   buttonStyle inherits .font: { down: button-down, up: button, checked: button-down, over: button-over } }
}

Style blocks override

Blocking overriding is useful when extending premade skin such as default libGDX skin or VisUI skin. Block overrides starts with ^ and doesn't have to specify full block name with package.

For example:

include <visui>

^VisTextButtonStyle: {
	custom inherits default: { over: button-down }
	custom2 { up: button-up, down: button-down }
}

Package

Multiple styles block can be put into single package to avoid writing long names for every style block.

package com.foo.bar {
	#Button$ButtonStyle: {
		//... styles definition
	}

	//...
}

//is equivalent to:

#com.foo.bar.Button$ButtonStyle: {
	//... styles definition
}