bogue 20190717 · OCaml Package

Creating and using widgets

type t

type connection

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.

type action = t -> t -> Tsdl.Sdl.event -> unit

type action_priority =

| Forget
(*
discard the new action
*)
| Join
(*
execute the new after the first one has completed
*)
| Replace
(*
kill the first action (if possible) and execute the second one
*)
| Main
(*
run in the main program. So this is blocking for all subsequent actions
*)

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

val 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 has focus, then when an event ev matches one of the triggers list, the action is executed with arguments source target ev.

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

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

val add_connection : t -> connection -> unit

Registers the connection with the widget. This should systematically be done after each connection that is created after Main.make. add_connection is separated from connect because it is not pure: it mutates the widget. This might change in future versions.

val update : t -> unit

Ask for refresh at next frame. Use this in general in the action of a connection in case the action modifies the visual state of the widget, which then needs to be re-drawn.

Predefined connections

val 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

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

Uses priority=Main

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

Creation of Widgets

Simple boxes (rectangles)

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

Check boxes

The standard on/off check boxes.

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

val set_check_state : t -> bool -> unit

Text display

Use this for multi-line text.

val text_display : ?w:int -> ?h:int -> string -> t

val rich_text : ?size:int -> ?w:int -> ?h:int -> Text_display.words list -> t

val verbatim : string -> t

Labels or icons

One-line text.

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

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

fontawesome icon

Empty

Does not display anything but still gets focus and reacts to events.

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

Generic functions on widgets

val get_state : t -> bool

query a boolean state. Works for Button.t and Check.t

val get_text : t -> string

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

val set_text : t -> string -> unit

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

Image

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

Load image file.

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

Requires rsvg.

Text input

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

Buttons

val 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

val 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

val 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

val 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.

Conversions from the generic Widget type to the specialized inner type

val get_box : t -> Box.t

val get_check : t -> Check.t

val get_label : t -> Label.t

val get_button : t -> Button.t

val get_slider : t -> Slider.t

val get_text_display : t -> Text_display.t

val get_text_input : t -> Text_input.t

package bogue