01 Themes

(work in progress)

EZGUI themes are implemented in JSON format . they are composed of

A configuration section, where all theme specific parameters are defined.
A default component section : this define a fallback visual aspect of a component.
Skin sections : each one define the visual aspect of the given skin, if a skin name is the same as a component name, this skin will be applied to the component by default.

let's take a look at a theme sample :

{
    "__config__": {
        "name": "kenney",
        "resources": [
            "./kenney-atlas.json",
            "../fonts/desyrel.fnt",
            "../fonts/Skranji-Bold-40.fnt"
        ]
    },
    "default": {
        "bg": "wnd-grey-bg.png",
        "padding" : 2,
        "bgPadding": 6,
        "corner": "wnd-grey-corner.png",
        "line": "wnd-grey-line.png",
        "font": {
            "size": "20px",
            "family": "Arial",
            "color": "black"
        }
    },
    "Window": {
        "bgPadding": 5,
        "bg": "wnd-grey-bg.png",
        "corner": "wnd-grey-corner.png",
        "line": "wnd-grey-line.png"
    }, 
     "Button": {
        "bgPadding": 6,
        "bg": "btn-grey-bg.png",
        "corner": "btn-grey-corner.png",
        "line": "btn-grey-line-t.png"
    },
    "bluebutton": {
        "bgPadding": 6,
        "bg": "btn-blue-bg.png",
        "corner": "btn-blue-corner.png" ,
        "line": "btn-blue-line.png" 
    }
}

in the above example we define the theme name and resources in the configuration section. the default section define some properties.

then we have three skins : Window, Button and bluebutton. since Window and Button are also the names of EZGUI components, those skins will be used as default Window and Button skins... but the user can explicitly specify the skin he want to use for a given component. for example you can declare a Button component and tell EZGUI to use bluebutton as skin instead of the default Button skin.

Configuration section

The configuration section is a special theme entry named config in the current version it's only used to define the theme name and resources theme resources can be atlases, textures or bitmap fonts, if some resources are defined EZGUI will make sure that they are ready before applying the theme to a component. if those resources are already loaded by the default Pixi or Phaser loader, you'll not have to declare them here. bu for organization and to make your GUI totally independent from the game, it's recommended to store theme specific resources under the theme folder, and declare them using config resources section.

Default section

Skin properties

*scale (number) : define the scale of theme images, this allow you to get cross-platform hight quality graphics by using high resolution images for themes and scaling them down.
padding (number) : The padding property is used by container components like Window or List, it specify the distance from border from which the children components are cropped. for example if you use a large border in your theme, you don't want the component to apear in top of it, in this case, you need to increase padding value .
font (Theme font) : if the component support text, this font will be used.
bg (Theme image) : the image used to fill the background.
bgPadding (number) : distance between the component borders and the background tiling image. this is useful when defining background for rounded corners component. if you don't set bgPadding, the background will be visible behind the external area of the rounded corner.
bgTiling ('x' or 'y') : if specified, will restrict tiling to one direction. in some cases you don't want the background image to tile in all directions.
corner (Theme image) : the image used for all corners, the specified image should be the top left corner one, EZGUI will rotate it to get other corners. this property is overriden by corner-* properties.
corner-tl (Theme image) : same as corner, but is specific to top left corner.
corner-tr (Theme image) : same as corner, but is specific to top right corner.
corner-bl (Theme image) : same as corner, but is specific to bottom left corner.
corner-br (Theme image) : same as corner, but is specific to bottom right corner.
line (Theme image) : the image used for all borders, the specified image should be the top border line image, EZGUI will rotate it to get other border sides. this property is overriden by line-* properties.
line-t (Theme image) : same as line, but is specific to top side.
line-r (Theme image) : same as line, but is specific to right side.
line-b (Theme image) : same as line, but is specific to bottom side.
line-l (Theme image) : same as line, but is specific to left side.
checkmark (image) : for components supporting a "checked" state like Checkboxes or Radios, this property define the image added on top of the component when it is checked.

Theme font

a font object has three properties

size (string) : the size in pixels. examples : '11px', '24px' ...
family (string) : the font family, EZGUI will check first if there is a bitmap font with the given name and use it, if not it'll use the system font.
color (string) : a CSS color name. examples : '#ff0000', '#b45', 'red', 'green' ...etc

Theme image

EZGUI use an image description object which allow an image to have different states : default, down, up, hover and out. those states are used by some component to know what image to use depending on their current state. for example, when a Button component receive a mousedown event, it'll use the 'down' state images if available.

a theme image can be a pixi frame name, in this case the frame name is a string defining either an atlas ID or a path name. or a JSON object defining different states in this case, each state will define a frame name, default state is mandatory.

example of valid theme images :

 bg : 'my-atlas-frame.png'

 bg : './assets/images/background1.png'

 bg : {default : './assets/images/background1.png'}

 bg : {default : './assets/images/background1.png', down:'./assets/images/background1-down.png'}

Provide feedback

Saved searches