Props (stk.Stk.Props)

type t

A property-to-value map. This is a mutable structure.

Properties

exception Property_exists of string

Exception raised when trying to register a property but a property with the same name is already registered. The argument is the property name.

type 'a post_action =

| Resize
| Render
| Action of 'a -> unit

Describre what to do after a property is updated:

Resize: widget will claim that it needs resizing.
Render: widget will claim that it needs to be rendered.
Action f: call f ().

module Id : Misc.Id

Unique property ids.

type 'a prop

A property for values of type 'a.

type prop_value = ..

val name : 'a prop -> string

Get property name.

val after : 'a prop -> 'a post_action list

Get property post action list.

val prop_to_string : 'a prop -> 'a -> string

prop_to_string p v returns a string representation of a property value v, using the Ocf wrapper assoociated to property p.

val pp_prop : 'a prop -> Stdlib.Format.formatter -> 'a -> unit

pp_prop p ppf v pretty-prints value v of property p to formatter ppf.

module type PT = sig ... end

What is required to handle a property value: a type, a comparison function and an optional Ocf wrapper.

type 'a mk_prop =
  ?after:'a post_action list ->
  ?default:'a ->
  ?inherits:bool ->
  string ->
  'a prop

The type of functions creating properties. The property name is required. The property is then registered in a table. Creating a property when a property with the same name already exists raises Property_exists. Options arguments are:

after: a description of actions to perform after the value of a property changed. This is used in widgets to automatically perform these actions.
default: a default value for this property. This is the value returned by get when no value is defined for a property.
inherits (default is true indicates whether the value for this property is inherited by a widget when this widget is added to a parent widget (see Widget.widget.set_parent).

Property types

module type Prop_type = sig ... end

Type a of property, with a function mk_prop to create properties of this type.

module Add_prop_type (T : PT) : Prop_type with type t = T.t

Creating a property type from a value description.

Predefined property types

type 'a trbl = {

top : 'a;
right : 'a;
bottom : 'a;
left : 'a;

}

Top-right-bottom-left values.

val trbl : top:'a -> right:'a -> bottom:'a -> left:'a -> 'a trbl

val trbl_ : 'a -> 'a -> 'a -> 'a -> 'a trbl

trbl_ top right bottom left is a label-less equivalent of trbl_ ~top ~right ~bottom ~left.

val trbl__ : 'a -> 'a trbl

trbl__ x is equivalent to trbl ~top:x ~right:x ~bottom:x ~left:x.

val trbl_of : 
  ?top:'a ->
  ?right:'a ->
  ?bottom:'a ->
  ?left:'a ->
  'a trbl ->
  'a trbl

trbl_of t copies t except fields given as optional arguments.

val trbl_compare : ('a -> 'b -> int) -> 'a trbl -> 'b trbl -> int

trbl comparison.

val trbl_ocf_wrapper : 'a Ocf.Wrapper.t -> 'a trbl Ocf.Wrapper.t

Ocf.wrapper for trbl, using the given wrapper for values.

module TInt : PT with type t = int

module PInt : Prop_type with type t = int

module PFloat : Prop_type with type t = float

module PBool : Prop_type with type t = bool

module PString : Prop_type with type t = string

module PUchar : Prop_type with type t = Stdlib.Uchar.t

module TColor : PT with type t = Color.t

module PColor : Prop_type with type t = Color.t

module PFont_desc : Prop_type with type t = Font.font_desc

module PLayer : Prop_type with type t = Layer.t

module TProps : PT with type t = t

module PProps : Prop_type with type t = t

module PTrbl (T : PT) : Prop_type with type t = T.t trbl

module PTrbl_int : Prop_type with type t = int trbl

module PTrbl_color : Prop_type with type t = Color.t trbl

module PPair (T1 : PT) (T2 : PT) : Prop_type with type t = T1.t * T2.t

module PPair_float : Prop_type with type t = float * float

Predefined property constructors

val int_prop : int mk_prop

val float_prop : float mk_prop

val color_prop : Color.t mk_prop

val bool_prop : bool mk_prop

val string_prop : string mk_prop

val uchar_prop : Stdlib.Uchar.t mk_prop

val font_desc_prop : Font.font_desc mk_prop

val layer_prop : Layer.t mk_prop

val int_trbl_prop : int trbl mk_prop

val color_trbl_prop : Color.t trbl mk_prop

val float_pair_prop : (float * float) mk_prop

val props_prop : t mk_prop

val keystate_prop : Key.keystate mk_prop

Property-to-value maps

type props = t

The property-to-value map of each Object.o (including widgets) are referred to as their "properties". We add a props type to represent this denomination.

val empty : unit -> t

Returns a new empty property map.

val dup : t -> t

dup t returns a copy of t.

val default : t

Default properties. By now it is empty. Can be used internally for debugging.

val create : unit -> t

Create a new property map with default values.

val opt : t -> 'a prop -> 'a option

opt t p returns the value of property p in t, is any.

val get : t -> 'a prop -> 'a

get t p returns the value of property p in t, or else the default value of p. If p has no value in t and p has no default value, then exception Misc.error.Missing_prop is raised.

val set : t -> 'a prop -> 'a -> unit

set t p v gives value v to property p in t.

val set_opt : t -> 'a prop -> 'a option -> unit

set_opt t p (Some v) gives value v to property p in t. set_opt t p None removes value associated to p in t.

val update : t -> 'a prop -> 'a -> 'a option option

update t p v set value v to propery p in t. If v is the same as previousvalue for p in t, then returns None, else returns Some x with x being the optional previous value associated to p in t.

val compare : t -> t -> int

Property map comparison.

val to_string : t -> string

to_string t returns a string representation of t, mainly for debugging purpose.

val pp : Stdlib.Format.formatter -> t -> unit

pp ppf t pretty-prints t to the given formatter, using to_string.

val merge : ?use_inherits:bool -> t -> t -> t

merge t1 t2 returns a new !t using map merging function (see Map.S.merge). The optional argument use_inherits (false by default) change the way to handle the case where a property p has a value v in t1 and no value in t2. When use_inherits = false, p is given value v in the new map. When use_inherits = true, then p is given value v in the new map only if p was defined with ~inherits:true (which is the default, see mk_prop).

val iter : ('a prop -> 'a -> unit) -> t -> unit

iter f t calls f on each property defined in t.

val fold : ('a prop -> 'a -> 'b -> 'b) -> t -> 'b -> 'b

fold f t acc folds over properties defined in t.

Predefined properties

All properties are not inherited, except when specified else. The name of a property is the same as its OCaml ident. For example property padding has name "padding", except is specified else.

type text_valign =

| Baseline
| Sub
| Super
| Top
| Text_top
| Middle
| Bottom
| Text_bottom

type selection_mode =

| Sel_none
| Sel_single
| Sel_browse
| Sel_multiple

type orientation =

| Vertical
| Horizontal

val padding : int trbl prop

Padding of a widget in pixels.

val margin : int trbl prop

Margin of a widget in pixels.

val border_width : int trbl prop

Border width of a widget in pixels.

val border_color : Color.t trbl prop

Border color of a widget.

val border_color_hover : Color.t trbl prop

Border color of a widget when mouse cursor in hovering.

val border_color_selected : Color.t trbl prop

Border color of a widget when its selected property is true.

val border_color_focused : Color.t trbl prop

Border color of a widget when its is_focus property is true.

val hexpand : int prop

How many shares of a container free space the widget requires to expand horizontally (see Pack.box.pack).

val vexpand : int prop

How many shares of a container free space the widget requires to expand vertically (see Pack.box.pack). Default is 1.

val visible : bool prop

Whether the widget is visible. Default is true. Inherited.

val sensitive : bool prop

Whether the widget is sensitive, i.e. responds to user events. Default is true. Inherited.

val insensitive_color_mask : Color.t prop

The color mask to apply on insensitive widgets. Default is 0x80808044. Inherited.

val hfill : bool prop

Whether the widget should fill horizontally the allocated space. (used by some containers). Default is true.

val vfill : bool prop

Whether the widget should fill vertically the allocated space. (used by some containers). Default is true.

val halign : float prop

Horizontal alignment (not used by all widgets). 0. means align on the left, 1.0 means align on the right. Default is 0.5 (centered).

val valign : float prop

Same as halign but for vertical alignment (0.: align on top, 1.: align on bottom).

val width : int prop

Width of a widget in pixels. Only some widgets use this property. Other widget's width depend on the way they are packed and their allocated width can be accessed through the Widget.widget.geometry method. Inherited.

val height : int prop

Same as width but for... height.

val fill : bool prop

Whether backgroup must be filled with bg_color. Default is false.

val bg_fill_borders : bool prop

Whether background color should cover borders. Default is false.

val font_desc : Font.font_desc prop

Font description. Inherited. Default is family "DejaVu Sans" with size 14.

val bold : bool prop

Whether font to use is bold. Inherited. If set, then the bold flag in font description is set accordingly when retrieving the corresponding SDL font.

val italic : bool prop

Same as bold but for italic. Inherited.

val fg_color : Color.t prop

Foreground color, use for example for text. Inherited.

val fg_color_hover : Color.t prop

Foreground color when mouse is hovering. Inherited.

val fg_color_selected : Color.t prop

Foreground color when widget has its selected property set to true. Inherited.

val fg_color_focused : Color.t prop

Foreground color when widget has its is_focus property set to true. Inherited.

val bg_color : Color.t prop

Foreground color, use for example for text. Inherited. Remember that setting background color has no effect if fill property has value false.

val bg_color_hover : Color.t prop

Foreground color when mouse is hovering. Inherited.

val bg_color_selected : Color.t prop

Foreground color when widget has its selected property set to true. Inherited.

val bg_color_focused : Color.t prop

Foreground color when widget has its is_focus property set to true. Inherited.

val input_bg_color : Color.t prop

Background color for input area. Default is 0xeeeeeeff. Inherited.

val input_ghost_color : Color.t prop

Color for "ghost" text (see ghost_text). Default is 0xccccccff. Inherited.

val current_line_bg_color : Color.t prop

Background color of current line (in Textview.textview widget). Inherited.

val click_mask : Color.t prop

Color mask applied on some widgets (buttons) when button is pressed. Default is 0xffffff88. Inherited.

val has_focus : bool prop

Whether a widget has input focus. It means that the is_focus property is true for it and all its parent widgets, and its window has focus too. Default is false.

val is_focus : bool prop

Widget has the input focus in its parent. Default is false.

val focusable : bool prop

Whether a widget can have the input focus. Default is false.

val can_focus : bool prop

Whether the input focus can enter the widget or any of its children. Default is true.

val show_on_focus : bool prop

Whether a widget getting the focus calls self#show. Default is true.

val selected : bool prop

Widget is selected. The way this property is set depends on the widget. Default is false.

val text : string prop

Text contents, used in some widgets (for example Text.label). Inherited.

val glyph : int prop

Glyph contents (unicode codepoint), used in some widgets (for example Text.glyph). Inherited.

val ghost_text : string prop

Ghost text t, i.e. hint text which disappears when user enters some text. Inherited.

val editable : bool prop

Used by some widgets to indicate whether contents is editable (typically text input widgets). Default is true.

val cursor_width : int prop

Used by some widgets (typically text input) to indicate the cursor width in pixels. Default is 2. Inherited.

val cursor_color : Color.t prop

Used by some widgets (typically text input) to indicate the cursor color. Default is Color.red. Inherited.

val active_cursor_color : Color.t prop

Used by some widgets (typically text input) to indicate the active cursor color. Default is Color.red. Inherited.

val scrollbar_width : int prop

Scrollbar width in pixels. Default is 12. Inherited.

val scrollbar_handle_min_size : int prop

Scrollbar handle minimum size in pixels. Default is 40. Inherited.

val scrollbar_handle_color : Color.t prop

Scrollbar handle color. Default is 0x2222dd00. Inherited.

val scrollbar_bg_color : Color.t prop

Scrollbar background color. Default is 0xffffff99. Inherited. Since scrollbar (by now) is displayed over contents, the background should not be opaque.

val selection_mode : selection_mode prop

Selection mode used by some widgets. Default is Sel_multiple.

val orientation : orientation prop

Orientation used by several widgets. Default is Vertical.

val text_valign : text_valign prop

Text vertical alignment for items in Flex.flex widget. Default is Baseline.

val get_font : t -> Tsdl_ttf.Ttf.font

get_font t uses font_desc, bold and italic to returns the corresponding SDL font.

val get_font_for_char : t -> Stdlib.Uchar.t -> Tsdl_ttf.Ttf.font

get_font_for_char t uchar returns the font fn to use for this char (using get_font, and returning fallback font (see Font.add_fallback_font) when character is not available in fn.

val set_font_size : t -> int -> unit

set_font_size t n sets font_desc in t by changing its size to n.

Reading from and writing to JSON

val var_of_string : string -> string option

val set_from_json : 
  ?vars:Yojson.Safe.t Misc.SMap.t ->
  t ->
  Yojson.Safe.t ->
  unit

val wrapper : t Ocf.Wrapper.t

val to_json : t -> Yojson.Safe.t