Library Coverage

Of the entities provided by a library, many are not intended for introspection, that is to say they are not intended for use from languages other than C, and are therefore excluded from the SML interface. Such entities are annotated with (skip) in the gtk-doc comment in the source code and with ‘[skip]’ in the reference manual.

An SML interface does not usually include all library entities intended for introspection. In most cases, entities are excluded because they are not wanted in the SML interface and this is not a limitation. For example, the following should not be in the SML interface, and are excluded:

  • constants whose values are platform-dependent;

  • functions below the level of abstraction in the SML interface, such as functions relating to memory management;

  • private fields of structs.

However, some entites are excluded due to:

  • constraints relating to use of SML and

  • missing support in the Giraffe code generator, which is still under development.

These limitations are described in the sections below.

SML Limitations

This section describes limitations are that inherent in using SML.

Variadic functions

A variadic function (and function that has an argument of type va_list) cannot be supported because there is no SML type for such a function. This is not a significant limitation in practice because the difficulties binding to such functions from many languages are recognised and alternative non-variadic functions are usually available. Some variadic functions are annotated with (skip) to indicate that they are not intended for introspection.

Giraffe Limitations

This section describes limitations due to missing support in the Giraffe code generator.

Types

Currently the code generator does not yet support the following GObject types:

  • array types GLib.Array, GLib.ByteArray and GLib.PtrArray (note that ordinary C arrays are supported)

  • list types GLib.List and GLib.SList

  • hash table type GLib.HashTable

  • callback types except GLib.SourceFunc, GLib.IOFunc, GLib.ChildWatchFunc and GLib.SpawnChildSetupFunc

  • union types except Gdk.Event

Any type, alias, function, property or signal that depends on an unsupported type is unsupported and is excluded from the SML interface. Support for the above types is expected to be added in future.

There is no support for creating new GObject types from SML. For example, it is not possible to use SML to create a derived class or an interface. Also, there is no support for overriding a virtual function. To date, such support has not been required in Giraffe Library.

Signals

There is support for handling the emission of a signal from an object (instance) but there is no support for:

  • handling a signal on all instances of an object (or interface) type, i.e. overriding the class closure

  • emission hooks

To date, such support has not been required in Giraffe Library.