Up  Next

Module Bogue.Theme

module Theme: sig .. end

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

Here is the list of Theme variables:

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:

  1. If the file string starts with /, it should be an absolute path (eg. file:/home/alice/myimage.png), no additional search is performed.
  2. 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.
  3. Otherwise, the file is first searched in the directory where your application binary resides (if any), then in the current directory, then in the current theme's directory (for instance $HOME/.config/bogue/themes/default), and finally in the special "common" theme.
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 Theme.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.

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.

val get_path : ?path:string list -> string -> string

get_path file returns an absolute path for accessing the given file using the rules described above, except if the file is not found, in which case the string file is returned unchanged, with the hope that it corresponds to a file in the current directory. Instead of the Bogue share directories, alternative directories for searching the file can be provided via the path option.

val get_font_path_opt : string -> string option

get_font_path file returns an absolute path for the given TTF file, if found. If file starts with "/", only this location is checked. Otherwise, the font file is searched first in the theme directory, then in Bogue's common fonts dir, then in the system's fonts (using fc-list, if available).