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:
They can also be saved in configuration files, and you may organize as many config files as you want into themes.
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
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 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
bogue.conffile where the Theme variables are defined.
$HOME/.config/bogue/bogue.confoverrides the theme files.
bogue.conffile in the same directory as the executable overrides the other config files.
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:azureThe first line
## BOGUE version XXXis compulsory.
BACKGROUND: the default background for all windows. It can be a color (eg.
color:#00CED1), or an image file (eg.
file:myimage.png). See below for how to specify paths.
BG_COLOR: a background color (eg.
#00CED1) that is used by default by some widgets/layouts. It should be clearly visible over the
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.
CHECK_OFF: the image used for the 'unchecked' icon. See
DIR: the directory containing the themes subdirectories. Default: auto-detected at startup, usually
FA_DIR: the fontawesome directory inside
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:
LABEL_FONT_SIZE: integer, eg
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 -Ror with emacs using xterm-color-colorize-buffer (from the xterm-color package).
MENU_HL_COLOR: the color for highlighting selected menu entries.
MONO_FONT: monospace font. See
OPENGL_MULTISAMPLE: set to "true" to enable this opengl attribute.
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
THEME: the name of the theme to use. It should be the name of the directory within the
themesdir. 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
#00CED1, or with a standard html name like
see this color
All variables can be overridden by setting the corresponding environment variables, prepending "BOGUE_". For instance:
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
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
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
if you want predictable results.
val room_margin :
val scale_int :
int -> int
Conversion: Bogue dimension -> hardware pixel dimension. The latter is
obtained by multiplying by
Warning: Bogue scale is detected only when opening a window, typically
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
val set_text_font :
string -> unit
val set_label_font :
string -> unit
val set_scale :
float -> unit
val set_integer_scale :
bool -> unit
Files distributed with your application built with Bogue should be
installed in a "share" directory, for instance using the
Another solution is to embed your files with the main binary using
string -> string -> string option
find_share app file returns a guessed location for your application
share directory (if it exists), for instance
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
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