bogue 20220101 · OCaml Package

The main, all-purpose graphics container

A layout is a "box" (a rectangle) whose purpose is to place onscreen the various elements composing the GUI. It can contain a single widget, or a list of sub-layouts. In Bogue, we use the housing metaphor: a layout is a house that contains either a single resident, or several rooms. Each room can be seen as a sub-house, and can contain a resident or sub-rooms. Houses and rooms have the type t, while a resident has the type Widget.t.

Technically, the usual metaphor in computer science is a Tree. A layout is a tree, each vertex (or node) has any number of branches (or children). A leaf (terminal node: without any child) is either empty or contains a widget. However, the tree is upside-down (as often): we think of the trunk (or top-layout) to be a the top, and the leaves at the bottom.

Dependency graph

type t

exception Fatal_error of t * string

type room_content =

| Rooms of t list
| Resident of Widget.t

type adjust =

| Fit
| Width
| Height
| Nothing

Not implemented.

Backgrounds

type background

Warning, the background type corresponds actually to the Style.t type, which means is includes color backgrounds, image patterns, corner and shadow styles. In fact, any Box.t can be turned into a background.

val color_bg : Draw.color -> background

Construct a background from an RGBA color.

val opaque_bg : Draw.rgb -> background

Construct a background from a RGB (ie non-transparent) color.

val box_bg : Box.t -> background

Construct a background from the given Box.

val style_bg : Style.t -> background

Construct a background from the given Style.

val bg_color : background

This is the background constructed from the current theme's BG_COLOR.

val unload_background : t -> unit

Free the texture associated with the background (if any). This can be used to force recreating it.

Creation of layouts

Remark: all layouts have an optional name property, which is used only for debugging.

val empty : 
  ?name:string ->
  ?background:background ->
  w:int ->
  h:int ->
  unit ->
  t

An empty layout can reserve some space without stealing focus.

Create layouts from widgets

val resident : 
  ?name:string ->
  ?x:int ->
  ?y:int ->
  ?w:int ->
  ?h:int ->
  ?background:background ->
  ?draggable:bool ->
  ?canvas:Draw.canvas ->
  ?layer:Draw.layer ->
  ?keyboard_focus:bool ->
  Widget.t ->
  t

val flat_of_w : 
  ?name:string ->
  ?sep:int ->
  ?h:int ->
  ?align:Draw.align ->
  ?background:background ->
  ?widget_bg:background ->
  ?canvas:Draw.canvas ->
  ?scale_content:bool ->
  Widget.t list ->
  t

val tower_of_w : 
  ?name:string ->
  ?sep:int ->
  ?w:int ->
  ?align:Draw.align ->
  ?background:background ->
  ?widget_bg:background ->
  ?canvas:Draw.canvas ->
  ?scale_content:bool ->
  Widget.t list ->
  t

Create layouts from other layouts

val flat : 
  ?name:string ->
  ?sep:int ->
  ?adjust:adjust ->
  ?hmargin:int ->
  ?vmargin:int ->
  ?margins:int ->
  ?align:Draw.align ->
  ?background:background ->
  ?shadow:Style.shadow ->
  ?canvas:Draw.canvas ->
  ?scale_content:bool ->
  t list ->
  t

val tower : 
  ?name:string ->
  ?sep:int ->
  ?margins:int ->
  ?hmargin:int ->
  ?vmargin:int ->
  ?align:Draw.align ->
  ?adjust:adjust ->
  ?background:background ->
  ?shadow:Style.shadow ->
  ?canvas:Draw.canvas ->
  ?clip:bool ->
  ?scale_content:bool ->
  t list ->
  t

val superpose : 
  ?w:int ->
  ?h:int ->
  ?name:string ->
  ?background:background ->
  ?canvas:Draw.canvas ->
  ?center:bool ->
  ?scale_content:bool ->
  t list ->
  t

Create a new layout by superposing a list of layouts without changing their (x,y) position.

Remark: when creating a house (a layout) with flat*, tower*, or superpose, the size of the inner rooms will be automatically updated whenever the size of the house is modified. However, as soon as one manually sets the size or the position of a room inside this house with set_width, setx and alikes, then the room will stop reacting to changes of the house size.

Some useful layout combinations

val make_clip : 
  ?w:int ->
  ?scrollbar:bool ->
  ?scrollbar_inside:bool ->
  ?scrollbar_width:int ->
  h:int ->
  t ->
  t

Clip a layout inside a smaller container and make it scrollable, and optionally add a scrollbar widget.

Get layout attributes

val xpos : t -> int

get current absolute x position of the layout (relative to the top-left corner of the window). Not necessarily up-to-date.

val ypos : t -> int

see xpos

val width : t -> int

val height : t -> int

val get_size : t -> int * int

get_size l is equivalent to (width l, height l)

val get_physical_size : t -> int * int

multiplies get_size by the Theme scaling factor. This gives in principle the correct size in physical pixels, up to an error of +/- 1pixel, due to rounding error.

val getx : t -> int

Compute the relative x position of the room with respect to its house, using animations if any. Because of this, this function should not be called by the animation itself! Use get_oldx instead.

val get_oldx : t -> int

Return the last computed value for the relative x position of the layout.

val gety : t -> int

val get_oldy : t -> int

val widget : t -> Widget.t

Return the resident widget, or

raises Not_found
if the layout is not a leaf.

val top_house : t -> t

Return the top of the layout tree (the "house" that contains the given layout and that is not contained in another layout). It is the only layout that is directly attached to a "physical" (SDL) window.

val get_content : t -> room_content

val get_rooms : t -> t list

val has_resident : t -> bool

Modify existing layouts

These functions will not work if there is an animation running acting of the variable we want to set. Most of these functions will stop the automatic resizing mechanism of the room. Use auto_scale to reactivate it.

val auto_scale : t -> unit

Set the layout to automatically scale its inner rooms when the layout size is modified.

val set_width : 
  ?keep_resize:bool ->
  ?check_window:bool ->
  ?update_bg:bool ->
  t ->
  int ->
  unit

val set_height : 
  ?keep_resize:bool ->
  ?check_window:bool ->
  ?update_bg:bool ->
  t ->
  int ->
  unit

val set_size : 
  ?keep_resize:bool ->
  ?check_window:bool ->
  ?update_bg:bool ->
  t ->
  (int * int) ->
  unit

val setx : ?keep_resize:bool -> t -> int -> unit

val sety : ?keep_resize:bool -> t -> int -> unit

val set_show : t -> bool -> unit

val set_shadow : t -> Style.shadow option -> unit

val fix_content : t -> unit

Disable automatic resizing of the rooms inside this layout.

val fit_content : ?sep:int -> t -> unit

Adapt the size of the layout (and their houses) to the disposition of the contained rooms.

val set_rooms : t -> ?sync:bool -> t list -> unit

Modify the layout content by replacing the former content by a new list of rooms. Use sync=true (the default) as much as possible in order to avoid multi-threading problems. Then the changes will be applied by the main thread at next frame (see Sync).

val replace_room : by:t -> t -> unit

Replace "room" by "by" inside "house" in lieu and place of the intial room. No size adjustments are made. Of course this is dangerous, because it modifies both the house and "by". Beware of circular dependencies... Of course this assumes that "room" already belongs to "house".

val unload_textures : t -> unit

Use this to free the textures stored by the layout (and its children) for reducing memory. The layout can still be used without any impact, the textures will be recreated on the fly.

val lock : t -> unit

val unlock : t -> unit

Since layouts can be modified by different threads, it might be useful to lock it with a mutex. This does *not* always prevent from modifying it, but another lock statement will wait for the previous lock to be removed by unlock.

val push_close : t -> unit

Emit the close-window event to the window containing the layout. This should close the window at the next graphics frame.

Animations

Position, size, alpha channel, and rotation of Layouts use Avar variables and hence can be easily animated. Most predefined animations have a default duration of 300ms.

Generic animations

These functions assign an animated variable if type Avar.t to one of the properties of the layout (position, width, etc.)

val animate_x : t -> int Avar.t -> unit

Assign an Avar to the layout x position.

val animate_y : t -> int Avar.t -> unit

val stop_pos : t -> unit

Stop animations of the variables x and y.

val animate_w : t -> int Avar.t -> unit

val animate_h : t -> int Avar.t -> unit

val animate_alpha : t -> float Avar.t -> unit

val animate_angle : t -> float Avar.t -> unit

Predefined animations

val hide : ?duration:int -> ?towards:Avar.direction -> t -> unit

See show.

val show : ?duration:int -> ?from:Avar.direction -> t -> unit

Does nothing if the layout is already fully displayed. Only the Avar.Top and Avar.Bottom directions are currently implemented. For these directions, hide and show do not modify the position variables (x,y) of the layout, they use a special variable called voffset.

val fade_in : 
  ?duration:int ->
  ?from_alpha:float ->
  ?to_alpha:float ->
  t ->
  unit

Animate the alpha channel of the layout. Can be combined with animations involving the other animated variables. Does not modify the show status of the layout. By default, from_alpha=0. (transparent) and to_alpha=1. (opaque).

val fade_out : 
  ?duration:int ->
  ?from_alpha:float ->
  ?to_alpha:float ->
  ?hide:bool ->
  t ->
  unit

See fade_in. WARNING: fading out to alpha=0 results in a completely transparent layout, but the layout is still there (it's not "hidden"). Which means it can still get mouse focus. If you want to hide it, then use hide=true. By default, hide=false, from_alpha is the current alpha of the layout, and to_alpha=0.

val rotate : ?duration:int -> ?from_angle:float -> angle:float -> t -> unit

Rotate all widgets inside the layout around their respective centers. For a global rotation, use a Snapshot.

val slide_in : ?from:Avar.direction -> dst:t -> t -> unit

val slide_to : ?duration:int -> t -> (int * int) -> unit

slide_to room (x0,y0) will translate the room to the position (x0,y0).

val follow_mouse : 
  ?dx:int ->
  ?dy:int ->
  ?modifierx:(int -> int) ->
  ?modifiery:(int -> int) ->
  t ->
  unit

val oscillate : ?duration:int -> ?frequency:float -> int -> t -> unit

val zoom : ?duration:int -> from_factor:float -> to_factor:float -> t -> unit

val reflat : 
  ?align:Draw.align ->
  ?hmargin:int ->
  ?vmargin:int ->
  ?margins:int ->
  ?duration:int ->
  t ->
  unit

Adjust an existing layout to arrange its rooms in a "flat" fashion, as if they were created by Layout.flat. Will be animated if duration <> 0.

val retower : 
  ?align:Draw.align ->
  ?hmargin:int ->
  ?vmargin:int ->
  ?margins:int ->
  ?duration:int ->
  t ->
  unit

Windows

A very special use of layout is to represent the 'window' on which everything is drawn. Thus, this specific to the 'main house' (or top-layout), i.e. a layout that is not a sublayout of another layout.

val window : t -> Tsdl.Sdl.window

val set_window_pos : t -> (int * int) -> unit

It should be set after Main.make and before Main.run. Otherwise it has possibly no effect, or perhaps causes some glitches.

Misc

val set_cursor : t option -> unit

Sets the cursor to the default value for this layout.

package bogue