GUI Themes config file format
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.
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.
NOTE: if you want to add new widgets, pay attention to correspondent section below
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
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.
Currently there are these built-in constants defined:
These correspond to constants defined in gui/widget.h file. There is no restriction on constants names.
- kThumbnailWidth -- defined in graphics/scaler.h
- false = 0
- true = 1
Built-in variables are symbolic names for ScummVM variables whose value is determined at run-time. These are:
- w -- current GUI width
- h -- current GUI height
Defining widget positions
Widgets are specified by following construction:
widget_name=X Y [W H]
X, Y, W and H are whitespace-delimited expressions. W and H are optional.
This construct effectively defines
If W and H are present, also these get defined:
- widget_name.x2 = widget_name.x + widget_name.w
- widget_name.y2 = widget_name.y + widget_name.h
chooser_headline=10 6 (w - 2 * 16) (kLineHeight)
Above mentioned constructions with dots are called widget properties.
Also there are following additional widget properties:
- .visible -- if set to 0, then widget is not drawn
- .align -- for text widgets defines text alignment (kTextAlignLeft, kTextAlignRight or kTextAlignCenter). Default is kTextAlignLeft
Widget class properties
Each widget class can be customized per-resolution. You need to specify their special properties.
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 endges. Default values are 0.
hlLeftPadding, hlRightPadding specify padding of selected text highlight, i.e. green bar in modern theme. Default values are 0.
This is drop-down list used to select one item out of several. In inactive state it displays only selected item.
leftPadding and rightPadding specify list contents (text) padding from widget endges. Default values are 0.
Special variables are:
It is reference to current and last defined widget special variables respectively, i.e. .x, .y, .w and .h
chooser_list=10 (6 + kLineHeight + 2) (w - 2 * 16) (h - self.y - buttonHeight - 12)
Denote self.y which equals to computed value of (6 + kLineHeight + 2).
You cannot use these references forward, i.e. refer to .w in .x. They get defined from left to right.
def_kLineHeight=16 * 2 OneThirdWidth=(w / 3)
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).
You can define alias to any symbolic atom, i.e. constants, variables and widget properties.
Now you can use headerBottomX everywhere.
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
set_parent=tabMidi midi_checkbox=(parent.x + 10) (parent.y + 20) roland_checkbox=midi_checkbox.x (parent.y + 50)
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.
[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.
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.
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 def_blah=22
In above case section [XxY] will not be loaded for 320x200 or 320x240 resolutions.
Modern Theme configuration
Inactive dialog effects
For using an effect change the "inactive_dialog_shading" option in the "[extra]" section of default-theme.ini. Possible values are: "luminance" and "dim".
- "luminance" will change all inactive screen areas to black and white.
- Example (enables it)
- "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 complete black
- Example (30% screen dim):
[extra] inactive_dialog_shading=dim shading_dim_percent=30
Within one section everything is computed left to right down to top. No forward references are allowed. Only exception is 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 built-in theme.
On each resolution change all user-defined variables and aliases get cleared and all sections get 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 whole thing.
Sections loading order is always the same. For resolution 640x480 it is:
- Built-in theme
- Custom theme
Only present sections are loaded. If section is not defined, no error message is generated
Widget name conventions
Widget names are in form:
where dialog_ is dialog name, and widget is a distinguishable name within that dialog. Be discreet and give meaningful names.
What to do if I need to add new widgets to GUI
First thing to mention, is that all real GU behaviour is not described in theme config. You can only alter the look, not the feel. So all real coding should go in corresponding files in 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 both 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 everywhere is narrower
- Indentation is lesser in most cases, besides in Game Options dialog