►GObject Introspection
1 Main interface
gi-ffi
2 Get FFI element
repository
3 Foreign objects
object
3.1 Pointer to object
3.2 Fields
3.3 Properties
4 Signals
connect
5 Alternative interface
pointer
get-properties
set-properties!
5.3.5

GObject Introspection

 (require (planet Kalimehtar/gi-ffi:1:=2))

1 Main interface

This is Gobject FFI.

Usage example:

(define gtk (gi-ffi "Gtk"))
(gtk 'init 0 #f)
(let ([window (gtk 'Window 'new 0)])
  (window 'show)
  (gtk 'main))

Interface with the GObjectIntrospection is based on repositories. Main function is

procedure

(gi-ffi repository-name [version]) → procedure?

  repository-name : string?
  version : string? = ""
Returns interface to repository with name repository-name

2 Get FFI element

procedure

(repository func-name func-arg ...) → any/c

  func-name : (or/c string? symbol?)
  func-arg : any/c
(repository const-name) → any/c
  const-name : (or/c string? symbol?)
(repository enum-name enum-value-name) → exact-integer?
  enum-name : (or/c string? symbol?)
  enum-value-name : (or/c string? symbol?)
(repository class-name constructor-name) → procedure?
  class-name : (or/c string? symbol?)
  constructor-name : (or/c string? symbol?)

This interface takes as a first argument name of foreign object. Name could be string? or symbol?. In both cases it’s allowed to replace "_" with "-". So you can write either "get_name" or ’get-name with the same result.

If first argument is a name of function, then rest arguments are the arguments of the function and it returns result of the function. In example
(define gtk (gi-ffi "Gtk"))
(gtk 'init 0 #f)
gtk_init is called with 0 and null pointer.

If first argument is a name of constant, then it returns value of the constant. For example,

(gtk 'MAJOR-VERSION)

returns 2 for GTK2 or 3 for GTK3.

If first argument is a name of enumeration, then second arguments should be value name. It returns integer value. For example,

(gtk 'WindowType ':toplevel)

Returns 0.

If first argument is a name of class (or struct), then the second argument should be a name of class constructor (in GTK it is usually "new"), rest arguments are the arguments of the constructor.

(define window (gtk 'Window 'new 0))

This call will return a representation of object.

3 Foreign objects

procedure

(object method-name method-arg ...) → any/c

  method-name : (or/c string? symbol?)
  method-arg : any/c

Representation of an object is also a function. First argument of it should be either name of method (string? or symbol?) or special name.

(window 'add button)

will call method "add" with argument "button".

3.1 Pointer to object

To get C pointer to an object call it with "method" :this.

(window ':this)

3.2 Fields

Getting and setting field values are done with :field and :set-field!.
(define entry (gtk 'TargetEntry 'new "ok" 0 0))
 
> (entry ':field 'flags)
0
> (entry ':set-field! 'flags 1)
> (entry ':field 'flags)
1

But you cannot set with :set-field! complex types such as structs, unions or even strings. It is a restriction of GObjectIntrospection.

3.3 Properties

Getting and setting field values are done with :properties and :set-properties!. You may get or set several properties at once.

(define-values (width height) (window ':properties 'width-request 'height-request))
(window ':set-properties! 'width-request 100 'height-request 200)

4 Signals

procedure

(connect object signal-name handler) → void?

  object : procedure?
  signal-name : (or/c symbol? string?)
  handler : (or/c procedure? cpointer?)

5 Alternative interface

If like more traditional interface, you may use gi-ffi/interface module

 (require (planet Kalimehtar/gi-ffi:1:=2/interface))

It provides interface in style of racket/class: send, send/apply, dynamic-send, set-field!, get-field, dynamic-get-field, dynamic-set-field!.

Besides, it provides functional interface for object pointers and properties:

procedure

(pointer object) → cpointer?

  object : procedure?
Returns pointer to object

procedure

(get-properties object property-name ...) → 
any/c ...
  object : procedure?
  property-name : (or/c string? symbol?)

procedure

(set-properties! object    
  property-name    
  property-value ...) → void?
  object : procedure?
  property-name : (or/c string? symbol?)
  property-value : any/c