libgdx API

com.badlogic.gdx.scenes.scene2d.ui
Class Skin

java.lang.Object
  extended by com.badlogic.gdx.scenes.scene2d.ui.Skin
All Implemented Interfaces:
Disposable

public class Skin
extends java.lang.Object
implements Disposable

A skin holds styles for widgets and the resources (texture regions, ninepatches, bitmap fonts, etc) for those styles. A skin has a single texture that the resources may reference. This reduces the number of texture binds necessary for rendering many different widgets.

The resources and styles for a skin are usually defined using JSON (or a format that is JSON-like), which is formatted in this way:

 {
        resources: {
                className: {
                        name: value,
                        ...
                },
                ...
        },
        styles: {
                className: {
                        name: value,
                        ...
                },
                ...
        }
 }
 
There are two sections, one named "resources" and the other "styles". Each section has a class name, which has a number of names and values. The name is the name of the resource or style for that class, and the value is the serialized resource or style. Here is a real example:
 {
        resources: {
                com.badlogic.gdx.graphics.g2d.TextureRegion: {
                        check-on: { x: 13, y: 77, width: 14, height: 14 },
                        check-off: { x: 2, y: 97, width: 14, height: 14 }
                },
                com.badlogic.gdx.graphics.Color: {
                        white: { r: 1, g: 1, b: 1, a: 1 }
                },
                com.badlogic.gdx.graphics.g2d.BitmapFont: {
                        default-font: { file: default.fnt }
                }
        },
        styles: {
                com.badlogic.gdx.scenes.scene2d.ui.CheckBox$CheckBoxStyle: {
                        default: {
                                checkboxOn: check-on, checkboxOff: check-off,
                                font: default-font, fontColor: white
                        }
                }
        }
 }
 
Here some named resource are defined: texture regions, a color, and a bitmap font. Also, a CheckBox.CheckBoxStyle is defined named "default" and it references the resources by name.

Styles and resources are retrieved from the skin using the type and name:

 Color highlight = skin.getResource("highlight", Color.class);
 TextureRegion someRegion = skin.getResource("logo", TextureRegion.class);
 CheckBoxStyle checkBoxStyle = skin.getStyle("bigCheckbox", CheckBoxStyle.class);
 CheckBox checkBox = new CheckBox("Check me!", checkBoxStyle);
 
For convenience, most widget constructors will accept a skin and look up the necessary style using the name "default".

The JSON required for a style is simply a JSON object with field names that match the Java field names. The JSON object's field values can be an object to define a new Java object, or a string to reference a named resource of the expected type. Eg, Label.LabelStyle has two fields, font and fontColor, so the JSON could look like:

 someLabel: { font: small, fontColor: { r: 1, g: 0, b: 0, a: 1 } }
 
When this is parsed, the "font" field is a BitmapFont and the string "small" is found, so a BitmapFont resource named "small" is used. The "fontColor" field is a Color and a JSON object is found, so a new Color is created and the JSON object is used to populate its fields.

The order resources are defined is important. Resources may reference previously defined resources. This is how a BitmapFont can find a TextureRegion resource (see BitmapFont section below).

The following gives examples for the types of resources that are supported by default:

Color:

 { r: 1, g: 1, b: 1, a: 1 }
 
TextureRegion:
 { x: 13, y: 77, width: 14, height: 14 }
 
Skin.TintedNinePatch:
 [
        { x: 2, y: 55, width: 5, height: 5 },
        { x: 7, y: 55, width: 2, height: 5 },
        { x: 9, y: 55, width: 5, height: 5 },
        { x: 2, y: 60, width: 5, height: 11 },
        { x: 7, y: 60, width: 2, height: 11 },
        { x: 9, y: 60, width: 5, height: 11 },
        { x: 2, y: 71, width: 5, height: 4 },
        { x: 7, y: 71, width: 2, height: 4 },
        { x: 9, y: 71, width: 5, height: 4 }
 ]
 
Skin.TintedNinePatch can also be specified as a single region, which is set as the center of the ninepatch:
 [ { width: 20, height: 20, x: 6, y: 2 } ]
 
This notation is useful to use a single region as a ninepatch. Eg, when creating a button made up of a single image for the Button.ButtonStyle.up field, which is a ninepatch.

BitmapFont:

 { file: default.fnt }
 
First the skin tries to find the font file in the directory containing the skin file. If not found there, it uses the specified path as an Files.FileType.Internal path. The bitmap font will use a texture region with the same name as the font file without the file extension. If no texture region with that name is defined in the skin (note the order resources are defined is important), it will look in the same directory as the font file for a PNG with the same name as the font file but with a "png" file extension.

TintedNinePatch provides a mechanism for tinting an existing NinePatch:

 { name: whiteButton, color: blue }
 
This would create a new NinePatch identical to the NinePatch named "whiteButton" and tint it with the color named "blue".

The skin JSON is extensible. Styles and resources for your own widgets may be included in the skin, usually without writing any code. Deserialization is handled by the Json class, which automatically serializes and deserializes most objects. While nearly any style object can be automatically deserialized, often resource objects require custom deserialization. Eg, TextureRegion, BitmapFont, and NinePatch need to reference the skin's single texture. If needed, getJsonLoader(FileHandle) may be overridden to register additional custom serializers. See the source for getJsonLoader(FileHandle) for examples on how to write serializers.

Note that there is a SkinPacker class in the gdx-tools project that can take a directory of individual images, pack them into a single texture, and write the proper texture region and ninepatch entries to a skin JSON file. The styles and other resources sections still need to be written by hand, but SkinPacker makes the otherwise tedious entry of pixel coordinates unnecessary.

Author:
Nathan Sweet

Nested Class Summary
static class Skin.TintedNinePatch
           
 
Constructor Summary
Skin()
           
Skin(FileHandle skinFile)
           
Skin(FileHandle skinFile, FileHandle textureFile)
           
Skin(FileHandle skinFile, Texture texture)
           
 
Method Summary
 void addResource(java.lang.String name, java.lang.Object resource)
           
 void addStyle(java.lang.String name, java.lang.Object style)
           
 void dispose()
          Disposes the Texture and all Disposable resources of this Skin.
 java.lang.String findStyleName(java.lang.Object style)
          Returns the name of the specified style object, or null if it is not in the skin.
 Color getColor(java.lang.String name)
           
 BitmapFont getFont(java.lang.String name)
           
protected  Json getJsonLoader(FileHandle skinFile)
           
 NinePatch getPatch(java.lang.String name)
           
 TextureRegion getRegion(java.lang.String name)
           
<T> T
getResource(java.lang.String name, java.lang.Class<T> type)
           
<T> T
getStyle(java.lang.Class<T> type)
           
<T> T
getStyle(java.lang.String name, java.lang.Class<T> type)
           
 Texture getTexture()
          Returns the single Texture that all resources in this skin reference.
 boolean hasResource(java.lang.String name, java.lang.Class type)
           
 boolean hasStyle(java.lang.String name, java.lang.Class type)
           
 void load(FileHandle skinFile)
           
 NinePatch newTintedPatch(java.lang.String patchName, Color color)
           
 NinePatch newTintedPatch(java.lang.String patchName, java.lang.String colorName)
           
 NinePatch newTintedRegion(java.lang.String regionName, Color color)
           
 NinePatch newTintedRegion(java.lang.String regionName, java.lang.String colorName)
           
 void save(FileHandle skinFile)
           
 void setEnabled(Actor actor, boolean enabled)
          Sets the style on the actor to disabled or enabled.
 void setTexture(Texture texture)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Skin

public Skin()

Skin

public Skin(FileHandle skinFile)

Skin

public Skin(FileHandle skinFile,
            FileHandle textureFile)

Skin

public Skin(FileHandle skinFile,
            Texture texture)
Method Detail

load

public void load(FileHandle skinFile)

addResource

public void addResource(java.lang.String name,
                        java.lang.Object resource)

getResource

public <T> T getResource(java.lang.String name,
                         java.lang.Class<T> type)

hasResource

public boolean hasResource(java.lang.String name,
                           java.lang.Class type)

getPatch

public NinePatch getPatch(java.lang.String name)

getColor

public Color getColor(java.lang.String name)

getFont

public BitmapFont getFont(java.lang.String name)

getRegion

public TextureRegion getRegion(java.lang.String name)

addStyle

public void addStyle(java.lang.String name,
                     java.lang.Object style)

getStyle

public <T> T getStyle(java.lang.Class<T> type)

getStyle

public <T> T getStyle(java.lang.String name,
                      java.lang.Class<T> type)

hasStyle

public boolean hasStyle(java.lang.String name,
                        java.lang.Class type)

findStyleName

public java.lang.String findStyleName(java.lang.Object style)
Returns the name of the specified style object, or null if it is not in the skin. This compares potentially every style object in the skin of the same type as the specified style, which may be a somewhat expensive operation.


setEnabled

public void setEnabled(Actor actor,
                       boolean enabled)
Sets the style on the actor to disabled or enabled. This is done by appending "-disabled" to the style name when enabled is false, and removing "-disabled" from the style name when enabled is true. A method named "getStyle" is called the actor via reflection and the name of that style is found in the skin. If the actor doesn't have a "getStyle" method or the style was not found in the skin, no exception is thrown and the actor is left unchanged.


newTintedPatch

public NinePatch newTintedPatch(java.lang.String patchName,
                                java.lang.String colorName)

newTintedPatch

public NinePatch newTintedPatch(java.lang.String patchName,
                                Color color)

newTintedRegion

public NinePatch newTintedRegion(java.lang.String regionName,
                                 java.lang.String colorName)

newTintedRegion

public NinePatch newTintedRegion(java.lang.String regionName,
                                 Color color)

setTexture

public void setTexture(Texture texture)

getTexture

public Texture getTexture()
Returns the single Texture that all resources in this skin reference.


dispose

public void dispose()
Disposes the Texture and all Disposable resources of this Skin.

Specified by:
dispose in interface Disposable

save

public void save(FileHandle skinFile)

getJsonLoader

protected Json getJsonLoader(FileHandle skinFile)

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)