How to skin JXClient — a butcher's guide

Overview

This file specifies the file format of JXClient's skin files. Skin files define the graphical user interface of JXClient.

The skin to use can be specified with the --skin command-line option:

    java -jar jxclient.jar --skin ragnorok

selects the "ragnorok" skin. Currently only two skins are built into jxclient.jar: "ragnorok" and "default;". "default" is used if no --skin option is given; it maps to "ragnorok".

The option --skin accepts either a built-in skin name or the name of a directory containing the skin definition. The latter alternative is useful when creating new skins: no need to recompile the client, just restart it. See the section about creating new skins.

Structure

Skin definition is split into multiple files which are stored in a common directory:

The global file is global.skin; it is always loaded. Other skin files are *.skin; the following files are always loaded and therefore must be defined by all skins:

If these skin files reference other dialogs using the DIALOG_OPEN, DIALOG_TOGGLE, or DIALOG_CLOSE commands, more .skin files may be needed.

Empty lines and lines starting with '#' are ignored within .skin files.

Concepts

Dialogs

A dialog consists of a set of GUI elements. Dialogs are used for:

Some dialogs are accessed by client code by name. These elements must have fixed names:

GUI Elements

A GUI element can be drawn on the screen. Some GUI elements allow user input (for example, buttons); others ignore user input (for example, pictures).

A GUI element may be visible or invisible. Only visible GUI elements are painted and may receive user input. The visibility can be changed executing the TOGGLE command.

Each GUI element has a name. The name must be unique within a dialog. The names are invisible to the user; they are used for referencing GUI elements within .skin files. For example: the skin command

    set_invisible magicmap

hides the GUI element "magicmap".

Some GUI elements are accessed by client code. These elements must have fixed names or fixed positions:

Command Lists

A command list is a list of one or more commands. Commands are skin-internal commands, not commands sent to a Crossfire server. Section command types defines possible commands.

Commands

Commands start with one or two keywords and optionally have arguments. Keywords and arguments are separated by spaces or TABs. Arguments may be quoted with " or ' characters to allow embedded spaces or TABs.

Some commands do not require quoting but combine multiple arguments into a single argument. These arguments are marked with a trailing "...", for example <text...>. These arguments support multi-line strings using following syntax:

    label_multi [...] <<EOF
    first line
    second line
    etc.
    EOF

add: add GUI element to dialog

syntax:

    add <name>

precondition: dialog

Adds the GUI element <name> to the dialog.

Using this command is optional: all GUI elements defined but not explicitly added are added implicitly after the last line of the dialog definition file just as if a add * command was present. Explicitly adding GUI elements allows to control the drawing order of GUI elements regardless of declaration order.

button: execute command on activation

syntax:

    button <name> <x> <y> <w> <h> <up> <down> <auto-repeat> <command-list>
    button <name> <x> <y> <w> <h> <up> <down> <auto-repeat> <command-list> <font> <color> <label-x> <label-y> <text...>

precondition: dialog

Defines a button element which executes the command-list <command-list> when activated. Activation is by mouse-click, the GUI_EXECUTE_ELEMENT command, or by pressing ENTER or SPACE in dialogs defining a default element.

The remaining arguments specify the text displayed in the command button. If omitted, only the <up> or <down> pictures are shown.

checkbox: toggle option

syntax:

    checkbox <name> <x> <y> <w> <h> <option> <text...>

precondition: dialog, def checkbox

Defines a checkbox element which displays the state of a configuration option which can be selected or unselected.

Options can be defined with def checkbox_option. The section about predefined options defines the options built into JXClient.

commandlist: define executable commands

syntax:

    commandlist <name> <type>
    commandlist <name> <type> <element> <command> <args>
    commandlist_add <name> <element> <command> <args>

Defines a named list of commands. Command lists are referenced by other GUI elements. The /exec <name> command executes a named command list.

If the following arguments are present in commandlist, a sub-command is created and added to the list. It is equivalent to a separate commandlist_add statement.

text, command_text, query_text: text input fields

syntax:

    text <name> <x> <y> <w> <h> <active-pic> <inactive-pic> <font> <active-color> <inactive-color> <margin> <command-list> <enable-history>
    command_text <name> <x> <y> <w> <h> <active-pic> <inactive-pic> <font> <active-color> <inactive-color> <margin> <enable-history>
    query_text <name> <x> <y> <w> <h> <active-pic> <inactive-pic> <font> <active-color> <inactive-color> <margin> <enable-history>

precondition: dialog

Defines a text input field. text executes a fixed command-list, command_text sends the entered text as an "ncom" command to the Crossfire server, query_text sends the entered text as a "reply" response to the Crossfire server.

def: define template information

syntax:

    def <type> <args>

The def command defines template information for use in other commands.

def checkbox: define layout of checkboxes

syntax:

    def checkbox <checked-pic> <unchecked-pic> <font> <color>

Defines layout information for rendering checkboxes.

def checkbox_option: define options

syntax:

    def checkbox_option <option-name> <command-on> <command-off> <description...>

Defines a new option. The <option-name> must be globally unique and must be different from predefined options.

def dialog: define layout of dialogs

syntax:

    def dialog <frame> <font> <color> <background-color> <alpha>

Defines layout information for rendering dialogs.

def item: define layout for items

syntax:

    def item <cursed> <damned> <magic> <blessed> <applied> <unidentified> <selector> <locked> <unpaid> <font> <color>

Defines layout for rendering items. Typically used in ground or inventory views.

def textbutton: define layout for text buttons

syntax:

    def textbutton <up-pic> <down-pic> <font> <color>

Defines layout for rendering text buttons.

dialog: group GUI elements

syntax:

    dialog <name> <x> <y> <w> <h> <save> <title...>

precondition: dialog, def dialog

Defines a group of GUI elements forming a dialog or screen.

dialog_hide: hide dialogs depending on state

syntax:

    dialog_hide <state...>

precondition: dialog

Hides this dialog in the given states.

dupgauge, duptextgauge, gauge, textgauge: graphically display a stat value

syntax:

    gauge <name> <x> <y> <w> <h> <pos-pic> <neg-pic> <empty-pic> <type> <orientation> <tooltip...>
    textgauge <name> <x> <y> <w> <h> <pos-pic> <neg-pic> <empty-pic> <type> <orientation> <color> <font> <tooltip>
    dupgauge <name> <x> <y> <w> <h> <pos-div-pic> <pos-mod-pic> <empty-pic> <type> <div-orientation> <mod-orientation> <tooltip...>
    duptextgauge <name> <x> <y> <w> <h> <pos-div-pic> <pos-mod-pic> <empty-pic> <type> <div-orientation> <mod-orientation> <color> <font> <tooltip...>

precondition: dialog

Defines a GUI element that graphically displays a stat value.

event: execute actions for events

syntax:

    event <type> <args>

Defines an action to be executed if an event occurs.

Ordering of init/connect/login events

The ordering of some events is: init (connect (login logout)* disconnect)*. This means:

event connect: connection to Crossfire server

syntax:

    event connect <command-list>

Executes <command-list> after a connection to a Crossfire server has been established.

event init: one-time initialization

syntax:

    event init <command-list>

Executes <command-list> once after the skin has been loaded.

event magicmap: magicmap message has been received

syntax:

    event magicmap <command-list>

Executes <command-list> after a magicmap message has been received from the Crossfire server.

event mapscroll: map view has scrolled

syntax:

    event mapscroll <command-list>

Executes <command-list> whenever the map view has scrolled.

event skill: skill has been learned or forgotten

syntax:

    event skill add <command-list>
    event skill del <command-list>

Executes <command-list> after the character has learned a new skill or after he has forgotten a skill.

After login, event skill add events are delivered for all skills known by the character. Just before logout, event skill del events are delivered for all skills known by the character.

font: define named font

syntax:

    font <name> <font> <size>

Declares a font to be used in GUI elements.

ignore: ignore GUI element for mouse interaction

syntax:

    ignore <name>

precondition: dialog

Ignores the named GUI element for mouse interaction. The GUI element is painted but otherwise ignored.

floor_list, inventory_list: display list of items

syntax:

    floor_list <name> <x> <y> <w> <h> <cell-size> <selected-item-name>
    inventory_list <name> <x> <y> <w> <h> <cell-size> <selected-item-name>

precondition: dialog, def item

Defines a list box showing items on the floor or in the character's inventory. The items are rendered using the options defined by a preceding def item command.

Note: if both set_num_look_objects and floor_list are used, set_num_look_objects takes precedence. Otherwise the number of items shown in the floor list is requested from the server; the value is re-negotiated if needed.

hide_input: instructs a text field to display entered text as *

syntax:

    hide_input <element>

precondition: dialog

The <element> must be a text element.

item: display items

syntax:

    item <type> <name> <x> <y> <w> <h> <index> <args>

precondition: dialog

Displays a single item.

item floor: display items on the floor

syntax:

    item floor <name> <x> <y> <w> <h> <index>

precondition: def item

item inventory: display items in the character's inventory

syntax:

    item inventory <name> <x> <y> <w> <h> <index>

precondition: def item

item shortcut: display shortcut commands

syntax:

    item shortcut <name> <x> <y> <w> <h> <index> <cast> <invoke> <font>

Displays a shortcut command. Shortcut commands can be activated by pressing Fx function keys.

item spelllist: display spells known to the character

syntax:

    item spelllist <name> <x> <y> <w> <h> <index> <selected>

Displays a spell known by the character.

key: define default key bindings

syntax:

    key char <code> <command-list>
    key code <code> <modifiers> <command-list>

Defines default key bindings. default key bindings can be defined in global.skin or within dialog .skin files. Definitions within dialogs are active only while the dialog is shown; global key bindings are always active.

Lookup of key bindings uses the following ordering. Further steps are not checked after a match was found. the following steps are executed for either code or har key bindings, depending on the key being pressed.

Note that some keys produce both char and code events. These keys are checked twice and thus may execute two command-lists.

label_*: display text label

syntax:

    label_html <name> <x> <y> <w> <h> <font> <color> <text...>
    label_multi <name> <x> <y> <w> <h> <font> <color> <text...>
    label_query <name> <x> <y> <w> <h> <font> <color>
    label_failure <name> <x> <y> <w> <h> <font> <color>
    label_message <name> <x> <y> <w> <h> <font> <color>
    label_text <name> <x> <y> <w> <h> <font> <color> <text...>
    label_stat <name> <x> <y> <w> <h> <font> <color> <stat> <alignment>
    label_stat2 <name> <x> <y> <w> <h> <font> <normal> <upgradable> <depleted> <boosted> <boosted+upgradable> <stat-curr> <stat-base> <stat-race> <stat-applied> <alignment>
    label_spell <name> <x> <y> <w> <h> <font> <type>

precondition: dialog

Defines a GUI element that displays a text label.

log_label: display last received message

syntax:

    log_label <name> <x> <y> <w> <h> <background-pic> <font-print> <font-fixed> <font-fixed+bold> <font-arcane> <default-color>

precondition: dialog

Defines a GUI element that displays the last received "drawinfo" or "drawextinfo" message.

log_message: display messages

syntax:

    log_message <name> <x> <y> <w> <h> <background-pic> <font-print> <font-fixed> <font-fixed+bold> <font-arcane> <default-color>

precondition: dialog

Defines a GUI element that displays received "drawinfo" or "drawextinfo" messages.

log_color: change color of log_message

syntax:

    log_color <name> <index> <color>

precondition: dialog

Changes a color of a log_message element.

log_filter: filter contents of log_message

syntax:

    log_filter <name> <which> <type...>

precondition: dialog

Specifies the message types to display in a log_message element.

Note: the command /debug_messages may be useful for choosing the right message types.

minimap: display map overview

syntax:

    minimap <name> <x> <y> <w> <h>

precondition: dialog

Defines a GUI element that displays a small map view. The map view may contain magicmap information.

map: display map view

syntax:

    map <name> <x> <y> <w> <h>

precondition: dialog

Defines a GUI element that displays a map view.

meta_list: display Crossfire server list

syntax:

    meta_list <name> <x> <y> <w> <h> <cell-width> <cell-height> <picture> <font> <text> <label> <connect> <format> <tooltip>

precondition: dialog

Defines a GUI element that displays available Crossfire servers.

character_list: display characters list for an account

syntax:

    character_list <name> <x> <y> <w> <h> <cell-width> <cell-height> <font>

precondition: dialog

Defines a GUI element that displays available characters for an account.

picture: display pictures

syntax:

    picture <name> <x> <y> <w> <h> <picture> <alpha>

precondition: dialog

Defines a GUI element that displays a static picture.

set_forced_active: force GUI elements to be active

syntax:

    set_force_active <name>

precondition: dialog

Defines a GUI element to be always active. It prevents other GUI elements from getting the keyboard focus.

set_auto_size: update dialog size after window resizes

syntax:

    set_auto_size

precondition: dialog

Recalculates the dialog's extent (location and size) whenever the main window's size changes. Auto-sizing dialogs cannot be moved manually.

set_default: define default GUI elements

syntax:

    set_default <name>

precondition: dialog

Marks a GUI element as the default element. The default element is activated by pressing ENTER or SPACE unless these keys are overridden by a key binding.

set_invisible: hide GUI elements

syntax:

    set_invisible <name>

precondition: dialog

Hides a GUI element by default: the GUI element is hidden when the skin is loaded. It can be made visible by executing SHOW or TOGGLE command lists.

set_modal: make dialogs modal

syntax:

    set_modal

precondition: dialog

Makes this dialog modal.

set_num_look_objects: request floor size from server

syntax:

    set_num_look_objects <n>

Requests a floor size from the Crossfire server. Overrides implicit definition by floor_list.

scrollbar: display scrollbars controlling other GUI elements

syntax:

    scrollbar <name> <x> <y> <w> <h> <proportional-slider> <element> <foreground> <background>

precondition: dialog

Defines a GUI element that displays a scrollbar.

skin_name: define general skin-related information

syntax:

    skin_name <name> <min-resolution> <max-resolution>

Sets general skin-related information.

textbutton: display buttons with a text labels

syntax:

    textbutton <name> <x> <y> <w> <h> <auto-repeat> <command-list> <text...>

precondition: dialog, def textbutton

Defines a GUI element that displays a button showing a text label.

tooltip: add tooltip labels

syntax:

    tooltip <font>

Adds a tooltip label to the skin. If this command is not used, no tooltips are shown.

Misc

Macros

Macros are placeholders within commands sent to the Crossfire server. The macros are replaced when the command is sent to the server.

Macros are supported in key bindings (/bind command) and within arguments of the GUI_EXECUTE_COMMAND command.

The following macros are supported:

Command Types

Command types are the types of commands allowed in command lists.

Stats

The following names for displaying stat values are supported:

Most constants correspond to the constants CS_STAT_xyz defined in the Crossfire server.

Options

Options are boolean valued settings. Options can be presented to the user with the checkbox command.

Skins can define options with the def checkbox_option. The following options are predefined:

These constants correspond to the constants PU_xyz defined in the Crossfire server.

Colors

Colors can be specified as:

Optionally a transparency specification may be appended: BLACK/0.5 for half-transparent BLACK or #FF0000/0.9 for slightly transparent red.

How to start hacking

Create new skin

To create a new skin called "rawhide", copy the default skin into the directory rawhide:

    svn export https://crossfire.svn.sourceforge.net/svnroot/crossfire/jxclient/trunk/skins/ragnorok rawhide

Modify the files rawhide/*. At least change

    skin_name ragnorok ...

to

    skin_name rawhide ...

in rawhide/global.skin.

Restart JXClient using the new skin:

    java -jar <optional path>jxclient.jar --skin rawhide

Optionally disable full-screen mode and force a small window size:

    java -jar <optional path>jxclient.jar --skin rawhide --no-full-screen --resolution 1024x768

Debugging the new skin

Add the command-line option --debug-gui to enable GUI related debug information:

Note: this option also works for built-in skins.

Add the command-line option --debug-keyboard keys.log to write debug information about pressed keys into keys.log. This information may help to define key bindings. "pressed" keys are matched by key code key bindings, "typed" keys are matched by key char key bindings.

For debugging log_color definitions, the command /debug_messages may be useful. It prints text using all possible color codes or message types.