Previous  Up  Next

Module Bogue.Main

module Main: sig .. end

Control the workflow of the GUI mainloop.

Dependency graph
type board

The board is the whole universe of your GUI. It contains everything. Most of the time, though, you don't really care, because you will immediately run your board after creating it, like in run (of_layout my_layout).

However, nothing prevents you from creating several boards and finally choosing the one you want to run. What you should not do is to simultaneously run several boards in different threads, because SDL can manage events only from the main thread.

type shortcuts

Shortcut maps can be passed to the board to associate an arbitrary action with specific keys (like quitting when ESC is pressed). See Creating global keyboard shortcuts.

exception Exit

Raising the Exit exception will tell the GUI loop to terminate.

val create : ?shortcuts:shortcuts ->
       ?connections:Widget.connection list ->
       ?on_user_event:(Tsdl.Sdl.event -> unit) ->
       Window.t list -> board

Create a board from a list of layouts and connections. The list of connections can be empty, because connections can be added afterwards. Each Layout in the list will open as a new window.

shortcuts : This optional argument is a shortcut map.
on_user_event : This optional argument is a function to be executed (by the main thread) when a Trigger.user_event is emitted.
val get_monitor_refresh_rate : board -> int option

get_monitor_refresh_rate board returns the monitor refresh rate, for the monitor containing board. In case of several monitors with different refresh rates, return the greatest common divisor, or the minimum if the gcd is less than 30.

val of_windows : ?shortcuts:shortcuts ->
       ?connections:Widget.connection list ->
       ?on_user_event:(Tsdl.Sdl.event -> unit) ->
       Window.t list -> board

Synonym for Main.create. (Since 20220418)

val of_layouts : ?shortcuts:shortcuts ->
       ?connections:Widget.connection list ->
       ?on_user_event:(Tsdl.Sdl.event -> unit) ->
       Layout.t list -> board

Similar to Main.create. Each layout in the list will be displayed in a different window. (Since 20220418)

val of_layout : ?shortcuts:shortcuts ->
       ?connections:Widget.connection list ->
       ?on_user_event:(Tsdl.Sdl.event -> unit) -> Layout.t -> board

Similar to Main.of_layout but with only one layout. (Since 20220418)

val make : ?shortcuts:shortcuts ->
       Widget.connection list -> Layout.t list -> board
Deprecated. (since 20220418). Use Main.of_layouts or Main.create instead.

Similar to Main.of_layouts.

val run : ?vsync:bool ->
       ?before_display:(unit -> unit) ->
       ?after_display:(unit -> unit) -> board -> unit

This is finally how you run your app! It creates the SDL windows associated with the Window.ts registered with the board, and launches the main loop. This function only returns when all windows are closed (in case at least one window was created), or when the Main.Exit exception is raised. vsync defaults to true and enables synchronization to monitor refresh rate where possible, otherwise a 60 FPS Time.adaptive_fps is used.

Creating global keyboard shortcuts

A shortcut consists of two integers: one for the key modifier (shift, ctrl, etc.) and one for the key code (from SDL table), plus an action to be executed when this key combination is pressed.

For the shortcuts to take effect, one has to pass a shortcuts argument to the board creating functions. This argument can be created with shortcuts_of_list, or by using the shortcuts_add* functions below.

type shortcut_action = board -> unit 
val shortcuts_of_list : (Tsdl.Sdl.keymod * Tsdl.Sdl.keycode * shortcut_action) list ->
       shortcuts

Construct shortcuts from a list of (SDL keycode, SDL keymod, action).

val exit_on_escape : Tsdl.Sdl.keymod * Tsdl.Sdl.keycode * shortcut_action

The exit_on_escape shortcut will raise the Main.Exit exception upon pressing the Escape key.

val shortcuts_empty : unit -> shortcuts
val shortcuts_add : shortcuts ->
       ?keymod:Tsdl.Sdl.keymod ->
       Tsdl.Sdl.keycode -> shortcut_action -> shortcuts
val shortcuts_add_ctrl : shortcuts ->
       Tsdl.Sdl.keycode -> shortcut_action -> shortcuts
val shortcuts_add_ctrl_shift : shortcuts ->
       Tsdl.Sdl.keycode -> shortcut_action -> shortcuts
val get_shortcut : ?map:shortcuts ->
       ?keymod:Tsdl.Sdl.keymod -> int -> shortcut_action option
val remove_shortcut : ?board:board -> ?keymod:Tsdl.Sdl.keymod -> int -> unit
val add_shortcut : ?board:board ->
       ?keymod:Tsdl.Sdl.keymod -> int -> shortcut_action -> unit

Using Bogue together with another graphics loop

See the embed example.

val make_sdl_windows : ?windows:Tsdl.Sdl.window list -> board -> unit

This is only useful if you have your own graphics loop, and do not use Main.run. This function creates an SDL window for each top layout in the board. One can use predefined windows with the optional argument windows. They will be host the layouts in the order they appear in the list. If there are fewer windows than layouts, new windows are created. If there are more, the excess is disregarded.

val refresh_custom_windows : board -> unit

Ask the GUI to refresh (ie. repaint) the custom windows (those that were not created by Bogue itself).

val one_step : ?before_display:(unit -> unit) ->
       bool ->
       (unit -> unit) * (unit -> unit) -> ?clear:bool -> board -> bool

This is only useful if you have your own graphics loop, and do not use Main.run. Calling one_step ~before_display anim (start_fps, fps) ~clear
      board is what is executed at each step of the Bogue mainloop. If anim=true this step is non blocking; this is what you want if either Bogue or your loop has an animation running. If anim=false then the function will wait until an event is received.

val get_frame : unit -> int

Number of displayed frames since startup.

val quit : unit -> unit

Use this to close SDL windows and cleanup memory, after Main.run has returned. This does not exit your program. Calling quit () is not necessary if your program exits after Main.run.