Module Stk.PropsSource

Properties and their values.

Sourcetype t

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

Properties

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

Sourcetype 'a post_action =
  1. | Resize
  2. | Render
  3. | 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 ().
Sourcemodule Id : Misc.Id

Unique property ids.

Sourcetype 'a prop

A property for values of type 'a.

Sourcemodule Map : sig ... end
Sourcetype 'a transition = start:'a -> stop:'a -> float -> 'a

Transition function. f ~start ~stop r returns the value corresponding to r in the range from start (r=0.0) to stop (r=1.0).

Sourcetype prop_value = ..
Sourceval name : 'a prop -> string

Get property name.

Sourceval inherited : 'a prop -> bool

Get inherited flag.

Sourceval default_value : 'a prop -> 'a option

Get property default value, if any.

Sourceval transition : 'a prop -> 'a transition option

Get property transition function.

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

Get property post action list.

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

Sourceval pp_prop : 'a prop -> Format.formatter -> 'a -> unit

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

Sourcemodule type PT = sig ... end

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

Sourcetype 'a mk_prop = ?after:'a post_action list -> ?default:'a -> ?inherited:bool -> ?transition:'a transition -> 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.
  • inherited (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).
  • transition (default is the transition function of the datatype) indicates a transition function used when a delay is indicated when setting the property.

Property types

Sourcemodule type Prop_type = sig ... end

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

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

Creating a property type from a value description.

Predefined property types

Sourcetype 'a trbl = {
  1. top : 'a;
  2. right : 'a;
  3. bottom : 'a;
  4. left : 'a;
}

Top-right-bottom-left values.

Sourceval trbl : top:'a -> right:'a -> bottom:'a -> left:'a -> 'a trbl
Sourceval trbl_ : 'a -> 'a -> 'a -> 'a -> 'a trbl

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

Sourceval trbl__ : 'a -> 'a trbl

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

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

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

trbl comparison.

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

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

Sourcemodule TInt : PT with type t = int
Sourcemodule PInt : Prop_type with type t = int
Sourceval int_transition : int transition
Sourcemodule PFloat : Prop_type with type t = float
Sourceval float_transition : float transition
Sourcemodule PBool : Prop_type with type t = bool
Sourcemodule PString : Prop_type with type t = string
Sourcemodule PUchar : Prop_type with type t = Uchar.t
Sourcemodule TColor : PT with type t = Color.t
Sourcemodule PColor : Prop_type with type t = Color.t
Sourcemodule PLayer : Prop_type with type t = Layer.t
Sourcemodule TProps : PT with type t = t
Sourcemodule PProps : Prop_type with type t = t
Sourcemodule PTrbl (T : PT) : Prop_type with type t = T.t trbl
Sourceval trbl_transition : 'a transition -> 'a trbl transition
Sourcemodule PTrbl_int : Prop_type with type t = int trbl
Sourcemodule PPair (T1 : PT) (T2 : PT) : Prop_type with type t = T1.t * T2.t
Sourcemodule PTriple (T1 : PT) (T2 : PT) (T3 : PT) : Prop_type with type t = T1.t * T2.t * T3.t
Sourcemodule PList (T : PT) : Prop_type with type t = T.t list
Sourceval list_transition : 'a transition -> 'a list transition
Sourcemodule PPair_float : Prop_type with type t = float * float

Predefined property constructors

Sourceval int_prop : int mk_prop
Sourceval float_prop : float mk_prop
Sourceval color_prop : Color.t mk_prop
Sourceval bool_prop : bool mk_prop
Sourceval string_prop : string mk_prop
Sourceval uchar_prop : Uchar.t mk_prop
Sourceval font_desc_prop : Font.font_desc mk_prop
Sourceval layer_prop : Layer.t mk_prop
Sourceval int_trbl_prop : int trbl mk_prop
Sourceval color_trbl_prop : Color.t trbl mk_prop
Sourceval float_pair_prop : (float * float) mk_prop
Sourceval props_prop : t mk_prop
Sourceval keystate_prop : Key.keystate mk_prop

Property-to-value maps

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

Sourceval empty : unit -> t

Returns a new empty property map.

Sourceval dup : t -> t

dup t returns a copy of t.

Sourceval default : t

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

Sourceval create : unit -> t

Create a new property map with default values.

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

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

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

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

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

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

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

Sourceval clear : t -> unit

clear t removes all properties in t.

Sourceval compare : t -> t -> int

Property map comparison.

Sourceval to_string : t -> string

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

Sourceval pp : Format.formatter -> t -> unit

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

Sourceval merge : ?use_inherited:bool -> t -> t -> t

merge t1 t2 returns a new !t using map merging function (see Map.S.merge). The optional argument use_inherited (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_inherited = false, p is given value v in the new map. When use_inherited = true, then p is given value v in the new map only if p was defined with ~inherited:true (which is the default, see mk_prop).

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

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

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

Sourcetype text_valign =
  1. | Baseline
  2. | Sub
  3. | Super
  4. | Top
  5. | Text_top
  6. | Middle
  7. | Bottom
  8. | Text_bottom
Sourcetype selection_mode =
  1. | Sel_none
  2. | Sel_single
  3. | Sel_browse
  4. | Sel_multiple
Sourcetype orientation =
  1. | Vertical
  2. | Horizontal
Sourceval string_of_orientation : orientation -> string
Sourceval padding : int trbl prop

Padding of a widget in pixels.

Sourceval margin : int trbl prop

Margin of a widget in pixels.

Sourceval border_width : int trbl prop

Border width of a widget in pixels.

Sourceval border_color : Color.t trbl prop

Border color of a widget.

Sourceval border_color_hover : Color.t trbl prop

Border color of a widget when mouse cursor in hovering.

Sourceval border_color_selected : Color.t trbl prop

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

Sourceval border_color_focused : Color.t trbl prop

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

Sourceval hexpand : int prop

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

Sourceval vexpand : int prop

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

Sourceval visible : bool prop

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

Sourceval sensitive : bool prop

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

Sourceval insensitive_color_mask : Color.t prop

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

Sourceval hfill : bool prop

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

Sourceval vfill : bool prop

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

Sourceval 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).

Sourceval valign : float prop

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

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

Sourceval height : int prop

Same as width but for... height.

Sourceval max_width : int prop

Maximum width. This property may be used by container to ask their childre for additional constraint (not used by now). Negative value should be considered as no value.

Sourceval max_height : int prop

Maximum height. This property may be used by container to ask their childre for additional constraint. (only used by Clist.column by now). Negative value should be considered as no value.

Sourceval fill : bool prop

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

Sourceval bg_fill_borders : bool prop

Whether background color should cover borders. Default is false.

Sourceval font_desc : Font.font_desc prop

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

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

Sourceval italic : bool prop

Same as bold but for italic. Inherited.

Sourceval fg_color : Color.t prop

Foreground color, use for example for text. Inherited.

Sourceval fg_color_hover : Color.t prop

Foreground color when mouse is hovering. Inherited.

Sourceval fg_color_selected : Color.t prop

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

Sourceval fg_color_focused : Color.t prop

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

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

Sourceval bg_color_hover : Color.t prop

Foreground color when mouse is hovering. Inherited.

Sourceval bg_color_selected : Color.t prop

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

Sourceval bg_color_focused : Color.t prop

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

Sourceval selection_fg_color : Color.t prop

Foreground color for selection in some widgets (like Textview.textview).

Sourceval selection_bg_color : Color.t prop

Background color for selection in some widgets (like Textview.textview).

Sourceval input_bg_color : Color.t prop

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

Sourceval input_ghost_color : Color.t prop

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

Sourceval current_line_bg_color : Color.t prop

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

Sourceval click_mask : Color.t prop

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

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

Sourceval is_focus : bool prop

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

Sourceval focusable : bool prop

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

Sourceval can_focus : bool prop

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

Sourceval show_on_focus : bool prop

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

Sourceval selected : bool prop

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

Sourceval text : string prop

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

Sourceval glyph : int prop

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

Sourceval ghost_text : string prop

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

Sourceval editable : bool prop

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

Sourceval cursor_width : int prop

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

Sourceval cursor_color : Color.t prop

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

Sourceval active_cursor_color : Color.t prop

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

Sourceval scrollbar_width : int prop

Scrollbar width in pixels. Default is 12. Inherited.

Sourceval scrollbar_handle_min_size : int prop

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

Sourceval scrollbar_handle_color : Color.t prop

Scrollbar handle color. Default is 0x2222dd00. Inherited.

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

Sourceval selection_mode : selection_mode prop

Selection mode used by some widgets. Default is Sel_multiple.

Sourceval orientation : orientation prop

Orientation used by several widgets. Default is Vertical.

Sourceval text_valign : text_valign prop

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

Sourceval get_font : t -> Font.font

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

Sourceval get_font_for_char : t -> Uchar.t -> Font.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.

Sourceval set_font_size : t -> int -> unit

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

Sourceval set_font_italic : t -> bool -> unit

set_font_italic t b sets font_desc in t by changing its italic flag to b.

Sourceval set_font_bold : t -> bool -> unit

set_font_bold t b sets font_desc in t by changing its bold flag to b.

Sourceval set_font_family : t -> string -> unit

set_font_family t s sets font_desc in t by changing its font family to s.

Sourceval set_font_underline : t -> bool -> unit

set_font_underline t b sets font_desc in t by changing its underline flag to b.

Sourceval set_font_strikethrough : t -> bool -> unit

set_font_strikethrough t b sets font_desc in t by changing its strikethrough flag to b.

Sourceval set_font_kerning : t -> bool -> unit

set_font_kerning t b sets font_desc in t by changing its kerning flag to b.

Sourceval set_font_outline : t -> int -> unit

set_font_outline t n sets font_desc in t by changing its outline to n.

Reading from and writing to JSON

Sourceval var_of_string : string -> string option
Sourceval set_from_json : ?vars:Yojson.Safe.t Smap.t -> t -> Yojson.Safe.t -> unit
Sourceval wrapper : t Ocf.Wrapper.t
Sourceval to_json : t -> Yojson.Safe.t