Skin files from the libGDX tests can be used as a starting point. You will need: , uiskin.atlas, uiskin.json, and default.fnt. This enables you to quickly get started using scene2d.ui and replace the skin assets later.

Resources in a skin typically come from a , widget styles and other objects defined using JSON, and objects added to the skin via code. Even when JSON is not used, it is still recommended to use Skin with a texture atlas and objects added via code. This is much more convenient to obtain instances of drawables and serves as a central place to obtain UI resources.

Useful resources:

Resources

Each resource in the skin has a name and type. The regions from a texture atlas can be made available as resources in the skin. Texture regions can be retrieved as a ninepatch, sprite, tiled drawable, or drawable.

Resources can also be defined for a skin using JSON () or added using code:

  1. Skin skin = new Skin();
  2. skin.add("logo", new Texture("logo.png"));
  3. ...
  4. Texture logo = skin.get("logo", Texture.class);

There are convenience methods to retrieve resources for commons types.

  1. Color red = skin.getColor("red");
  2. BitmapFont font = skin.getFont("large");
  3. TextureRegion region = skin.getRegion("hero");
  4. NinePatch patch = skin.getPatch("header");
  5. Sprite sprite = skin.getSprite("footer");
  6. TiledDrawable tiled = skin.getTiledDrawable("pattern");
  7. Drawable drawable = skin.getDrawable("enemy");

These methods are identical to passing in the appropriate class, but allow for slightly more concise code.

Conversions

All styles for UI widgets use a when they need an image. This allows a texture region, ninepatch, sprite, etc to be used anywhere in the UI. Skin makes it easy to convert textures and texture regions to drawables and other types:

  1. Skin skin = new Skin();
  2. skin.add("logo", new Texture("logo.png"));
  3. ...
  4. Texture texture = skin.get("logo", Texture.class);
  5. TextureRegion region = skin.getRegion("logo");
  6. NinePatch patch = skin.getPatch("logo");
  7. Sprite sprite = skin.getSprite("logo");
  8. TiledDrawable tiled = skin.getTiledDrawable("logo");

A texture region can be retrieved as a ninepatch, sprite, tiled drawable, or drawable. The first time a conversion is made, a new object is allocated and stored in the skin. Subsequent retrievals will return the stored object.

Resources obtained from the skin are not new instances, the same object is returned each time. If the object is modified, the changes will be reflected throughout the application. If this is not desired, a copy of the object should be made.

The newDrawable method copies a drawable. The new drawable’s size information can be changed without affecting the original. The method can also tint a drawable.

Note the new drawable is not stored in the skin. To store it in the skin it must be explicitly added with a name like any other resource.

Widget styles

Skin is a useful container for providing texture regions and other resources that UI widgets need. It can also store the UI widget styles that define how widgets look.

  1. TextButtonStyle buttonStyle = skin.get("bigButton", TextButtonStyle.class);
  2. TextButton button = new TextButton("Click me!", buttonStyle);

All widgets have convenience methods for passing the skin and the style name:

  1. TextButton button = new TextButton("Click me!", skin, "bigButton");

If the style name is omitted, the name “default” is used:

  1. TextButton button = new TextButton("Click me!", skin);

A skin can be . Alternatively, JSON can be used to describe named objects in the skin. This makes it convenient to define the UI widget styles. Note the JSON does not describe texture regions, ninepatche splits, or other information which comes from the texture atlas. However, the JSON may reference the regions, ninepatches, and other resources in the skin by name. The JSON looks like this:

className is the fully qualified Java class name for the objects. name is the name of each resource. resource is the JSON for the actual resource object. The JSON corresponds exactly to the names of the fields in the resource’s class. Here is a real example:

  1. {
  2.     com.badlogic.gdx.graphics.Color: {
  3.         white: { r: 1, g: 1, b: 1, a: 1 },
  4.         red: { r: 1, g: 0, b: 0, a: 1 },
  5.         yellow: { r: 0.5, g: 0.5, b: 0, a: 1 }
  6.     },
  7.         medium: { file: medium.fnt }
  8.     },
  9.     com.badlogic.gdx.scenes.scene2d.ui.TextButton$TextButtonStyle: {
  10.         default: {
  11.             down: round-down, up: round,
  12.             font: medium, fontColor: white
  13.         },
  14.         toggle: {
  15.             down: round-down, up: round, checked: round-down,
  17.         },
  18.         green: {
  19.             down: round-down, up: round,
  20.             font: medium, fontColor: { r: 0, g: 1, b: 0, a: 1 }
  21.         }
  22.     }
  23. }

First, some colors and a font are defined. Next, some text button styles are defined. The fields down, up, and checked are of type Drawable. An object is expected but a string is found in the JSON, so the string is used as a name to look up the drawable in the skin. The same thing happens for the font and colors, except for the “green” text button style, which defines a new color inline.

Skin files from the can be used as a starting point: uiskin.png, uiskin.atlas, uiskin.json, and default.fnt.

Loading and configuring a freetype font via the skin json file requires some additional steps. Either use Scene Composer or a library like .

Colors are defined in JSON as shown above. If the r, g, or b properties are omitted, 0 is used. If a is omitted, 1 is used.

Alternatively, you can specify the color by hex value:

  1. com.badlogic.gdx.graphics.Color: {
  2.     skyblue: { hex: 489affff }
  3. }

A bitmap font is declared in the JSON like this:

  1. {
  2.     com.badlogic.gdx.graphics.g2d.BitmapFont: {
  3.         medium: { file: medium.fnt,
  4.                   scaledSize: -1, //integer height of capital letters, default -1 for unscaled
  5.                   markupEnabled: false,
  6.                   flip : false}

To find the font’s BMFont file, first the skin looks in the directory containing the skin file. If not found, it uses the specified path as an internal path.

To find the font’s image file, first the skin looks for a texture region with the same name as the font file, without the file extension. If not found, it will look in the directory containing the font file for an image with the same name as the font file, but with a “png” file extension.

It is very useful to tint regions various colors. For example, the regions for a white button can be tinted to have a button of any color. Drawables can be tinted in code using the newDrawable method. The Skin.TintedDrawable class provides a way to tint drawables in JSON:

This makes a copy of the drawable named “round”, tints it green, and adds it to the skin as a drawable under the name “round-green”.