Module Bogue.WidgetSource

Creating widgets and giving life to them

Widgets are simple graphic elements that can react to user interaction. They are the inhabitants of your GUI house. When a widget is woken up by some event, it can talk to another widget by means of a connection.

Dependency graph
Sourcetype t

The type t is a union of all kinds of widgets: Box, Button, Check box, Image, Label, Slider, Text display, and Text input, plus the Empty widget.

For instance, in the following code:

let w = label "Hello" in
let l = get_label w in
...

w has the generic t type, while l has the specialized Label.t type.

Connections

A connection has a source widget and a target widget. When the source widget receives a specified event, the connection is activated, executing a specified function, which is called action.

An action is always executed in a new Thread (and hence will not block the GUI), unless the priority Main is specified.

Sourcetype connection
Sourcetype action = t -> t -> Tsdl.Sdl.event -> unit

An action is a function with three parameters w1 w2 ev, where w1 is the source widget, w2 the target widget, and ev the event (Trigger.t) that triggered the action.

What to do when the same action (= same connection id) is already running?

Sourcetype action_priority =
  1. | Forget
    (*

    discard the new action

    *)
  2. | Join
    (*

    execute the new after the first one has completed

    *)
  3. | Replace
    (*

    kill the first action (if possible) and execute the second one

    *)
  4. | Main
    (*

    run in the main program. So this is blocking for all subsequent actions

    *)
Sourceval connect : t -> t -> action -> ?priority:action_priority -> ?update_target:bool -> ?join:connection -> Trigger.t list -> connection

connect source target action triggers creates a connection from the source widget to the target widget, but does not register it (this may change in the future...). Once it is registered (either by Main.make or add_connection), and assuming that the layout containing the source widget has focus, then when an event ev matches one of the triggers list, the action is executed with arguments source target ev.

  • parameter priority

    indicates the desired priority policy. Default is Forget.

Sourceval connect_main : t -> t -> action -> ?update_target:bool -> ?join:connection -> Trigger.t list -> connection

Alias for connect ~priority:Main. Should be used for very fast actions that can be run in the main thread.

Sourceval add_connection : t -> connection -> unit

Registers the connection with the widget. This should systematically be done after each connection creation, when the connection is created after Main.make.

Connections that are created before Main.make should rather be passed as argument to Main.make, and not via add_connection. Although this is not striclty necessary, this indicates that these connections are more 'pure' or at least more static, in the sense that they will not be modified by Bogue. These are usually much easier to debug.

add_connection is separated from connect because it is not pure: it mutates the widget. This might change in future versions.

Sourceval update : t -> unit

update w asks the widget w to refresh at next frame. The most probable use of update is within the code of an action. It can happen that the action modifies the visual state of a widget that is neither the source or the target, and then one needs to explicitly tell this widget to re-draw itself.

Predefined connections

Sourceval on_release : release:(t -> unit) -> t -> unit

on_release ~release:f w registers on the widget w the action f, which will be executed when the mouse button is released on this widget. Uses priority=Main

Sourceval on_click : click:(t -> unit) -> t -> unit

Uses priority=Main

Sourceval mouse_over : ?enter:(t -> unit) -> ?leave:(t -> unit) -> t -> unit

Creation of Widgets

Simple boxes (rectangles)

Sourceval box : ?w:int -> ?h:int -> ?background:Style.background -> ?border:Style.border -> ?shadow:Style.shadow -> unit -> t

Create a Box widget, which simply displays a rectangle, optionally with rounded corners and drop shadow. It is often used for the background of a group of widgets (i.e. a Layout.t).

Check boxes

The standard on/off check boxes.

Sourceval check_box : ?state:bool -> ?style:Check.style -> unit -> t
Sourceval set_check_state : t -> bool -> unit

Text display

Use this for multi-line text.

Sourceval text_display : ?w:int -> ?h:int -> string -> t
Sourceval rich_text : ?size:int -> ?w:int -> ?h:int -> Text_display.words list -> t
Sourceval verbatim : string -> t
Sourceval html : string -> t

Display basic html text by interpreting the following tags: <em>,</em>, <b>,</b>, <strong>,</strong>, <p>,</p>, <br>

Labels or icons

Sourceval label : ?size:int -> ?fg:Draw.color -> ?font:Label.font -> string -> t

Create a Label widget with a one-line text.

Sourceval icon : ?size:int -> ?fg:Draw.color -> string -> t

Create a Label widget with a FontAwesome icon.

For instance icon ~size:24 "star" creates a widget that displays the "fa-star" fontawesome icon.

Empty

Sourceval empty : w:int -> h:int -> unit -> t

Create a widget that does not display anything but still gets focus and reacts to events.

Image

Sourceval image : ?w:int -> ?h:int -> ?bg:Draw.color -> ?noscale:bool -> string -> t

Load image file.

Sourceval image_from_svg : ?w:int -> ?h:int -> ?bg:Draw.color -> string -> t

Requires rsvg.

Text input

Sourceval text_input : ?text:string -> ?prompt:string -> ?size:int -> ?filter:Text_input.filter -> ?max_size:int -> unit -> t

Buttons

Sourceval button : ?kind:Button.kind -> ?label:Label.t -> ?label_on:Label.t -> ?label_off:Label.t -> ?fg:Draw.color -> ?bg_on:Style.background -> ?bg_off:Style.background -> ?bg_over:Style.background -> ?state:bool -> ?border_radius:int -> ?border_color:Draw.color -> string -> t

Sliders

Sourceval slider : ?priority:action_priority -> ?step:int -> ?value:int -> ?kind:Slider.kind -> ?var:(int Avar.t, int) Tvar.t -> ?length:int -> ?thickness:int -> ?tick_size:int -> ?lock:bool -> int -> t
Sourceval slider_with_action : ?priority:action_priority -> ?step:int -> ?kind:Slider.kind -> value:int -> ?length:int -> ?thickness:int -> ?tick_size:int -> action:(int -> unit) -> int -> t

Create a slider that executes an action each time the local value of the slider is modified by the user.

Creation of combined widgets

Sourceval check_box_with_label : string -> t * t

let b,l = check_box_with_label text creates a check box b, a label l, and connect them so that clicking on the text will also act on the check box.

Generic functions on widgets

Sourceval get_state : t -> bool

query a boolean state. Works for Button and Check.

Sourceval get_text : t -> string

Return the text of the widget. Works for Button, TextDisplay, Label, and TextInput.

Sourceval set_text : t -> string -> unit

Change the text of a widget. Works for Button, TextDisplay, Label, and TextInput.

Conversions from the generic Widget type to the specialized inner type

Sourceval get_box : t -> Box.t
Sourceval get_check : t -> Check.t
Sourceval get_label : t -> Label.t
Sourceval get_button : t -> Button.t
Sourceval get_slider : t -> Slider.t
Sourceval get_text_display : t -> Text_display.t
Sourceval get_text_input : t -> Text_input.t