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

The default section is a skin (see Skin properties below) having 'default' as name. It defines the skin to which the gui will fallback if it doesn't find a user specified skin name, or a missing property.

For example, in the default section you can define the default font properties, which will be shared by all components, then you can override them in each component.

Skin properties

scale (number) : Defines the scale of theme images. This allows you to get cross-platform high 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 specifies 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 appear on top of it. In this case, you would need to increase padding value.
font (Theme font) : If the component supports 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 overridden 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 overridden 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.
transparent (boolean) : If false will not draw the component, text and children are not affected.
checkmark (image) : For components supporting a "checked" state like Checkboxes or Radios, this property defines 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 uses an image description object which allows an image to have different states: default, down, up, hover and out.

Those states are used by some components 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.

Examples 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