package bogue

  1. Overview
  2. Docs

Theme variables.

A number of variables control the appearance of your Bogue application. They are called Theme variables. They take effect when you start your application up (no need to recompile). For quick experimentation, they can be modified as environment variables, for instance in a terminal: 

export BOGUE_SCALE=2.5

They can also be saved in configuration files, and you may organize as many config files as you want into themes.

Where are the config files?

The config files are all called bogue.conf. Several locations are used. Upon installing Bogue, a system wide Bogue share directory is created. If you used an opam install, this will be 

$(opam var share)/bogue

The share directory contains a themes directory, which itself contains a default dir. This is where the default configuration file resides.

However, if you want to modify the themes, it is advisable to create your own Bogue share dir. This personal Bogue dir should be $(XDG_CONFIG_HOME)/bogue. (If $XDG_CONFIG_HOME is not defined in your system, you may use $HOME/.config/bogue). So, this is what you can do for creating your personal Bogue dir for the first time: 

cp -r $(opam var
    share)/bogue $HOME/.config/bogue
  • Each theme has its own directory inside the Bogue share dir, in which there is a bogue.conf file where the Theme variables are defined.
  • A global user config file $HOME/.config/bogue/bogue.conf overrides the theme files.
  • A bogue.conf file in the same directory as the executable overrides the other config files.

  • The syntax of the config file is VARIABLE = value, one entry per line. Notice the spaces surrounding =. Comment lines starting by # are ignored. For instance:

    ## BOGUE version 20220115
THEME = dark
BACKGROUND = color:azure

    The first line <code>## BOGUE version XXX</code> is compulsory.

Here is the list of Theme variables:

  • BACKGROUND: the default background for all windows. It can be a color (eg. color:darkturquoise or color:#00CED1), or an image file (eg. file:myimage.png). See below for how to specify paths.
  • BG_COLOR: a background color (eg. darkturquoise, or #00CED1) that is used by default by some widgets/layouts. It should be clearly visible over the BACKGROUND.
  • BUTTON_COLOR_ON: the color of active buttons.
  • BUTTON_COLOR_OFF: the color of inactive buttons.
  • CHECK_ON: the image used for the 'checked' icon. It can be a file (eg. myimage.png) or a font-awesome icon (eg. fa:check-square-o).
  • CHECK_OFF: the image used for the 'unchecked' icon. See CHECK_ON.
  • CURSOR_COLOR
  • DIR: the directory containing the themes subdirectories. Default: auto-detected at startup, usually $HOME/.config/bogue/themes
  • FA_DIR: the fontawesome directory inside DIR/common/.
  • FAINT_COLOR: a non-obtrusive color for disabled options or text of little importance.
  • LABEL_COLOR: the color for text or icon labels.
  • LABEL_FONT: path of a TTF font for text labels. If your system has fontconfig, any installed font (as listed by fc-list) can be specified without the full path. Eg: Ubuntu-R.ttf.
  • LABEL_FONT_SIZE: integer, eg 14.
  • LOG_TO_FILE: if "false", all log messages will appear on the console. If "true", the messages are instead sent to a log file, typically in the "/tmp" directory. Log files can be viewed on an ANSI terminal with less -R or with emacs using xterm-color-colorize-buffer (from the xterm-color package).
  • MENU_HL_COLOR: the color for highlighting selected menu entries.
  • MENU_BG_COLOR
  • MONO_FONT: monospace font. See LABEL_FONT.
  • OPENGL_MULTISAMPLE: set to "true" to enable this opengl attribute.
  • ROOM_MARGIN
  • SCALE: global scale (any non-negative float). For instance if SCALE = 2., all dimensions given to Bogue functions will be multiplied by 2 before rendering to obtain the hardware size in pixels. If set to 0. or not specified, it is autodetected to match your screen DPI (using xdpyinfo, if present).
  • INT_SCALE: set to "true" to force integer scale when using auto-detection. Some games may require this to avoid small graphics artifacts.
  • SEL_BG_COLOR: background color for selected items in lists.
  • SEL_FG_COLOR: text color for selected items in lists.
  • SMALL_FONT_SIZE: integer. Used for instance for tooltips popups.
  • TEXT_COLOR: color of standard text displays.
  • TEXT_FONT: used for text displays. See LABEL_FONT.
  • TEXT_FONT_SIZE
  • THEME: the name of the theme to use. It should be the name of the directory within the themes dir. As soon as this variable is set, all variables from that theme are loaded and override previously defined variables. If not specified, the default theme is initially loaded.

All variables with "COLOR" in their name can be specified either with RGB hexadecimal like #00CED1, or with a standard html name like darkturquoise, see this color table.

All variables can be overridden by setting the corresponding environment variables, prepending "BOGUE_". For instance:

export BOGUE_LABEL_COLOR=forestgreen

How to load assets (images, sounds, etc.)

When specifying a file to load, for instance

BACKGROUND = file:background.png

you need to specify where the file should be searched. Here are the rules:

First, the file is searched in current directory, then in the current theme's directory (for instance $HOME/.config/bogue/themes/default), unless the file string starts with /, in which case it should be an absolute path (eg. file:/home/alice/myimage.png). Finally, if the file string starts with %, for instance file:%assets/images/bob.png, then the % char is replaced by the Bogue dir, for instance file:/home/bob/.config/bogue/assets/images/bob.png.

Dependency graph

Accessing Theme variables

Theme variables are essentially for Bogue's internal use, but sometimes it can be useful to access or modify their values. See above for their description.

Warning: Theme variables are global variables and should be modified (by the main thread) before starting the main loop (with Main.run) if you want predictable results.

val room_margin : int
val scale_int : int -> int

Conversion: Bogue dimension -> hardware pixel dimension. The latter is obtained by multiplying by SCALE.

Warning: Bogue scale is detected only when opening a window, typically when running Main.run, or manually with Draw.video_init. If you use scale_int too early you might end up with zeros... If you don't require auto-detection, you can use set_scale.

val set_text_font : string -> unit
val set_label_font : string -> unit
val set_scale : float -> unit
val set_integer_scale : bool -> unit

Set INT_SCALE.

Accessing files installed along with your application

Files distributed with your application built with Bogue should be installed in a "share" directory, for instance using the install stanza of dune with (section share).

Another solution is to embed your files with the main binary using ppx_blob(https://github.com/johnwhitington/ppx_blob).

val find_share : string -> string -> string option

find_share app file returns a guessed location for your application share directory (if it exists), for instance /usr/local/share/my_app. The app string should be the system name of your application (for instance app="my_app"). The returned location is guaranteed to contain the given file. If you don't have any file to search, you may use file=".".

Warning: The directory returned by find_share is not necessarily writable. If you want a directory where the users of your application can save their preferences, you should rather use Sdl.get_pref_path.