Themes

A theme defines the appearance and style of Widelands’ user interface. Especially some widgets defined with create_child() need some of the styles of themes.

When working with richtext it is recommended to use the theme styles. Look at styles to access the styles within richtext.

The following directory structure is recommended for a theme’s directory:

  • base_directory/

    • init.lua

    • wui/

      • button.png

      • windows/

        • background.png

        • bottom.png

        • close.png

        • corner_bottom_left.png

        • corner_bottom_right.png

        • corner_minimal_left.png

        • corner_minimal_right.png

        • corner_top_left.png

        • corner_top_right.png

        • left.png

        • maximize.png

        • minimize.png

        • pin.png

        • right.png

        • top.png

        • unpin.png

    • fsmenu/

      • button.png

      • windows/

        • background.png

        • bottom.png

        • close.png

        • corner_bottom_left.png

        • corner_bottom_right.png

        • corner_minimal_left.png

        • corner_minimal_right.png

        • corner_top_left.png

        • corner_top_right.png

        • left.png

        • maximize.png

        • minimize.png

        • pin.png

        • right.png

        • top.png

        • unpin.png

    • loadscreens/

      • logo.png

      • gametips.png

      • ending.png

      • splash.jpg

      • editor.png

      • mainmenu/

        • image1.png

        • image2.jpg

        • …

      • gameloading/
        • desert/

          • image1.png

          • image2.jpg

          • …

        • summer/

          • image1.png

          • …

        • wasteland/

          • image1.png

          • …

        • winter/

          • image1.png

          • …

    • images/

      • …

The names of all files and directories in loadscreens as well as the names wui/ and fsmenu are hardcoded, except for the names and amounts of the image files in loadscreens/mainmenu and in the subdirectories of loadscreens/gameloading/. These directories may contain any number of images. Supported image formats are JPG (large, photographic pictures) and PNG (all other images).

The paths for the images in wui/ and fsmenu/ are specified in the init.lua and may differ from the recommended structure.

Required Files

loadscreens/logo.png

Will be used for the large ‘Widelands’ logo banner displayed in the main menu.

loadscreens/gametips.png

Will be used as background for the tips shown while starting or loading a game.

loadscreens/ending.png

Will be tiled across the screen during a lengthy operation to indicate that user input is blocked. Introduced in version 1.1.

loadscreens/splash.png

The splash screen shown when starting Widelands.

loadscreens/editor.png

The splash screen shown when starting the map editor.

loadscreens/mainmenu/

Any number of images that will be used as backgrounds for the main menu. If more than one image is present, they will be exchanged in frequent intervals. If no images are found, the splashscreen will be used as background instead.

loadscreens/gameloading/

Contains one subdirectory for each of the four map themes ‘desert’, ‘summer’, ‘wasteland’, and ‘winter’. Each of these directories may contain any number of images. Whenever a map is loaded, a random image from the subdirectory corresponding to the map’s theme will be used as background image for the loading screen. If a theme contains no images, the Widelands logo will be used as background instead.

If any of the above images or directories is missing, a fallback image will be used.

wui/ and fsmenu/

These directories contain images for UI elements for items in the game and editor (‘wui’) and in the main menu (‘fsmenu’). The filenames and -paths may be changed, though the correct paths need to be stated in the init.lua file. It is recommended to use the default filenames as stated above.

  • button.png is used as the background for buttons and several other UI elements. The image is tiled to fit the element’s width and height.

  • windows/close.png is used as the icon for the Close button in a window’s top-right corner.

  • windows/pin.png is used as the icon for the Pin button in a window’s top-left corner.

  • windows/unpin.png is used as the icon for the Unpin button in a pinned window’s top-left corner.

  • windows/minimize.png is used as the icon for the minimize button in a window’s top-left corner.

  • windows/maximize.png is used as the icon for the unminimize button in a minimized window’s top-left corner.

  • windows/background.png is used as the window background. The image is tiled to fit the window’s width and height.

  • windows/top.png, windows/bottom.png, windows/left.png, and windows/right.png are used as the window’s upper, lower, left, and right border respectively. The images are tiled to fit the window’s length.

  • windows/corner_bottom_left.png, windows/corner_bottom_right.png, windows/corner_top_left.png, and windows/corner_top_right.png are used as the window’s border’s corners.

  • windows/corner_minimal_left.png and windows/corner_minimal_right.png are used as the window’s corners when the window is minimized.

A window consists of a main panel surrounded on all four sides by a border, with corners where borders meet. The main panel is tiled with the background.png image. Each border is tiled with the respective {top,left,right,bottom}.png image. The four corner images corner_{top,bottom}_{left,right}.png are drawn only once each.

A minimized window consists only of the two corners windows/corner_minimal_{left,right}.png with the top.png border image tiled between them to fit the width.

The thicknesses of the borders are determined by the height of the upper and lower border images and the width of the left and right border images respectively. The corner images are aligned to the corners of the resulting outer rectangle. Because of this, the corner images can be bigger than the respective borders to create fixed transitions to the main border images, but should not be smaller, as that would create gaps in the drawn window borders.

images/

This directory may contain replacement images for any image file located under the data directory’s images directory.

init.lua

This Lua script returns a table with descriptions for all UI elements. The table needs to contain the following keys:

  • minimum_font_size (int): Fonts will not be scaled below this size.

  • minimap_icon_frame (RGB): The color for the frame of minimap previews in the Choose Map/Savegame screens.

  • background_focused (RGBA): The color for the focus overlays of the focused UI element.

  • background_semi_focused (RGBA): The color for the focus overlays of the focused UI element’s parent elements.

  • focus_border_thickness (int): Thickness of the focus overlays of the focused UI element.

  • windows (table): Style definitons for windows

  • buttons (table): Style definitons for buttons

  • sliders (table): Style definitons for sliders

  • tabpanels (table): Style definitons for tabpanels

  • editboxes (table): Style definitons for one-line and multi-line editboxes

  • dropdowns (table): Style definitons for dropdowns

  • scrollbars (table): Style definitons for scrollbars

  • statistics_plot (table): Style definitons for in-game statistics plots

  • building_statistics (table): Style definitons for the in-game building statistics menu

  • progressbar (table): Style definitons for progress bars

  • tables (table): Style definitons for tables

  • wareinfo (table): Style definitons for ware statistics windows

  • fonts (table): Style definitons for all fonts commonly used in Widelands

  • paragraphs (table): Style definitons for all paragraph styles commonly used in Widelands

    New in version 1.2.

  • colors (table): Style definitons for RGB colors

    New in version 1.2.

  • styled_sizes (table): Definitons for UI element sizes and text spacing

    New in version 1.2.

RGB colors are arrays with three entries representing the red, green, and blue components (in this order). RGBA colors are arrays with four entries representing the red, green, blue, and alpha components (in this order). Example:

minimap_icon_frame = {255, 220, 0},
background_focused = {240, 240, 240, 200},

Since version 1.2, it is no longer required to specify all styles in a theme. The corresponding style from the default theme will be used for omitted styles. However, if a style is included, its definition must be complete. Individual elements still cannot be overridden separately.

windows

The windows table contains two subtables wui and fsmenu for in-game/in-editor and main menu windows respectively. Each subtable requires the following keys:

  • window_border_focused (RGBA): The color to blend over the border of the window if it has focus.

  • window_border_unfocused (RGBA): The color to blend over the border of the window if it does not have focus.

  • background, border_top, border_bottom, border_right, border_left, button_close, button_pin, button_unpin, button_minimize, button_unminimize (strings): The paths to the corresponding icons. See above for the recommended directory structure.

  • button_spacing (int) (optional, default 1): The spacing around the window titlebar buttons. Introduced in version 1.3.

buttons

Buttons appearance

The buttons table contains two subtables wui and fsmenu for in-game/in-editor and main menu buttons respectively. Each subtable contains three sub-subtables primary, secondary, and menu for the three button types. Each sub-subtable contains two sub-sub-subtables enabled and disabled for the button’s enabled and disabled variant. Each of these contains a key font with a font definition table and a table background with the keys image, typically pointing to the button background image as described above, and an RGB color color which will be blended with the image.

sliders

The sliders table contains two subtables wui and fsmenu for in-game/in-editor and main menu sliders respectively. The fsmenu subtable contains a single sub-subtable menu; the wui subtable contains two sub-subtables light and dark. Each of these contains tables background and font like for buttons.

tabpanels

The tabpanels table contains two subtables wui and fsmenu for in-game/in-editor and main menu tabpanels respectively. The fsmenu subtable contains a single sub-subtable menu; the wui subtable contains two sub-subtables light and dark. Each of these contains tables image and color like for the backgrounds of buttons.

editboxes

The editboxes table contains two subtables wui and fsmenu for in-game/in-editor and main menu editboxes respectively. Each subtable contains tables background and font like for buttons. The background table requires an additional argument margin of type int which will be used for the editbox’s padding.

scrollbars

The scrollbars table contains two subtables wui and fsmenu for in-game/in-editor and main menu scrollbars respectively, each of which contains a single sub-subtable menu. Each sub-subtable contains tables image and color like for the backgrounds of buttons.

statistics plots

The statistics_plot table contains two subtables colors and fonts. The colors table defines two RGB colors named axis_line and zero_line for the two axis of a statistics plot. The fonts tables needs to define font definition tables named y_min_value and y_max_value (for the y-axis labels) and x_tick (for the x-axis labels).

building statistics

The building statistics table contains two font definition tables census_font and statistics_font which will be used for the in-game census and statistics strings shown over buildings; a table colors with eight RGB colors low, medium, and high (for production sites), low_alt, medium_alt, and high_alt (alternative colors for situations where more contrast is required), construction (for objects under construction), and neutral (e.g. for military sites’ soldier string); and a table statistics_window with an integer value editbox_margin to override the padding of editboxes and a table fonts with two font definition tables button_font (for buttons) and details_font (for other texts).

progress bars

The progressbar table contains two subtables wui and fsmenu for in-game/in-editor and loading screen progress bars respectively. Each subtable contains a font definition table font and a table background_colors with three RGB colors low, medium, and high for the three states of the progress bar.

tables

The tables table contains two subtables wui and fsmenu for in-game/in-editor and main menu tables respectively. Each subtable contains three font definition tables enabled (for normal table entries), disabled (for greyed-out table entries), and hotkey (to display hotkeys).

ware statistics

The wareinfo table contains two subtables highlight and normal for highlighted/selected and non-highlighted items respectively. Each subtable contains a string icon_background_image with an image path; a colors table with three RGB colors icon_frame (for frames), icon_background (for the backgrounds of icons), and info_background (for the background of the info string associated with an item); and a fonts table with two font definition tables header (for captions) and info (for the info strings).

fonts

A font definition table contains the following entries:

  • color (RGB): The font’s color

  • face (string): The font’s face’s name

  • size (int): The default font size

Optionally the following boolean values may be set: bold, italic, underline, and shadow.

Some of the above style tables define custom fonts. Additionally, there is a fonts table which defines fonts used in many places in Widelands:

fonts and themes

wui

  • wui_window_title: Window titles (game and editor)

  • wui_message_heading: Headings for in-game inbox messages

  • wui_message_paragraph: Text of in-game inbox messages

  • wui_info_panel_heading: Headings for info texts (game and editor)

  • wui_info_panel_paragraph: Info texts (game and editor)

  • label_wui: Normal labels (game and editor)

  • tooltip_header_wui: Tooltip headings (game and editor)

  • tooltip_wui: Tooltips (game and editor)

  • tooltip_hotkey_wui: Hotkey tooltips (game and editor)

  • wui_game_speed_and_coordinates: Time, speed and coordinates strings in the game/editor info panel

  • wui_attack_box_slider_label: The label over the in-game attack dialog’s slider

  • game_summary_title: Heading in the end-of-game-summary screen

  • chat_message: Basic chat messages

  • chat_timestamp: Timestamps for chat messages

  • chat_whisper: Whispered chat messages

  • chat_playername: The name of the player who sent a chat message

  • chat_server: Chat messages sent by the server

fs

  • fs_window_title: Window titles (main menu only)

  • fsmenu_gametip: Tips shown on the loading screens

  • fsmenu_info_panel_heading: Headings for info texts (main menu only)

  • fsmenu_info_panel_paragraph: Info texts (main menu only)

  • fsmenu_game_setup_headings: Headings in the main menu’s Launch Game screens

  • fsmenu_game_setup_mapname: The name of the selected map in the Launch Game screens

  • fsmenu_game_setup_superuser: Administrators in the internet lobby’s list of users

  • fsmenu_game_setup_irc_client: IRC clients in the internet lobby’s list of users

  • fsmenu_translation_info: Translation statistics in the main menu’s options window

  • label_fs: Normal labels (main menu only)

  • tooltip_header_fs: Tooltip headings (main menu only)

  • tooltip_fs: Tooltips (main menu only)

  • tooltip_hotkey_fs: Hotkey tooltips (main menu only)

  • fsmenu_intro: Previously used in the splashscreen. Currently unused.

  • italic: Italic texts (main menu only)

global

  • warning: Warnings and errors

  • disabled: Greyed-out items

  • unknown: Used when a Lua script requests a font style not included in this list

    New in version 1.2.

paragraph styles

New in version 1.2.

A paragraph style definition must contain a font definition table font.

Optional elements:

  • align (string): The horizontal alignment of the paragraph, possible values: left (default), center or middle, right

  • valign (string): The vertical alignment of the paragraph, possible values: top (default), center or middle, bottom

  • indent (int): Adds an indentation to the first line of the paragraph

  • spacing (int): Vertical line spacing as a pixel value

  • space_before (int): Padding to be used above the paragraph

  • space_after (int): Padding to be used below the paragraph

Note

Paddings of consecutive paragraphs are added, not collapsed.

The paragraphs table defines paragraph styles used mostly by the help texts and scenarios:

  • readme_title: Used for the name of the game in the About window

  • about_title: Used for the titles of the tab pages in the About window

  • about_subtitle: Used for the subtitles in the tab pages in the About window

  • authors_heading_1: Used for level 1 headings in the Developers tab in the About window

  • fs_heading_1: Used for level 1 headings in the main menu

  • fs_heading_2: Used for level 2 headings in the main menu

  • fs_heading_3: Used for level 3 headings in the main menu

  • fs_heading_4: Used for level 4 headings in the main menu

  • fs_text: The default paragraph style in the About window

  • wui_objectives_heading: Used in scenario message boxes for the titles of new objectives

  • wui_heading_1: Used for level 1 headings in-game/in-editor

  • wui_heading_2: Used for level 2 headings in-game/in-editor

  • wui_heading_3: Used for level 3 headings in-game/in-editor

  • wui_heading_4: Used for level 4 headings in-game/in-editor

  • wui_text: The default paragraph style in-game/in-editor

  • wui_image_line: Used in the Encyclopedia helptexts for consumed items and dependencies

  • wui_lore_author: Used for the lore author texts in the Encyclopedia

  • unknown: Used when a Lua script requests a paragraph style not included in this list

colors

New in version 1.2.

The colors table contains subtables of RGB colors:

  • campaign_bar_thron: Text color for Thron’s speech box titles in the Barbarian campaign

  • campaign_bar_boldreth: Text color for Boldreth’s speech box titles in the Barbarian campaign

  • campaign_bar_khantrukh: Text color for Khantrukh’s speech box titles in the Barbarian campaign

  • campaign_emp_lutius: Text color for Lutius’s speech box titles in the Empire campaign

  • campaign_emp_amalea: Text color for Amalea’s speech box titles in the Empire campaign

  • campaign_emp_saledus: Text color for Saledus’s speech box titles in the Empire campaign

  • campaign_emp_marcus: Text color for Marcus’s speech box titles in the Empire campaign

  • campaign_emp_julia: Text color for Julia’s speech box titles in the Empire campaign

  • campaign_atl_jundlina: Text color for Jundlina’s speech box titles in the Atlantean campaign

  • campaign_atl_sidolus: Text color for Sidolus’s speech box titles in the Atlantean campaign

  • campaign_atl_loftomor: Text color for Loftomor’s speech box titles in the Atlantean campaign

  • campaign_atl_colionder: Text color for Colionder’s speech box titles in the Atlantean campaign

  • campaign_atl_opol: Text color for Opol’s speech box titles in the Atlantean campaign

  • campaign_atl_ostur: Text color for Ostur’s speech box titles in the Atlantean campaign

  • campaign_atl_kalitath: Text color for Kalitath’s speech box titles in the Atlantean campaign

  • campaign_fri_reebaud: Text color for Reebaud’s speech box titles in the Frisian campaign

  • campaign_fri_hauke: Text color for Hauke’s speech box titles in the Frisian campaign

  • campaign_fri_maukor: Text color for Maukor’s speech box titles in the Frisian campaign

  • campaign_fri_murilius: Text color for Murilius’s speech box titles in the Frisian campaign

  • campaign_fri_claus: Text color for Claus Lembeck’s speech box titles in the Frisian campaign

  • campaign_fri_henneke: Text color for Henneke’s speech box titles in the Frisian campaign

  • campaign_fri_iniucundus: Text color for Iniucundus’s speech box titles in the Frisian campaign

  • campaign_fri_angadthur: Text color for Angadthur’s speech box titles in the Frisian campaign

  • campaign_fri_amazon: Text color for the Amazon’s speech box titles in the Frisian campaign

  • campaign_fri_ketelsen: Text color for Ketelsen’s speech box titles in the Frisian campaign

  • map_river_advisor: Text color for the advisor’s speech box titles in the Along the River SP scenario

  • unknown: Used when a Lua script requests a color not included in this list

sizes

New in version 1.2.

The styled_sizes table contains integer values to be used for paddings and UI element sizes:

  • fs_text_default_gap: Default size for extra separator spacing in texts in the About window

  • fs_text_space_before_inline_header: Padding to be used above text lines containing an inline level 3 heading in the About window

  • wui_text_default_gap: Default size for extra separator spacing in texts in-game and in-editor

  • wui_text_space_before_inline_header: Padding to be used above text lines containing an inline level 3 heading in-game and in-editor

  • wui_space_before_immovable_icon: Padding above the icons of the immovables in the Immovable help in the Encyclopedia

  • win_condition_message_gap: Padding between sections in status reports sent by win condition scripts

  • help_terrain_tree_header_space_before: Extra padding above the headers of tree and terrain help texts

  • help_terrain_tree_header_space_after: Extra padding below the headers of tree and terrain help texts

  • editor_tooltip_icon_gap: Gap between the terrain, immovable and animal icons in the editor tooltips

  • campaign_message_box_default_h: Default height of campaign message boxes

  • campaign_message_box_default_w: Default width of campaign message boxes

  • campaign_message_box_top_pos_y: Default y position of campaign message boxes with top alignment

  • campaign_message_box_size_step: Step size for the helper functions that allow changing the width or height of campaign message boxes in a controlled way

  • campaign_message_box_h_min: The minimum height of campaign message boxes that the helper function can set

  • campaign_message_box_h_max: The minimum height of campaign message boxes that the helper function can set

  • campaign_message_box_w_min: The maximum width of campaign message boxes that the helper function can set

  • campaign_message_box_w_max: The maximum width of campaign message boxes that the helper function can set

  • campaign_fri02_poem_indent: The indentation of the poem in the second scenario in the Frisian campaign

  • map_plateau_message_pos_y: The y position of the message boxes in the SP scenario The Green Plateau

  • ui_default_padding: default size for padding between UI elements