Difference between revisions of "GUI Themes/Specs"

From ScummVM :: Wiki
Jump to navigation Jump to search
(→‎Disabling Widgets: -- proper section title)
Line 1: Line 1:
See [[GUI Themes/TODO|GUI TODO]].
Since the merge of the new GUI into the ScummVM trunk, all documentation regarding the legacy GUI is now obsolete. Hence, this page has been updated with the details of the new Theme format.


== GUI Themes config file format ==
=== Theme Packages ===


=== Overview ===
A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information


We always have a built-in theme. It is used when there is no external .ini file. For simplicity it uses exactly same format as external .ini but is defined in Theme::_defaultConfigINI string in gui/theme-config.cpp file.
* One or more STX (ScummVM Theme XML) files.
* Any external Bitmap fonts.
* Any external Bitmap images.
* A <tt>THEMERC</tt> file.
===== The STX Files =====


Config file consists of at least one section. These sections can override one another. This is used to make a slight alteration of base theme possible without duplicating all element whose position is not changed.
STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.


'''NOTE: if you want to add new widgets, pay attention to correspondent section [[#What_to_do_if_I_need_to_add_new_widgets_to_GUI|below]]'''
The chosen syntax of this format is a basic subset of XML, the one which the embedded XML parser supports. Please refer to the parser documentation for its technical specifications.


=== Section names ===
Throughout the STX files, every single property of the theme's appearance and layout is defined: Although all this information can easily be stored in a single file, the theme engine conveniently allows to split the different sections of the Theme Description in one or more files.
They are defined with this regexp: (X|[0-9]+)x(Y|[0-9+]+). I.e. possible names are:
* [XxY] -- universal one which can be used for any resolution
* [640xY] -- could be used for 640x400 and 640x480
* [Xx400] -- could be used for 640x400 only (or any other resolution with height 400)
* [640x480] -- could be used for 640x480 only


=== Expressions ===
Any <tt>*.stx</tt> files contained inside the theme package will be automatically loaded and parsed. The content of such files must obviously adhere to the STX syntax which you can find in this document.
To add most flexibility arbitrary arithmetic expressions can be used for specifying any element. Allowed operations are '(', ')', '+', '-', '*', '/'. unary '+' and unary '-'. Atoms are either number or symbolic names.


=== Built-in Constants ===
===== The external resources =====
Currently there are these built-in constants defined:


* kButtonWidth
Together with the STX files, external resources for the theme may be optionally bundled. The most usual resources are bitmaps to use in the Graphical User Interface and Bitmap fonts.
* kButtonHeight
* kSliderWidth
* kSliderHeight
* kBigButtonWidth
* kBigButtonHeight
* kBigSliderWidth
* kBigSliderHeight
* kTextAlignLeft
* kTextAlignCenter
* kTextAlignRight
* kFontStyleBold
* kFontStyleNormal
* kFontStyleItalic
* kFontStyleFixedBold
* kFontStyleFixedNormal
* kFontStyleFixedItalic


These correspond to constants defined in gui/widget.h file. There is no restriction on constants names.
Packaged resources will then be accessible from the STX syntax (check the <tt>font</tt> and <tt>bitmap</tt> keys in the STX documentation).


* kThumbnailWidth -- defined in graphics/scaler.h
===== The <tt>THEMERC</tt> file =====
* false = 0
* true = 1


=== Built-in Variables ===
ScummVM themes '''must''' also contain a simple <tt>THEMERC</tt> file stating the theme's version, name and author. The <tt>THEMERC</tt> file is a simple text file with the following syntax:
Built-in variables are symbolic names for ScummVM variables whose value is determined at run-time. These are:


* w -- current GUI width
<pre>[SCUMMVM_THEME_V23:Name of the ScummVM Theme:Name of the Author]</pre>
* h -- current GUI height
The <tt>SCUMMVM_THEME_V23</tt> is just a simple check to make sure that the theme was developed to be used on the proper version of the GUI. Note that the <tt>THEMERC</tt> file is not optional, as it is used by the Theme engine to check that the Theme package is indeed valid and specifies the Name and Author fields that will be shown on the GUI.


=== Defining widget positions ===
===== Building theme packages =====
Widgets are specified by following construction:


  widget_name=X Y [W H]
Building a ScummVM Theme Package is as easy as dragging your STX files, bitmaps, resources and <tt>THEMERC</tt> files into your favorite archiver application and creating a zip file. However, to make the development process easier, a Python script called <tt>scummtheme.py</tt> has been included in the <tt>gui/themes/</tt> folder of the SVN repository.


X, Y, W and H are whitespace-delimited expressions.
When ran with the <tt>makeall</tt> argument, the script will automatically parse all the theme folders in the Theme directory and build their ZIP files. It can be also used to build a single theme by passing it the <tt>make [themename]</tt> argument, where <tt>[themename]</tt> is the name of the folder containing the theme to be built.
W and H are optional.


This construct effectively defines
This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.


* widget_name.x
===== Building the built-in theme =====
* widget_name.y
* widget_name.w
* widget_name.h


If W and H are present, also these get defined:
The Graphical User Interface must contain a built-in theme to use a fall-back when no other custom themes can be loaded. The built-in theme must be built manually with the <tt>scummtheme.py</tt> script, by passing it the <tt>default [themename]</tt> argument.


* widget_name.x2 = widget_name.x + widget_name.w
The Python script will then parse the supplied theme's STX files into a single <tt>*.inc</tt> file; this file is automatically built together with the ScummVM executable file when building the ScummVM source code, and will be used as the default built-in theme.
* widget_name.y2 = widget_name.y + widget_name.h


Example:
Note that because only STX files are embedded in the source code, the theme which is converted into a built-in theme '''cannot''' contain Bitmaps or any other external resources.


  chooser_headline=10 6 (w - 2 * 16) (kLineHeight)
By default, the <tt>ScummVM Classic Theme</tt> is the built-in theme.


=== Widget properties ===
=== Drawing specifications ===
Above mentioned constructions with dots are called widget properties.


Example:
The process of rendering a widget on the screen is discretized into several phases called ''drawing steps''. A set of such steps, which generate a basic widget shape on screen is called a Draw Data set. The GUI Engine loads all the different data sets for a given widget and takes care of rendering it into the screen based on its current state.


  chooser_list.x
For example, the basic Button widget may be composed of several sets of data: Drawing data for the button's idle state, drawing data for when the button is hovered and drawing data for when the button is pressed.


Also there are following additional widget properties:
The functionality of each set of Drawing Data is hard-coded into the Graphical User Interface; the most up to date version of all the drawing sets may be found extensively commented in the <tt>&quot;gui/ThemeRenderer.h&quot;</tt> file, in the <tt>DrawData</tt> enumeration inside the <tt>ThemeRenderer</tt> class.


* .visible -- if set to 0, then widget is not drawn
In order to successfully parse and load a custom theme definition, the whole list of Draw Data sets is not required to be defined in a theme description, but failing to declare all of them will make the parser complain and obviously several GUI elements will be missing.
* .enable -- if set to 0, then widget is disabled
* .align -- for text widgets defines text alignment (kTextAlignLeft, kTextAlignRight or kTextAlignCenter). Default is kTextAlignLeft


=== Widget class properties ===
=== Theme Layout specifications ===
Each widget class can be customized per-resolution. You need to specify their special properties.


==== ListWidget ====
The actual positioning and layout of widgets and dialogs on the graphical user interface is defined from the <tt>Layout</tt> section of the STX file. This new Graphical User Interface using a Flowing Layouts system which greatly differs from the old coordinate and arithmetic based implementation.
This is widget with list of selectable items
ListWidget.leftPadding=7                                                     
ListWidget.rightPadding=7                                                     
ListWidget.topPadding=5                                                       
ListWidget.bottomPadding=5                                                   
ListWidget.hlLeftPadding=0                                                   
ListWidget.hlRightPadding=0                                                   


''leftPadding'', ''rightPadding'', ''topPadding'' and ''bottomPadding'' specify list contents (text) padding from widget edges. Default values are 0.
The best way to learn about the new Layout system is to read the documentation on the <tt>layout</tt> key and its children, and to read the example Layout Design section, which provides a detailed overview into the steps required to design the layout of a dialog.


''hlLeftPadding'', ''hlRightPadding'' specify padding of selected text highlight, i.e. green bar in ''modern'' theme. Default values are 0.
=== Syntax overview ===


==== PopUpWidget ====
A full STX theme description is composed of:
This is drop-down list used to select one item out of several. In inactive state it displays only selected item.
PopUpWidget.leftPadding=7                                                     
PopUpWidget.rightPadding=5
PopUpWidget.labelSpacing=3


''leftPadding'' and ''rightPadding'' specify list contents (text) padding from widget endges. Default values are 0.
* A root <tt>&lt;render_info&gt;</tt> key, containing all the information regarding the looks of the theme.
** An optional <tt>&lt;palette&gt;</tt> key, containing color definitions.
** An optional <tt>&lt;bitmaps&gt;</tt> key, containing all the loaded bitmaps which will be used on the GUI.
** A <tt>&lt;fonts&gt;</tt> key, specifying the fonts used to draw text on the GUI.
** A <tt>&lt;drawdata&gt;</tt> key for ''each'' DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.
* A root &lt;layout_info&gt; key, containing all the information regarding the layout of the theme.
** A <tt>&lt;globals&gt;</tt> key, containing the global variables to use on the layout design.
** A <tt>&lt;dialog&gt;</tt> key for ''each'' dialog in the GUI, specifying the layout and position of the dialog and all its children widgets.
Here's a schematic overview of the layout of keys in a STX file:


''labelSpacing'' is used to specify space between text label and widget itself.
<pre>&lt;render_info&gt;
    &lt;palette&gt;
        ...
    &lt;/palette&gt;


==== EditTextWidget ====
    &lt;bitmaps&gt;
This is editable text.
        ...
EditTextWidget.leftPadding=7                                                     
    &lt;/bitmaps&gt;
EditTextWidget.rightPadding=5
EditTextWidget.font=kFontStyleNormal


''leftPadding'' and ''rightPadding'' specify list contents (text) padding from widget endges. Default values are 0.
    &lt;fonts&gt;
        ...
    &lt;/fonts&gt;


''font'' is used to specify font used by the widget.
    &lt;drawdata&gt;
        ...
    &lt;/drawdata&gt;


==== Console ====
    ...
This is our debug console
&lt;/render_info&gt;
Console.font=kFontStyleFixedNormal
Console.leftPadding=7
Console.rightPadding=5
Console.topPadding=5
Console.bottomPadding=5


''font'' is used to specify font for console. Note, that console uses fixed font.
&lt;layout_info&gt;
    &lt;globals&gt;
        ...
    &lt;/globals&gt;


''leftPadding'', ''rightPadding'', ''topPadding'' and ''bottomPadding'' specify console contents (text) padding from widget edges. Default values are 0.
    &lt;dialog&gt;
        ...
    &lt;/dialog&gt;


    ...
&lt;/layout_info&gt;</pre>
The best place to start writing a full theme description is taking a look at the already written themes in the <tt>gui/themes/</tt> directory of the Subversion repository, while consulting the following documentation for each specific key:


=== Special variables ===
=== Detailed STX documentation ===
Special variables are:


* self
The full documentation of the XML syntax used in the new Graphical User Interface can be found on its own [[GUI Themes/STX|wiki page]].
* prev


It is reference to current and last defined widget special variables respectively, i.e. .x, .y, .w and .h
=== Resolution-dependent keys and layouts ===


Example:
Several keys in the STX syntax support the <tt>resolution</tt> property, which allows to load or skip the key and all its children when loading the theme on a given resolution.


  chooser_list=10 (6 + kLineHeight + 2) (w - 2 * 16) (h - self.y - buttonHeight - 12)
The resolution property must contain one or more resolutions, comma separated, for which the given key is supposed to be loaded. Resolutions preceded by the minus sign will block the key from being loaded in that resolution, while resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples:


Denote self.y which equals to computed value of (6 + kLineHeight + 2).
<pre>/* Key will be loaded in all resolutions */
&lt;render_info&gt;


You cannot use these references forward, i.e. refer to .w in .x. They get defined from left to right.
/* Key will ONLY be loaded in resolutions with 320 width */
&lt;render_info resolution = '320xY'&gt;


=== Defining variables ===
/* Key will ONLY be loaded in resolutions with 240 height and in the 320x200 resolution */
&lt;render_info resolution = 'Xx240, 320x200'&gt;


Example:
/* Key will be loaded on ALL resolutions except for 320x200 */
&lt;render_info resolution = '-320x200'&gt;


  def_kLineHeight=16 * 2
/* Key will ONLY be loaded in resolutions with 320 width; the -240xY is superfluous. */
  OneThirdWidth=(w / 3)
&lt;render_info resolution = '320xY, -240xY'&gt;</pre>
Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition:


variable kLineHeight gets value 32. OneThirdWidth will be GUI width divided by 3. Note use of parens in last example. Definitions with 'def_' prefix have a special meaning and get skipped with USE keyword (see below).
<pre>&lt;def var = 'TestVar' value = '100'/&gt;
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre>
won't fail to parse. What will happen when loading the theme using a resolution with 320 width is that <tt>TestVal</tt> first will be assigned the <tt>100</tt> value, and then it will be overwritten with the <tt>200</tt> value. On the other hand, when loading the theme using a resolution ''without'' a with of 320, the <tt>ThemeVal</tt> will be assigned the <tt>100</tt> value and the second key will be plain ignored.


=== Defining aliases ===
The &quot;proper&quot; way to do that multi-resolution assignment would obviously be:
You can define alias to any symbolic atom, i.e. constants, variables and widget properties.


Example:
<pre>&lt;def var = 'TestVar' value = '100' resolution = '-320xY'/&gt;
 
&lt;def var = 'TestVar' value = '200' resolution = '320xY'/&gt;</pre>
  set_headerBottomX=headline.x2
This way keys are only parsed on the resolution they are used in, but the result will be '''exactly the same''': Most of the time it's just cleaner to avoid using <tt>-320xY</tt> resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the '320xY' tag.
 
Now you can use headerBottomX everywhere.
 
=== Special alias ===
 
  set_parent=chooser_list
 
It sets 6 aliases for each widget property, i.e.
 
* parent.x = chooser_list.x
* parent.y = chooser_list.y
 
etc for .w, .h, .x2 and .y2
 
Example:
 
  set_parent=tabMidi
  midi_checkbox=(parent.x + 10) (parent.y + 20)
  roland_checkbox=midi_checkbox.x (parent.y + 50)
 
=== USE keyword ===
You can request loading of some particular section at any time within another section. But all variable definitions with def_ prefix get skipped. If you want to define a variable, use plain VAR=VAL construction.
 
Example:
 
  [640xY]
  def_buttonHeight=kBigButtonHeight
  def_kLineHeight=16
  listW=(w - 2 * 16)
  chooser_headline=10 6 listW (kLineHeight)
  chooser_list=10 (6 + kLineHeight + 2) listW (h - self.y - buttonHeight - 12)
 
  [320xY]
  def_buttonHeight=kButtonHeight
  def_kLineHeight=9
  use=640xY
 
In this example for 320xY resolution chooser_headline and chooser_list will be loaded from [640xY] section, though buttonHeight and kLineHeight will be different. listW will get the value.
 
=== USEASIS keyword ===
Same as USE keyword above but without def_ valuse skipped. Used for weird resolution aliases.
 
Example:
 
  # MM NES resolution
  [256x240]
  useAsIs=320xY
 
=== USEWITHPREFIX keyword ===
This keyword is similiar to above described USE keyword. The difference is that all defined widgetset will get specified prefix. Example:
 
  [XxY]
  yoffset=10
  useWithPrefix=audioControls global_
  yoffset=50
  useWithPrefix=audioControls game_
 
  [audioControls]
  myx=10
  myw=(options_dialog.w - 20)
  midipopup=(myx -5) yoffset (myw + 5)
 
Here you will get global_midipopup and game_midipopup widgets defined.
 
=== skipFor keyword ===
If this key is defined within section, then section loading will be skipped for specified resolutions. For example, it is used in our modern theme to make 320xY widgets be positioned like in our classic theme.
 
  [XxY]
  skipFor=320xY,256x240
  def_blah=22
 
In above case section [XxY] will not be loaded for 320x200, 320x240 or 256x240 resolutions. No spaces are allowed in specified value, only [0-9XxYx,]
 
=== Modern Theme configuration ===
 
==== 'pixmaps' section ====
 
In the 'pixmaps' section all pixmaps used by the renderer are defined.
 
Basically there are four pixmaps per widget/dialog type:
 
* "pix_typename_corner" defines the pixmap used for rendering all the corners.The pixmap should show the upper left corner and is x/y flipped if needed.
* "pix_typename_top" defines the pixmap used for the top/bottom border. The pixmap should show the top border and is y flipped if it draws the bottom border.
* "pix_typename_left" defines the pixmap used for the left/right border. The pixmap should show the left border and is x flipped if it draws the right border.
* "pix_typename_bkgd" defines the pixmap used for the background.
 
Here's some example to defined the pixmaps used for dialog drawing:
 
pix_dialog_corner="dialog_bkgd_corner.bmp"
pix_dialog_top="dialog_bkgd_top.bmp"
pix_dialog_left="dialog_bkgd_left.bmp"
pix_dialog_bkgd="dialog_bkgd.bmp"
 
If you want to find out about all definable pixmaps look at our default theme config file, named "modern.ini".
Also note that only .bmp files with a bpp of 24 bits are supported.
The transparency color used is defined in the 'colors' section (see later on).
 
Apart from the widget pixmaps definitions in the 'pixmaps' section there are
some special pixmaps defined:
 
* "pix_widget_arrow" defines the pixmap used for all arrows in widgets (like in the scrollbar widget). It should be an image of an arrow pointing upwards, and is y flipped if an arrow pointing downwards is drawn.
* "pix_checkbox_empty" defines the pixmap used for empty checkboxes.
* "pix_checkbox_checked" defines the pixmap used for checked checkboxes.
* "pix_theme_logo" defines the pixmap used as logo.
* "pix_cursor_image" defines the pixmap used as mouse cursor. Note that just the first 255 colors found are used.
 
==== 'colors' section ====
 
In the "colors" section colors for the whole theme are specified.
A color gets defined in this way:
name=R G B
with values from 0 to 255 for R, G and B.
 
 
There is a special color entry to define the transparent color for the pixmaps, named "color_transparency". Our default theme uses pink (255 0 255) as the transparent color.
color_transparency=255 0 255
 
 
To set up text colors the following entries have to be set:
color_state_disabled=192 192 192
color_state_highlight=100 162 8
color_state_enabled=0 0 0
*"color_state_disabled" is used for disabled text.
*"color_state_highlight" is used for highlighted text.
*"color_state_enabled" is used for normal text.
 
The ListWidget uses two special text color entries:
text_inverted_background=100 162 8
text_inverted_color=0 0 0
There "text_inverted_background" is used for the rect which is drawn when an entry is selected, "text_inverted_color" is used for the text drawn when an entry is selected.
 
 
Another special color is used for all kinds of text input widgets:
caret_color=0 0 0
This value is used for the color the caret is drawn in.
 
 
Some colors are used for background fades, you can easily spot them since they have a '_start' and '_end' suffix.
Another example:
main_dialog_start=210 114 10
main_dialog_end=239 196 24
This defines the color fade for the launcher background. "main_dialog_start" defines the color at the top of the drawn area, "main_dialog_end" at the bottom of the drawn area, the colors in between are calculated. (see 'gradients' section
for more information).
 
 
Sometimes there is more than one color fade definition for a widget, the button
widget uses for example one colorfade for normal drawing and a special fade for highlighted
drawing. Example:
button_bkgd_start=203 126 107
button_bkgd_end=169 42 12
button_bkgd_highlight_start=255 210 200
button_bkgd_highlight_end=200 70 50
*"button_bkgd_start" and "button_bkgd_end" are used for normal drawing.
*"button_bkgd_highlight_start" and "button_bkgd_highlight_end" are used for highlighted drawing.
 
 
There are three special entries for the button widget to define the text color:
button_text_enabled=255 255 255
button_text_disabled=192 192 192
button_text_highlight=255 214 84
*"button_text_enabled" is used for normal buttons.
*"button_text_disabled" is used for buttons which are currently disabled.
*"button_text_highlight" is used for highlighted buttons.
 
If you want to find out all defineable colors look at our default theme config file, named "modern.ini".
 
==== 'gradients' section ====
 
In the 'gradients' section the gradient factors for the different widget/dialog types are defined.
 
Some example define:
 
gradient_dialog_main=1
 
Which is for the background of the launcher dialog. If you want to find out about all definable gradients look at our default theme config file, named "modern.ini".
 
To see what this value does here's how the calculate the color of a row in a widget/dialog:
 
calcGradient(firstLineColor, lastLineColor, currentLine, maxLineNumber, factor)
      currentLine = currentLine * factor
      if currentLine >= maxLineNumber then
          return lastLineColor
      return firstLineColor + (lastLineColor - firstLineColor) * currentLine / maxLineNumber
 
As you can see we're using a linear interpolation here. Since it's pseudocode it's a bit simplified though, but it should be enough to get the basic idea.
 
===== Examples =====
 
To have some examples showing in how far a different factor value changes the colors here are coming two.
 
The color values we use in our examples:
 
{|
| bgcolor="#D2720A" | firstLineColor=210 114 10
|-
| bgcolor="#EFC418" | lastLineColor=239 196 24
|}
 
The following shows the difference between a factor value of 1 and 2 over 10 lines:
 
{| cellspacing="0" cellpadding="2"
| Factor 1
|&nbsp;
| Factor 2
|-
| bgcolor="#D2720A" | line0=210 114 10
|
| bgcolor="#D2720A" | line0=210 114 10
|-
| bgcolor="#D57B0B" | line1=213 123 11
|
| bgcolor="#D8840D" | line1=216 132 13
|-
| bgcolor="#D8840D" | line2=216 132 13
|
| bgcolor="#DE9610" | line2=222 150 16
|-
| bgcolor="#DB8D0E" | line3=219 141 14
|
| bgcolor="#E5A813" | line3=229 168 19
|-
| bgcolor="#DE9610" | line4=222 150 16
|
| bgcolor="#EBBA16" | line4=235 186 22
|-
| bgcolor="#E29F11" | line5=226 159 17
|
| bgcolor="#EFC418" | line5=239 196 24
|-
| bgcolor="#E5A813" | line6=229 168 19
|
| bgcolor="#EFC418" | line6=239 196 24
|-
| bgcolor="#E8B114" | line7=232 177 20
|
| bgcolor="#EFC418" | line7=239 196 24
|-
| bgcolor="#EBBA16" | line8=235 186 22
|
| bgcolor="#EFC418" | line8=239 196 24
|-
| bgcolor="#EFC418" | line9=239 196 24
|
| bgcolor="#EFC418" | line9=239 196 24
|}
 
==== 'extra' section ====
 
===== Shadows =====
Shadows are defined in number of extra pixels at each side. However, each widget uses its own shadow format. Currently it is hardcoded, but if there is a need, it could be easily added to the theme config.
 
  [extra]
  shadow_left_width=2
  shadow_right_width=4
  shadow_top_height=2
  shadow_bottom_height=4
 
Specifies number of extra pixels which shadow covers. This is right-bottom shadow.
 
===== Fonts =====
Fonts used in the theme could also be specified. You should provide the font file in BDF format and put it to the theme archive.
 
  [extra]
  fontfile_normal="helvr12-l1.bdf"
  fontfile_bold="helvb12-l1,bdf"
  fontfile_italic="helvi12-l1.bdf"
  fontfile_fixed_normal="courr12-l1.bdf"
  fontfile_fixed_bold="courb12-l1.bdf"
  fontfile_fixed_italic="couri12-l1.bdf"
 
Specifies fonts for Variable Normal, Bold and Italic weight, as well as fixed width fonts.
 
At first load ScummVM will load BDF fonts which are in slow ASCII format and will write binary precompiled versions to files with extencion 'FCC'. You may consider putting these files to theme ZIP file if you will want to distribute your theme.
 
===== Inactive dialog effects =====
For using an effect change the "inactive_dialog_shading" option in the "[extra]" section of default-theme.ini.
Possible values are: "no_effect", "luminance" and "dim". (Note that currently backends which don't copy
the game screen into the overlay buffer should use "no_effect").
 
* "luminance" will change all inactive screen areas to black and white.
** Example (enables it)
 
  [extra]
  inactive_dialog_shading=luminance
 
* "dim" will dim the screen with the given percentage value.
** "shading_dim_percent" in the "[extra]" section sets the dimming value. 0 means no dim, 100 is completeley black
** Example (30% screen dim):
 
  [extra]
  inactive_dialog_shading=dim
  shading_dim_percent=30
 
===== Cursor parameters =====
Cursors are specified in cursor pixmap (see pixmpas section). Section extra specifies several additional parameters:
 
  [extra]
  cursor_hotspot_x=0
  cursor_hotspot_y=0
  cursor_targetScale=3
 
First two parameters define position of cursor hotspot within cursor pixmap (top left corner is [0,0]).
 
targetScale is used to specify at which scale cursor starts to be scaled. I.e. if targetScale = 2, then cursor will not be scaled at 320xY, but will be scaled 1.5x for 960xY resolution (by factor of [currentScale / cursorTargetScale]. With targetScale = 3 it will not  be scaled even at 3x.
 
It is used when your cursor is designed, say, for 640x480, and original interpretator always scaled 320x200 game graphics.
 
== Evaluation precedence ==
Within one section everything is computed left to right, down to top. No forward references are allowed. The only exception are aliases which can refer to not yet defined variables and widget properties, but at time of useage those variables should be defined (otherwise you will get an error).
 
Currently any error in evaluation will lead to error() and ScummVM will be closed. So be careful, especially with the built-in theme.
 
On each resolution change all user-defined variables and aliases get cleared and all sections are recomputed. When sections get loaded for a single resolution, all of them are kept, so you can specify a generic [XxY] scheme and then overwrite only some widgets, thus simplifying the whole thing.
 
Sections loading order is always the same. For the 640x480 resolution this is:
 
# Built-in theme
## [XxY]
## [640xY]
## [Xx480]
## [640x480]
# Custom theme
## [XxY]
## [640xY]
## [Xx480]
## [640x480]
 
Only present sections are loaded. If a section is not defined no error message is generated.
 
== Backend-specific theme additions ==
Backends may specify their own theme additions. This is especially useful on platforms that lack certain features and can be used without modifying the main theme configuration.
 
The function in the base OSystem is <tt>Common::String getExtraThemeConfig();</tt> and it can be used as such:
 
<pre>
Common::String OSystem_SDL::getExtraThemeConfig() {
        Common::String myConfigINI(""
          "[XxY]\n"
          "mcFontButton.enabled=false\n"
          "mcFontPath.enabled=false\n"
          "mcFontClearButton.enabled=false\n"
          );
        return myConfigINI;
}
</pre>
 
This code would disable those three widgets. The string will be treated like a separate configuration, so you would have to specify resolution sections in there.
 
== Widget name conventions ==
 
Widget names are given in the following form:
 
  dialog_widget
 
where dialog_ is the dialog name, and widget is a distinguishable name within that dialog. Be discreet and give meaningful names.
 
Example:
 
  chooser_headline
  chooser_list
 
== What to do if I need to add new widgets to GUI ==
 
Most importantly, not all GUI behaviour is described in theme config. You can only alter the look, not the feel. So all real coding should go into the corresponding files in the gui/ directory.
 
When you add a new widget, follow this checklist before committing:
 
* Does it look right in 320xY (./scummvm --force-1x-overlay)
** To do this you should either have no absolute positions in your config file or create [320xY] section
* Does it look right with classic theme (./scummvm --gui-theme=classic)
** that is the [XxY] section in gui/theme-config.cpp
* Does it look right <u>both</u> with classic theme and 320xY resolution (./scummvm --force-1x-overlay --gui-theme=classic)
** that is the [320xY] section in gui/theme-config.cpp
 
Currently the classic theme has the following most notable differences from the modern theme:
 
* Line spacing is narrower everywhere
* Indentation is smaller in most cases apart from the Game Options dialog

Revision as of 12:07, 15 October 2008

Since the merge of the new GUI into the ScummVM trunk, all documentation regarding the legacy GUI is now obsolete. Hence, this page has been updated with the details of the new Theme format.

Theme Packages

A theme file in the new version of the ScummVM GUI is a compressed ZIP file which contains all the required information

  • One or more STX (ScummVM Theme XML) files.
  • Any external Bitmap fonts.
  • Any external Bitmap images.
  • A THEMERC file.
The STX Files

STX (ScummVM Theme XML) is the new format for theme descriptions on the Graphical User Interface of ScummVM.

The chosen syntax of this format is a basic subset of XML, the one which the embedded XML parser supports. Please refer to the parser documentation for its technical specifications.

Throughout the STX files, every single property of the theme's appearance and layout is defined: Although all this information can easily be stored in a single file, the theme engine conveniently allows to split the different sections of the Theme Description in one or more files.

Any *.stx files contained inside the theme package will be automatically loaded and parsed. The content of such files must obviously adhere to the STX syntax which you can find in this document.

The external resources

Together with the STX files, external resources for the theme may be optionally bundled. The most usual resources are bitmaps to use in the Graphical User Interface and Bitmap fonts.

Packaged resources will then be accessible from the STX syntax (check the font and bitmap keys in the STX documentation).

The THEMERC file

ScummVM themes must also contain a simple THEMERC file stating the theme's version, name and author. The THEMERC file is a simple text file with the following syntax: 

[SCUMMVM_THEME_V23:Name of the ScummVM Theme:Name of the Author]

The SCUMMVM_THEME_V23 is just a simple check to make sure that the theme was developed to be used on the proper version of the GUI. Note that the THEMERC file is not optional, as it is used by the Theme engine to check that the Theme package is indeed valid and specifies the Name and Author fields that will be shown on the GUI.

Building theme packages

Building a ScummVM Theme Package is as easy as dragging your STX files, bitmaps, resources and THEMERC files into your favorite archiver application and creating a zip file. However, to make the development process easier, a Python script called scummtheme.py has been included in the gui/themes/ folder of the SVN repository.

When ran with the makeall argument, the script will automatically parse all the theme folders in the Theme directory and build their ZIP files. It can be also used to build a single theme by passing it the make [themename] argument, where [themename] is the name of the folder containing the theme to be built.

This Python script is totally standalone and doesn't require external ZIP utilities, only a standard Python distribution.

Building the built-in theme

The Graphical User Interface must contain a built-in theme to use a fall-back when no other custom themes can be loaded. The built-in theme must be built manually with the scummtheme.py script, by passing it the default [themename] argument.

The Python script will then parse the supplied theme's STX files into a single *.inc file; this file is automatically built together with the ScummVM executable file when building the ScummVM source code, and will be used as the default built-in theme.

Note that because only STX files are embedded in the source code, the theme which is converted into a built-in theme cannot contain Bitmaps or any other external resources.

By default, the ScummVM Classic Theme is the built-in theme.

Drawing specifications

The process of rendering a widget on the screen is discretized into several phases called drawing steps. A set of such steps, which generate a basic widget shape on screen is called a Draw Data set. The GUI Engine loads all the different data sets for a given widget and takes care of rendering it into the screen based on its current state.

For example, the basic Button widget may be composed of several sets of data: Drawing data for the button's idle state, drawing data for when the button is hovered and drawing data for when the button is pressed.

The functionality of each set of Drawing Data is hard-coded into the Graphical User Interface; the most up to date version of all the drawing sets may be found extensively commented in the "gui/ThemeRenderer.h" file, in the DrawData enumeration inside the ThemeRenderer class.

In order to successfully parse and load a custom theme definition, the whole list of Draw Data sets is not required to be defined in a theme description, but failing to declare all of them will make the parser complain and obviously several GUI elements will be missing.

Theme Layout specifications

The actual positioning and layout of widgets and dialogs on the graphical user interface is defined from the Layout section of the STX file. This new Graphical User Interface using a Flowing Layouts system which greatly differs from the old coordinate and arithmetic based implementation.

The best way to learn about the new Layout system is to read the documentation on the layout key and its children, and to read the example Layout Design section, which provides a detailed overview into the steps required to design the layout of a dialog.

Syntax overview

A full STX theme description is composed of:

  • A root <render_info> key, containing all the information regarding the looks of the theme.
    • An optional <palette> key, containing color definitions.
    • An optional <bitmaps> key, containing all the loaded bitmaps which will be used on the GUI.
    • A <fonts> key, specifying the fonts used to draw text on the GUI.
    • A <drawdata> key for each DrawData identifier of the Theme Engine, specifying how is each individual widget drawn.
  • A root <layout_info> key, containing all the information regarding the layout of the theme.
    • A <globals> key, containing the global variables to use on the layout design.
    • A <dialog> key for each dialog in the GUI, specifying the layout and position of the dialog and all its children widgets.

Here's a schematic overview of the layout of keys in a STX file: 

<render_info>
    <palette>
        ...
    </palette>

    <bitmaps>
        ...
    </bitmaps>

    <fonts>
        ...
    </fonts>

    <drawdata>
        ...
    </drawdata>

    ...
</render_info>

<layout_info>
    <globals>
        ...
    </globals>

    <dialog>
        ...
    </dialog>

    ...
</layout_info>

The best place to start writing a full theme description is taking a look at the already written themes in the gui/themes/ directory of the Subversion repository, while consulting the following documentation for each specific key:

Detailed STX documentation

The full documentation of the XML syntax used in the new Graphical User Interface can be found on its own wiki page.

Resolution-dependent keys and layouts

Several keys in the STX syntax support the resolution property, which allows to load or skip the key and all its children when loading the theme on a given resolution.

The resolution property must contain one or more resolutions, comma separated, for which the given key is supposed to be loaded. Resolutions preceded by the minus sign will block the key from being loaded in that resolution, while resolutions without any modifiers will force the theme to be loaded in all resolutions. Here are a few examples: 

/* Key will be loaded in all resolutions */
<render_info>

/* Key will ONLY be loaded in resolutions with 320 width */
<render_info resolution = '320xY'>

/* Key will ONLY be loaded in resolutions with 240 height and in the 320x200 resolution */
<render_info resolution = 'Xx240, 320x200'>

/* Key will be loaded on ALL resolutions except for 320x200 */
<render_info resolution = '-320x200'>

/* Key will ONLY be loaded in resolutions with 320 width; the -240xY is superfluous. */
<render_info resolution = '320xY, -240xY'>

Note that the Theme Parser does not assert on repeated keys or values, it just replaces them accordingly. For instance, the following variable definition: 

<def var = 'TestVar' value = '100'/>
<def var = 'TestVar' value = '200' resolution = '320xY'/>

won't fail to parse. What will happen when loading the theme using a resolution with 320 width is that TestVal first will be assigned the 100 value, and then it will be overwritten with the 200 value. On the other hand, when loading the theme using a resolution without a with of 320, the ThemeVal will be assigned the 100 value and the second key will be plain ignored.

The "proper" way to do that multi-resolution assignment would obviously be: 

<def var = 'TestVar' value = '100' resolution = '-320xY'/>
<def var = 'TestVar' value = '200' resolution = '320xY'/>

This way keys are only parsed on the resolution they are used in, but the result will be exactly the same: Most of the time it's just cleaner to avoid using -320xY resolution tags, and instead write a layout that works on all resolutions and overwrite parts of it with the '320xY' tag.

Retrieved from "https://wiki.scummvm.org/index.php?title=GUI_Themes/Specs&oldid=9484"