package bogue

Theming 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:

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 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 surroundind =. 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-obstrusive 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. 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.
• MENU_HL_COLOR: the color for highlighting selected menu entries.
• MENU_BG_COLOR
• MONO_FONT: monospace font.
• 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).
• 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
• 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 overriden 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 their values. See above for their description.