Properties

A property is a named parameter of a class or interface whose attributes determine its type and modes of use (readable, writable, construct-only).

The special structure Property provides support for working with properties in a type safe way. The the type Property.init_t is used to specify initial properties for use with GObject.Object.new as described by Initializing properties on object construction below.

Referring to properties

In GObject, a property name is string of ASCII letters and digits with words separated by a hyphen (or underscore) where the first word starts with a letter. The SML interface provides an abstract value for each property. For a property “some-property-name” of a class or interface Type in a namespace Namespace, the hierarchical SML name is Namespace.Type.somePropertyNameProp.

For example, the property “always-show-image” of the class Button in the namespace Gtk is Gtk.Button.alwaysShowImageProp

In order to provide a type-safe and mode-safe interface for using properties, each property has an SML specification constraining the instance type that provides the property, the type of the property and access to the property.

The specification of Namespace.Type.somePropertyNameProp in the signature NAMESPACE_TYPE has the form: 

val somePropertyNameProp : (instanceType, getType, setType, initType) Property.t

where

instanceType

is:

  • 'a class for a class, which allows an instance of the class or any subclass of the class;

  • t for an interface;

getType

is unit -> readType if the property is readable and, otherwise, is unit;

setType

is writeType -> unit if the property is writable and not contruct-only and, otherwise, is unit;

initType

is writeType -> unit if the property is writable and, otherwise, is unit;

where

readType

is the type of the value read from the property;

writeType

is the type of the value written to the property.

The term construct-only means that the property is writable only at the time of object construction.

For example, in the signature GTK_WINDOW, the specification of the readable and writable property Gtk.Window.transientForProp is 

val transientForProp : ('a class, unit -> base class option, 'b class option -> unit, 'b class option -> unit) Property.t

and the specification of the readable, writable and construct-only property Gtk.Window.typeProp is 

val typeProp : ('a class, unit -> window_type_t, unit, window_type_t -> unit) Property.t

and the specification of the write-only property Gtk.Window.startupIdProp is 

val startupIdProp : ('a class, unit, string option -> unit, string option -> unit) Property.t

and the specification of the read-only property Gtk.Window.hasToplevelFocusProp is 

val hasToplevelFocusProp : ('a class, unit -> bool, unit, unit) Property.t

Accessing properties

Reading

For a property “a” of a class ClassNamespace.Class, the value of the property in an object obj is given by 

Property.get ClassNamespace.Class.aProp obj

For a property “a” of an interface IfaceNamespace.Iface implemented by the class ClassNamespace.Class, the value of the property in the object obj is given by either converting obj: 

Property.get IfaceNamespace.Iface.aProp (ClassNamespace.Class.asIface obj)

or converting the property:

Property.get (Property.conv ClassNamespace.Class.asIface IfaceNamespace.Iface.aProp) obj

The above expressions do not type check if any of the following are satisfied:

  • obj is not an instance of the class ClassNamespace.Class;

  • the property is not readable.

Writing

For a property “a” of a class ClassNamespace.Class, the value of the property in an object obj is set to x by 

Property.set ClassNamespace.Class.aProp x obj

For a property “a” of an interface IfaceNamespace.Iface implemented by the class ClassNamespace.Class, the value of the property in the object obj is set to x by either converting obj: 

Property.set IfaceNamespace.Iface.aProp x (ClassNamespace.Class.asIface obj)

or converting the property:

Property.set (Property.conv ClassNamespace.Class.asIface IfaceNamespace.Iface.aProp) x obj

The above expressions do not type check if any of the following are satisfied:

  • obj is not an instance of the class ClassNamespace.Class;

  • the property is not writable;

  • the property is construct-only;

  • the type of x is not an instance of the type of the property.

Initializing properties on object construction

Using GObject.Object.new, the value of a property “a” of a class ClassNamespace.Class is initialized to x on construction of an instance of a class C as follows: 

val obj =
  GObject.Object.new
    (
      CClass.t,
      [
        …,
        Property.init ClassNamespace.Class.aProp x,
        …
      ]
    )

The value of a property “a” of an interface IfaceNamespace.Iface implemented by a class ClassNamespace.Class is initialized to x on construction of an instance of a class C as follows: 

val obj =
  GObject.Object.new
    (
      CClass.t,
      [
        …,
        Property.init (Property.conv ClassNamespace.Class.asIface IfaceNamespace.Iface.aProp) x,
        …
      ]
    )

The above expressions do not type check if any of the following are satisfied:

  • C is neither equal to nor a subclass of ClassNamespace.Class;

  • the property “a” is not writable;

  • the type of x is not an instance of the type of the property.