GNU G-Golf Reference Manual ¶

Naming Conventions ¶

G-Golf is, or at least tries to be, consistent in the way ‘things’ are being named, whether the functionality being ‘exposed’ is from an imported GNOME library or is part of a G-Golf’s core reference module.

GNOME Libraries ¶

When G-Golf imports a GNOME library, its classes, properties, methods, functions, types and constant are renamed, which is achieved by calling g-name->class-name and g-name->name appropriately.

As described in their respective documentation entry, as well as in the Customizing G-Golf section, G-Golf offers a way to either ignore or partially customize the renaming process.

  ^_ Classes

GNOME libraries classes are imported as GOOPS classes (the Guile Object Oriented System, see GOOPS in The GNU Guile Reference Manual), and their respective name is given by the result of calling g-name->class-name, for example:

GtkWindow ⇒ <gtk-window>
ClutterActor ⇒ <clutter-actor>
WebKitWebView ⇒ <webkit-web-view>(5)
...

  ^_ Properties

GNOME libraries class properties are imported as GOOPS class slots, and their respective name is given by calling g-name->name. Each property slot defines an init-keyword and an accessor, following G-Golf’s accessors naming conventions (See GOOPS Notes and Conventions).

As an example, the <gtk-label> class has a label slot, with the #:label init-keyword and !label accessor.

  ^_ Methods

GNOME libraries methods are imported as GOOPS methods, the name of which is obtained by calling g-name->name.

Unless otherwise specified (see Customization Square - GI Method Short Name Skip), as it imports a GI typelib, G-Golf creates a method short name for each imported method, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method long name.

For example, the <gtk-label> class, which defines a gtk-label-get-text method, would also define, using G-Golf’s default settings, an get-text method.

  ^_ Functions

GNOME libraries functions are imported as procedures, renamed by calling g-name->name. For example:

gtk_window_new ⇒ gtk-window-new
clutter_actor_new ⇒ clutter-actor-new
...

  ^_ Enums, Flags and Boxed types

GNOME libraries enums, flags and boxed types are renamed by calling g-name->name (and cached, See Cache Park section).

Enum and flag type members are renamed by calling g-name->name. To illustrate, here is an example:

,use (g-golf)

(gi-import-by-name "Gtk" "WindowPosition")
⇒ $2 = #<<gi-enum> 5618c7a18090>

(describe $2)
-| #<<gi-enum> 5618c7a18090> is an instance of class <gi-enum>
-| Slots are:
-|      enum-set = ((none . 0) (center . 1) (mouse . 2) (center-always . 3) (center-on-parent . 4))
-|      g-type = 94664428197600
-|      g-name = "GtkWindowPosition"
-|      name = gtk-window-position

G-Golf Core Reference ¶

  ^_ Procedures and Variables

G-Golf procedure names that bind a Glib, GObject or GObject Introspection functions (always) use the ‘original’ name, except that every _ (underscore) occurrence is replaced by a - (hyphens). For example:

g_main_loop_new
⇒ g-main-loop-new

g_irepository_get_loaded_namespaces
⇒ g-irepository-get-loaded-namespaces

G-Golf also comes with its own set of procedures, syntax and variables, aimed at not just reading a typelib, but making its functionality available from Guile. Naming those, whenever possible, is done following the ‘traditional way’ scheme name its procedures, syntax and variables. For example:

• procedure names that start with call-with-input-, call-with-output- followed by a Glib, GObject. Gdk or GI type, such as:

  call-with-input-typelib
  

• syntax names that start as with- followed by a Glib, GObject, Gdk or GI type, such as:

  with-gerror
  

When an ‘obvious’ name can’t be find ‘on its own’, or to avoid possible conflict outside G-Golf⁶, then the name starts using a g- prefix (when the procedure context is GNOME in general) or gi- prefix (when the procedure context is GI more specifically), and equally for variables, using %g- or %gi-.

  ^_ Types and Values

G-Golf variables that bind Glib, GObject and GI types and values use the same convention as for procedures, except that they always start with % and their original type names are transformed by the same rules that those applied when calling g-studly-caps-expand.

For example, from the GIBaseInfo section:

GIInfoType
⇒ %gi-info-type

GOOPS Notes and Conventions ¶

G-Golf extensively uses GOOPS, the Guile Object Oriented System (see GOOPS in The GNU Guile Reference Manual), in a way that is largely inspired by Guile-Gnome.

Here are some notes and the GOOPS conventions used by G-Golf.

  ^_ Slots are not Immutable

Except for virtual slots, there is currently no way to effectively prohibit (block) a user to mutate a goops class instance (one can always use slot-set! instance slot-name value)⁷.

However, you will find a few places in this manual using phrase excerpts like ‘instances of this <class> are immutable’, or ‘this <slot> is immutable’. In these contexts, what is actually meant is that these (insances or slots) are not meant to be mutated. Doing so is not only at your own risks, but likely to cause a crash.

  ^_ Merging Generics

In G-Golf, generic functions are always merged (see Merging Generics in The GNU Guile Reference Manual).

Users are (highly) recommended to do the same, in their repl, application/library modules and script(s). In its modules - those that import (oop goops) - G-Golf uses the following duplicate binding handler set:

  #:duplicates (merge-generics
		replace
		warn-override-core
		warn
		last)

In a repl or in scripts, these maybe set - after importing (oop goops) - by calling default-duplicate-binding-handler:

(use-modules (oop goops))

(default-duplicate-binding-handler
    '(merge-generics replace warn-override-core warn last))

G-Golf regular users should consider adding the above lines to their $HOME/.guile or, when working in a multi-user environmet, should consider adding those lines the file named init.scm in the so-called Guile global site directory⁸, here (evaluate the following expression in a terminal): guile -c "(display (%global-site-dir))(newline)".

  ^_ Accessors Naming Convention

In G-Golf, all slots define an accessor (and no getter, no setter), the name of which is the slot-name prefixed using !. For example:

(define-class <gtype-class> (<class>)
  (info #:accessor !info
        #:init-keyword #:info)
  ...)

The principal reasons are (not in any particular order):

• It is a good idea, we think, to be able to visually (and somehow immediately) spot and distinct accessors from the rest of the scheme code your are looking at or working on.
  
  
• Accessors are exported, and with this convention, we almost certainly avoid all ‘name clashes’ with user namespaces, that otherwise would be extremelly frequent⁹.
  
  
• Users quite often want or even need to cash slot values in a closure. By using this ! prefixing convention, we leave users with the (quite usefull) possibility to name their local variables using the respective slot names.
  
  
• Accessors may always be used to mutate a slot value (except for virtual slots, for which you can ‘block’ that feature), like in (set! (!name an-actor) "Mike"). In scheme, it is a tradition to signal mutability by postfixing the procedure name using the ! character.
  
  
• Accessors are not procedures though, there are methods, and to effectively mutate a slot value, one must use set!. Therefore, prefixing makes sence (and preserves the first reason announced here, where posfixing would break it).
  
  
• We should also add that we are well aware that Java also prefixes its accessors, using a . as its prefix character, but GOOPS is radically different from Java in its design, and therefore, we really wanted another character.

Configuring Guile for G-Golf ¶

The following description and content is shared and identical to the ‘Merging Generics’ heading of the previous section.

It is repeated it here, under its own section entry, so that it appears in the table of content and grab all users attention - those who do not follow our recommendation may void their warranty or poison their cat.

  ^_ Merging Generics

In G-Golf, generic functions are always merged (see Merging Generics in The GNU Guile Reference Manual).

Users are (highly) recommended to do the same, in their repl, application/library modules and script(s). In its modules - those that import (oop goops) - G-Golf uses the following duplicate binding handler set:

  #:duplicates (merge-generics
		replace
		warn-override-core
		warn
		last)

In a repl or in scripts, these maybe set - after importing (oop goops) - by calling default-duplicate-binding-handler:

(use-modules (oop goops))

(default-duplicate-binding-handler
    '(merge-generics replace warn-override-core warn last))

G-Golf regular users should consider adding the above lines to their $HOME/.guile or, when working in a multi-user environmet, should consider adding those lines the file named init.scm in the so-called Guile global site directory¹⁰, here (evaluate the following expression in a terminal): guile -c "(display (%global-site-dir))(newline)".

Customizing G-Golf ¶

G-Golf offers a series of customization interfaces for the following domains: (•) Name Transformation - how things are being named as they are being imported;(•) Strip Boolean Result - should G-Golf elude (some) function and method call returned value when it is #t and raise an exception if the returned value is #f; (•) Method Short Name - should G-Golf create them or not; (•) Syntax Name Protect - how G-Golf should address syntax name ‘clash’ against method short name.

  ^_ Name Transformation

When G-Golf imports a GNOME library, its classes, properties, methods, functions, types and constants are renamed (See Naming Conventions), mainly to (a) avoid ‘Camel Case’, (b) surround class names by ‘<’ ‘>’ and (c) replace ‘_’ (underscore) occurrences using the ‘-’ (hyphen) character instead.

G-Golf offers - through a series of interfaces to get, check, add, remove and reset two (distinct) associative lists - a way to either ignore or partially customize the renaming process.

See Customization Square - GI Name Transformation.

  ^_ Strip Boolean Result

Some GI typelib functions and methods that (1) have at least one 'inout or 'out argument(s) and (2) return either #t or #f, solely to indicate that the function or method call was successful or not.

G-Golf offers - through a series of interfaces to get, check, add, remove and reset a list of such function or methods names - to instead elude the function or method returned value when it is #t and raise an exception if the returned value is #f.

See Customization Square - GI Strip Boolean Result.

  ^_ Method Short Name

By default, as it imports a GI typelib, G-Golf creates a method short name for each imported method, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name.

Users may change this default and skip the method short name creation step, either individually or for all GI imported methods.

See Customization Square - GI Method Short Name Skip.

  ^_ Syntax Name Protect

When G-Golf creates a method short name, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name, it may lead to a ‘name clash’, with an already defined procedure or syntax.

Both type of ‘name clash’ need to be addressed, which G-Golf does, automatically, but special care must be taken when that happens against a syntax name, a process that you may custom to your own taste.

See Customization Square - GI Syntax Name Protect.

SXML Support - Emacs users ¶

G-Golf offers two files to support editing and maintaining GtkWidget template and GtkBuilder ui (xml) files as sxml files instead. Currently, these files are in the examples/adw-1/adw1-demo/ui directory.

sxml-ui.el

Emacs users should import this file in their .emacs file.

This is an attempt to provide both indentation and font-lock support, so ui files editing becomes a more pleasant experience. It is a first draft and definitely an experimental attempt. Better then nothing (much better imo), but suggestions to improve this first and quite ’naive’ draft would be welcome.

Makefile

Offered as an example of the simplest possible way to convert all *.scm files of a directory to their corresponding *.ui files.

Hello World! ¶

Following the tradition, let’s first see how the often seen ‘Hello World!’ familiar, minimal, friendly greeting program looks like in G-Golf:

;; Load Gtk
(use-modules (g-golf))
(gi-import "Gtk")

;; When the application is launched..
(define (activate app)
  ;; - Create a new window and a new button
  (let ((window (make <gtk-application-window>
                  #:title "Hello"
                  #:application app))
        (button (make <gtk-button>
                  #:label "Hello, World!")))
    ;; - Which closes the window when clicked
    (connect button
             'clicked
             (lambda (b)
               (close window)))
    (set-child window button)
    (show window)))

;; Create a new application
(let ((app (make <gtk-application>
             #:application-id "org.example.GtkApplication")))
  (connect app 'activate activate)
  ;; Run the application
  (run app 0 '()))

Providing you successfully installed G-Golf, you may run the above code in a Guile REPL (Read Evaluate Print Loop)¹², which as described in its comments, starts the application, resulting in opening a (small) window named ‘Hello’, with one button named ‘Hello, World!’, that will close the window when clicked.

Example 1: Hello World! (1)

Wonderful! But you probably rightfully think that it was a bit slow. This is not because G-Golf nor Guile are slow, but because the Gtk namespace is absolutely huge, and although we only use a few components, we asked to import the all namespace. We will see how to only selectively import the namespace components we need in the next section, but let’s first try the following, (a) close the window and (b) re-evaluate the last expression:

(let ((app (make <gtk-application>
             #:application-id "com.example.GtkApplication")))
  (connect app 'activate activate)
  (run app 0 '()))

Great! Now, the application was launched instantaneously. Since everything it needs was already imported, the time it takes to execute the code is nearly identical to the time it would take to execute the same code from C - if you accurately measure the execution time in both situation, you would see a difference in the results, but small enough that it is safe to declare it imperceptible.

It would be beyond the scope of this introduction to describe the <gtk-application> / g-application-run instance creation and run mechanism in detail, for this, please consult and carefully read their respective entries in the Gtk and Gio reference manuals.

The GNOME team also maintains a wiki called HowDoI, and two pages are dedicated to this subject: HowDoI GtkApplication and HowDoI GtkApplication/CommandLine.

This said, let’s just make a few hopefully usefull comments to newcomers:

• as you can see, we do not need to call gtk-init, it is done automatically (more on this in the GtkApplication section of the Gtk Reference Manual);
  
  
• the #:application-id init-keyworkd is optional, although recommended, and when passed, the application ID must be valid (more on this below).

  ^_ Is your application ID valid?

The set of rules that apply and determine if an Application Identifier is valid is fully described in the Gio Reference Manual, here.

In G-Golf, you may check if your application ID is valid by calling g-application-id-is-valid¹³, for example:

(g-application-id-is-valid "com.example.GtkApplication")
⇒ #t

(g-application-id-is-valid "RedBear")
⇒ #f

If you pass an invalid application ID to a <gtk-application> instance creation, you’ll be noted with a message similar to this:

(process:30818): GLib-GIO-CRITICAL **: 21:58:52.700: g_application_set_application_id: assertion ’application_id == NULL || g_application_id_is_valid (application_id)’ failed

  ^_ Great, but could we speed things up a little?

Yes we can! In the next section, as promised above, we will walk you through Selective Import, used to reduce the time G-Golf has to spend importing the typelib(s) that your application requires.

Selective Import ¶

To selectively import namespace components, use gi-import-by-name, which takes two arguments, a namespace and a (component) name. Let’s try on our minimal ‘Hello World!’ example and see how it goes. All we need to do, is to substitute the (gi-import "Gtk") call by the following expression:

(for-each (lambda (name)
            (gi-import-by-name "Gtk" name))
    '("Application"
      "ApplicationWindow"
      "Button"))

With this change, everything else kept equal, if you (quit and) restart Guile, evaluate the updated ‘Hello World!’ example code, you will notice how the elapse time before the application window appears is now substantially reduced, compared to the version that imports the all Gtk namespace. Substantially reduced but … not instantaneous: well, that is expected!

Although we only import a few Gtk namespace components, three GObject classes in this example, G-Golf will import those classes, their interface(s) if any, methods, enums, flags ... and do the same for their parent class, recursively. For those three classes only, G-Golf actually has to import (and dynamically define) tens of classes, interfaces, enums, flags … as well as hundreds of methods and procedures.

G-Golf will also import classes, interfaces and their dependencies (enums, flags … recursively as well …) from other namespace if necessary. We already have an illustration of this, both with the original example and the change we just made: although we do not explicitly import the GApplication class from the Gio namespace, G-Golf did that for us, and so we may call run - which is the short method name for g-application-run - as if we did manually import it.

Both the namespace and name arguments are case sensitive. The name argument is used to retrieve the typelib Base Info that holds the metadata of the introspectable library element it represents. Although there are a some exceptions, it is generally derived from and obtained by dropping the namespace prefix (without its version number if any) out of the original name. Here are a few more examples, organized by namespace:

Gtk

GtkWindow -> Window
gtk_init -> init
gtk_main -> main
gtk_main_quit -> main_quit
…

WebKit2

WebKitWebView -> WebView
WebKitLoadEvent -> LoadEvent
…

…

  ^_ Cool, selective import, but what about scripting?

Right! The ’Hello World!’ example we have presented so far can only be run interactively.

In the next section, we will see how we may turn it - and any other example or application - so it can be run as a script.

Scripting ¶

A Guile script is simply a file of Scheme code with some ‘extra information at the beginning’ which tells the OS (operating system) how to invoke Guile, and then tells Guile how to handle the Scheme code.

  ^_ Invoking Guile

It would be beyond the scope of this manual to expose the numerous ways one can define and invoke a Guile script, for a complete description of the subject, see Guile Scripting in The GNU Guile Reference Manual.

In G-Golf, both provided examples and in this manual, we use the so called ‘for maximum portability’ scripting technique, which is to invoke the shell to execute guile with specified command line arguments.

Here is what we do:

#! /bin/sh
# -*- mode: scheme; coding: utf-8 -*-
exec guile -e main -s "$0" "$@"
!#

In the above, the first line is to specify which shell will be used to interpret the (OS part of the) ‘extra information at the beginning’ of the script.

The second line is optional (and a comment from a shell point of view), that we use it to inform emacs (should you use emacs to edit the file) that despite the ‘extra information at the beginning’ (and the possible lack of filename extension in the script name), it should use the scheme mode as the script editing buffer mode.

The third line tells the shell to execute guile, with the following arguments:

-e main

after reading the script, apply main to command line arguments

-s "$0"

load the source code from "$0" (which by shell rules, is bound to the fullname of the script itself)

"$@"

the command line arguments

Note that the top level script lines may contain other declaration(s), like environment variable definitions. Suppose you would like to be warned if your script uses any deprecated guile functionality. In this case, you add the following export GUILE_WARN_DEPRECATED="detailed" declaration, before the exec guile … call, like this:

#! /bin/sh
# -*- mode: scheme; coding: utf-8 -*-
export GUILE_WARN_DEPRECATED="detailed"
exec guile -e main -s "$0" "$@"
!#

  ^_ Extra Guile information

Within the context of a G-Golf script, two other things must be taken care of - in addition to the (use-modules (g-golf)) step - so that the script runs fine: (1) set-up Guile so that generic functions are merged; (2) import (all) typelib element(s) at expand load eval time.

In a repl or in scripts, (1) is achieved by importing the (oop goops) module and calling default-duplicate-binding-handler¹⁴.

In Guile, (2) is achieved by calling the eval-when syntax¹⁵.

Now, bear with us :), since (2) will define generic functions and/or add methods to existing generic functions, we must make sure the (1) not only preceeds (2), but also happens at expand load eval time.

With all the above in mind, here is how the extra Guile information looks like, for our ‘Hello World!’ script example:

(eval-when (expand load eval)
  (use-modules (oop goops))

  (default-duplicate-binding-handler
    '(merge-generics replace warn-override-core warn last))

  (use-modules (g-golf))

  (for-each (lambda (name)
              (gi-import-by-name "Gtk" name))
      '("Application"
        "ApplicationWindow"
         "Button")))

  ^_ A Hello World! script

Let’s put all this together, and while doing this, enhance a little our original example.

Here is what we propose to do: (a) add a GtkLabel, (b) use a GtkBox and see how to declare its margins and orientation, (c) specify a default width and height for our application window, and (d) see how we can tell the label to horizontally and vertically expand, so it occupies the extra vertical space, while keeping the button to its minimal vertical size.

Joining (1), (2) and the small enhancement, our ‘Hello World!’ script now looks like this:

#! /bin/sh
# -*- mode: scheme; coding: utf-8 -*-
exec guile -e main -s "$0" "$@"
!#


(eval-when (expand load eval)
  (use-modules (oop goops))

  (default-duplicate-binding-handler
    '(merge-generics replace warn-override-core warn last))

  (use-modules (g-golf))

  (for-each (lambda (name)
              (gi-import-by-name "Gtk" name))
      '("Application"
        "ApplicationWindow"
        "Box"
        "Label"
        "Button")))


(define (activate app)
  (let ((window (make <gtk-application-window>
                  #:title "Hello"
                  #:default-width 320
                  #:default-height 240
                  #:application app))
        (box    (make <gtk-box>
                  #:margin-top 6
                  #:margin-start 12
                  #:margin-bottom 6
                  #:margin-end 6
                  #:orientation 'vertical))
        (label  (make <gtk-label>
                  #:label "Hello, World!"
                  #:hexpand #t
                  #:vexpand #t))
        (button (make <gtk-button>
                  #:label "Close")))

    (connect button
	     'clicked
	     (lambda (b)
               (close window)))

    (set-child window box)
    (append box label)
    (append box button)
    (show window)))


(define (main args)
  (let ((app (make <gtk-application>
               #:application-id "org.gtk.example")))
    (connect app 'activate activate)
    (let ((status (run app 0 '())))
      (exit status))))

If you save the above in a file, say hello-world, then chmod a+x hello-world and launch the script, ./hello-world, here is what you’ll get on the screen:

Example 2: Hello World! (2)

  ^_ A last few comments

We need to make a last few comments, that also applies and will be further addressed in the next section.

Desktop Entry

If you are running a GNOME desktop, you probably noticed that in the GNOME menu bar, the application menu entry for our ‘Hello World!’ script is org.gtk.example (not Hello). This is because we’re missing a Desktop Entry. We will see how to create and install a Desktop Entry in the next section.

Command Line Arguments

As described in the first part of this section, we use the so called ‘for maximum portability’ scripting technique, and more precisely, the following incantation:

exec guile -e main -s "$0" "$@"

In the above, the last argument refers to the the command line arguments. It is actually optional, but when used, they are passed to the main (entry point) script procedure.

However, as you may have noticed, we do not pass those (if any) to the Gtk application, which we launch using (run app 0 '()).

This is intentional: (a) we (want to) always use the same incantation to invoke Guile - and sometimes. may quiclky hack something using additional debug args on the scheme side only …; (b) you may only pass those arguments to the Gtk application if you have defined the signal callback(s) to handle them.

If you pass the command line arguments to a Gtk application that does not define the appropriate signal callback procedure to handle them, you’ll get an error message in the terminal (and the application won’t be launched).

To illustrate, let’s change the g-application-run call of our script, so it becomes (run app (length args) args), then try to launch it, passing a few (fake) arguments, here is what happens:

./hello-world 1 2 3
-| (hello-world:216198): GLib-GIO-CRITICAL **: 22:26:41.135: This application can not open files.

And as mentioned above, the application is not launched.

Although scripts may (also) accept and pass command line argument(s) to the Gtk application or dialog they define, we will see how to handle those in the next section, Building Applications.

Building Applications ¶

G-Golf on Mobile Devices ¶

Import ¶

G-Golf Import interfaces.
Importing GNOME libraries.

Procedures ¶

gi-import

gi-import-by-name

Description ¶

The G-Golf GIR namespace (Typelib) import interfaces.

Procedures ¶

Procedure: gi-import namespace #:key (version #f) ¶

Returns nothing.

Imports the namespace GIR Typelib and exports its interface. For example:

,use (g-golf
(gi-import "Clutter")

The namespace is a case sensitive string. It is an error to call this procedure using an invalid namespace.

The optional #:version keyword argument may be used to require a specific namespace version, otherwise, the latest will be used.

This procedure is certainly one of the first thing you will want to try and use, but it has a cost: you will not ‘feel it’ if the number of objects in namespace is relatively small, but importing the "Gtk" namespace, on a laptop equiped with a i5-2450M CPU  2.50GHz × 4 and 6GB of memory takes nearly 2 seconds.

So, either early in the development cycle, or when your application is more stable, at your best convenience, you may consider making a series of selective import instead, see gi-import-by-name here below.

Procedure: gi-import-by-name namespace name #:key (version #f) (force? #f) (with-method #t) (allow-constant? #f) ¶

Returns the object returned by gi-import-info called upon the GIBaseInfo info named name in namespace. The namespace and name arguments are case sensitive. It is an error to call this procedure using an invalid namespace or name.

The optional #:version keyword argument may be used to require a specific namespace version, otherwise, the latest will be used.

The optional #:force? keyword argument is required to import object(s) from the GLib and GObject namespaces, as G-Golf won’t allow any import from those by default (due to bootsrap reasons, a very important part of those namespaces are manually imported, see the GLib and GObject sections of the G-Golf Core Reference parts of the manual). As a user, you should normally not have to import for neither GLib nor GObject (if you think you do, ask for help, either by email or on irc), unless you really know what you are doing, this may corrupt your g-golf session/environment - you have been warned.

The optional #:with-method keyword argument (which is #t by default) is passed to the gi-import-enum, gi-import-flags and gi-import-struct. When #:with-method is #f, then the enum, flags or struct info will be imported without their respective methods.

The optional #:allow-constant? keyword argument is required to import constants, as by default, G-Golf doesn’t not import any constants, from any namespace. The reason is there are (far) too many and most are not useful for language bindings, but of course there are exception(s), such as (for example) the Gdk KEY_* constants, required to add shortcuts to your application. Here is an example, an excerpt from the (pages tab-view tab-view-demo-window) module (distributed with G-Golf, in the examples/adw-1/demo directory):

(define (install-shortcuts tab-view-demo-window)
  (let ((controller (make <gtk-shortcut-controller>)))
    (set-scope controller 'managed)
    (add-controller tab-view-demo-window controller)
    (for-each (match-lambda
                ((key-name modifiers action-name)
                 (let ((key-value
                        (gi-import-by-name "Gdk" key-name
                                           #:allow-constant? #t)))
                   (add-shortcut controller
                                 (make <gtk-shortcut>
                                   #:trigger (make <gtk-keyval-trigger>
                                               #:keyval key-value
                                               #:modifiers modifiers)
                                   #:action (make <gtk-named-action>
                                              #:action-name action-name))))))
        '(("KEY_n" (control-mask)  "win.window-new")
          ("KEY_t" (control-mask)  "win.tab-new")
          ("KEY_w" (control-mask)  "tab.close")))))

Events ¶

G-Golf Events interfaces.
Handling events from the window system.

Most of the numerous, important and sometimes radical changes in between Gtk-3.0/Gdk-3.0 and Gtk-4.0/Gdk-4.0/Gsk-4.0 have had no impact on G-Golf. And by most, we actually mean all but one: the GdkEvent and its API.

For this reason, this section is split/organized in two subheading, namely ‘In Gdk-3.0’ and ‘In Gdk-4.0’, how creative :), that expose their respective G-Golf interfaces.

  ^_ In Gdk-3.0

In Gdk-3.0, a GdkEvent contains a union of all of the event types. Data fields may be accessed either directly, direct access to GdkEvent structs, or using accessors (but not all data fields have an accessor).

In G-Golf however GdkEvent is a class, with an event slot - holding a pointer the Gdk event - all other slots are virtual and define an accessor, which is the only way users may retrieve data fields.

When G-Golf detects it is leading with GdkEvent from Gdk-3.0, while dynamically implementing the above, in addition, when applicable, it will also add some of the upstream GdkEvent accessor name to the GI Strip Boolean Result list. This is further detailed below, at the end of the section.

Class ¶

<gdk-event>

Accessors ¶

!event

!axis

!button

!click-count

!coords

!device

!device-tool

!event-sequence

!event-type

!keycode

!keyval

!pointer-emulated

!root-coords

!scancode

!screen

!scroll-deltas

!scroll-direction

!seat

!source-device

!state

!time

!window

!keyname

!x

!y

!root-x

!root-y

Class ¶

Class: <gdk-event> ¶

It is an instance of <class>.

Superclasses are:

<object>

Class Precedence List:

<gdk-event>

<object>

<top>

Direct slots are:

event


#:accessor !event
#:init-keyword #:event

A pointer to a GdkEvent.

axis


#:accessor !axis
#:allocation #:virtual

button


#:accessor !button
#:allocation #:virtual

click-count


#:accessor !click-count
#:allocation #:virtual

coords


#:accessor !coords
#:allocation #:virtual

device


#:accessor !device
#:allocation #:virtual

device-tool


#:accessor !device-tool
#:allocation #:virtual

event-sequence


#:accessor !event-sequence
#:allocation #:virtual

event-type


#:accessor !event-type
#:allocation #:virtual

keycode


#:accessor !keycode
#:allocation #:virtual

keyval


#:accessor !keyval
#:allocation #:virtual

pointer-emulated


#:accessor !pointer-emulated
#:allocation #:virtual

root-coords


#:accessor !root-coords
#:allocation #:virtual

scancode


#:accessor !scancode
#:allocation #:virtual

screen


#:accessor !screen
#:allocation #:virtual

scroll-deltas


#:accessor !scroll-deltas
#:allocation #:virtual

scroll-direction


#:accessor !scroll-direction
#:allocation #:virtual

seat


#:accessor !seat
#:allocation #:virtual

source-device


#:accessor !source-device
#:allocation #:virtual

state


#:accessor !state
#:allocation #:virtual

time


#:accessor !time
#:allocation #:virtual

window


#:accessor !window
#:allocation #:virtual

keyname


#:accessor !keyname
#:allocation #:virtual

x


#:accessor !x
#:allocation #:virtual

y


#:accessor !y
#:allocation #:virtual

root-x


#:accessor !root-x
#:allocation #:virtual

root-y


#:accessor !root-y
#:allocation #:virtual

Accessor: !event (inst <gdk-event>) ¶

Returns the content of the event slot for inst, a pointer to a GdkEvent.

Accessor: !axis (inst <gdk-event>) ¶

Accessor: !button (inst <gdk-event>) ¶

Accessor: !click-count (inst <gdk-event>) ¶

Accessor: !coords (inst <gdk-event>) ¶

Accessor: !device (inst <gdk-event>) ¶

Accessor: !device-tool (inst <gdk-event>) ¶

Accessor: !event-sequence (inst <gdk-event>) ¶

Accessor: !event-type (inst <gdk-event>) ¶

Accessor: !keycode (inst <gdk-event>) ¶

Accessor: !keyval (inst <gdk-event>) ¶

Accessor: !pointer-emulated (inst <gdk-event>) ¶

Accessor: !root-coords (inst <gdk-event>) ¶

Accessor: !scancode (inst <gdk-event>) ¶

Accessor: !screen (inst <gdk-event>) ¶

Accessor: !scroll-deltas (inst <gdk-event>) ¶

Accessor: !scroll-direction (inst <gdk-event>) ¶

Accessor: !seat (inst <gdk-event>) ¶

Accessor: !source-device (inst <gdk-event>) ¶

Accessor: !state (inst <gdk-event>) ¶

Accessor: !time (inst <gdk-event>) ¶

Accessor: !window (inst <gdk-event>) ¶

Respectively returns the scheme representation of the content of the inst event (struct) element - refered to by its name. It is an error to call an accessor on a inst for which the event (struct) does not deliver the element.

Internally, each of the above <gdk-event> accessor calls the corresponding GdkEvent accessor, passing the content of the event slot. For example, lets see what happens when a user performs a left button (single) click upon a widget that tracks the 'button-press-event signal callback:

(!button inst)
→ (gdk-event-get-button (!event inst))
⇒ 1

(!click-count inst)
→ (gdk-event-get-click-count (!event inst))
⇒ 1

Please refer to the Gdk Events documentation for a description of the event (struct) element accessor returned value.

To complete the above listed <gdk-event> virtual slots and accessors automatically provided by introspecting GdkEvent, G-Golf also defines a few additional rather convinient virtual slots and accessors:

Accessor: !keyname (inst <gdk-event>) ¶

Returns the key (symbol) name that was pressed or released.

Note that there is actually no such element in any (gdk) event. This accessor calls gdk-keyval-name on the keyval of the event). Here is what happens if a user press the ’a’ keyboard key in a widget that tracks the 'key-press-event signal callback:

(!keyname inst)
→ (gdk-keyval-name (!keyval inst))
→ (gdk-keyval-name (gdk-event-get-keyval inst))
⇒ a

Accessor: !x (inst <gdk-event>) ¶

Accessor: !y (inst <gdk-event>) ¶

Accessor: !root-x (inst <gdk-event>) ¶

Accessor: !root-y (inst <gdk-event>) ¶

Respectively returns the x, y, root-x and root-y coordinate for inst.

The result is simply obtained by destructuring and selecting one of the !coords and !root-coords list values, respectively.

Strip Boolean Result ¶

If you are not (yet) familiar with the concept we are dealing with here, make sure you visit and read the Customization Square - GI Strip Boolean Result section of the manual.

When G-Golf detects it is leading with GdkEvent from Gdk-3.0, while dynamically implementing the <gdk-event> class and its accessors, it will add the following names to the GI Strip Boolean Result list:

gdk-event-get-axis

gdk-event-get-button

gdk-event-get-click-count

gdk-event-get-coords

gdk-event-get-keycode

gdk-event-get-keyval

gdk-event-get-root-coords

gdk-event-get-scroll-deltas

gdk-event-get-scroll-direction

gdk-event-get-state

  ^_ In Gdk-4.0

In Gdk-4.0, GdkEvent is a class¹⁶. GdkEvent structs are opaque and immutable. Direct access to GdkEvent structs is no longer possible in GTK 4. All event fields have accessors.

In G-Golf - as in Gdk-4.0 GdkEvent is a class - no special treatment is performed anymore. In particular, no virtual slot is defined and users must access the GdkEvent structs data fields using the accesors provided by Gdk-4.0.

GObject ¶

G-Golf GObject interfaces.
The G-Golf integration with the GLib Object System.

For completion, this section exposes the definition of the classes and metaclasses involved in the G-Golf integration of the GLib Object System. From a (strict) user point of view however, these are actually G-Golf internals and, unless you are interested of course, might be ignored.

What you actually really need to know, as a G-Golf user, is mostly (a) the upstream reference manual of the GNOME library(ies) you intend to use, (b) how to program in Guile Scheme of course, and (c) the basics of the Guile Object Oriented System.

It doesn’t hurt if you are, or if you are willing to become one, but we would like to emphasize that you do not need to be a Guile Object Oriented System expert to use G-Golf. What you need to know, with that respect, is somehow largely covered by the Getting Started with G-Golf sections, the description of this (and related) sections and in the examples that come with G-Golf.

Classes ¶

<gobject>

<ginterface>

<gobject-class>

<gtype-class>

<gtype-instance>

Procedures, Accessors and Methods ¶

gobject-class?

!info

!derived

!namespace

!g-type

!g-name (2)

!g-class

!g-inst

unref

Description ¶

GObject¹⁷ is the GLib Object System.

The GLib Object System - a C based object-oriented framework and APIs - is composed of three principal elements: (1) GType¹⁸, the lower-level GLib Dynamic Type System, (2) GObject, the base object type and (3) the GObject closures and signals messaging system.

All the GNOME libraries that use the GLib type system inherit from GObject, the base object type, which provides methods for object construction and destruction, property access methods, and signal support.

G-Golf uses GOOPS¹⁹ and defines the <gobject> class, from which all imported GNOME libraries inherit, as their class hierarchy is being built in Guile Scheme.

Classes ¶

Class: <gobject> ¶

The base class of the GLib Object System.

It is an instance of <gobject-class>.

Superclasses are:

<gtype-instance>

Class Precedence List:

<gobject>

<gtype-instance>

<object>

<top>

(No direct slot)

Class: <ginterface> ¶

The base class for GLib’s interface types. Not derivable in Scheme.

It is an instance of <gobject-class>.

Superclasses are:

<gtype-instance>

Class Precedence List:

<ginterface>

<gtype-instance>

<object>

<top>

(No direct slot)

Class: <gobject-class> ¶

The metaclass of the <gobject> and <ginterface> classes.

It is an instance of <class>.

Superclasses are:

<gtype-class>

Class Precedence List:

<gobject-class>

<gtype-class>

<class>

<object>

<top>

(No direct slot)

Class: <gtype-class> ¶

The metaclass of all GType classes. Ensures that GType classes have an info slot, holding a pointer to either a GIObjectInfo or a GIInterfaceInfo.

It is an instance of <class>.

Superclasses are:

<class>

Class Precedence List:

<gtype-class>

<class>

<object>

<top>

Direct slots are:

info

#:accessor !info
#:init-keyword #:info

derived

#:accessor !derived
#:init-keyword #:derived
#:init-value #f

A class is derived when it is user defined (not imported), and inherit a <gobject> subclass.

namespace

#:accessor !namespace

g-type

#:accessor !g-type

g-name

#:accessor !g-name

g-class

#:accessor !g-class

The #:info #:init-keyword is mandatory, other slots are initialized automatically. All slots are immutable (to be precise, they are not meant to be mutated, see GOOPS Notes and Conventions, ’Slots are not Immutable’).

Accessor: !info (inst <gtype-class>) ¶

Accessor: !derived (inst <gtype-class>) ¶

Accessor: !namespace (inst <gtype-class>) ¶

Accessor: !g-type (inst <gtype-class>) ¶

Accessor: !g-name (inst <gtype-class>) ¶

Accessor: !g-class (inst <gtype-class>) ¶

Returns the content of their respective slot for inst.

Class: <gtype-instance> ¶

The root class of all instantiable GType classes. Adds a slot, g-inst, to instances, which holds a pointer to the C value.

It is an instance of <gtype-class>.

Superclasses are:

<object>

Class Precedence List:

<gtype-instance>

<object>

<top>

Direct slots are:

g-inst

#:accessor !g-inst

The g-inst slot is initialized automatically and immutable (to be precise, it is not meant to be mutated, see GOOPS Notes and Conventions, ’Slots are not Immutable’).

Accessor: !g-inst (inst <gtype-instance>) ¶

Returns the content of the g-inst slot for instance.

Method: unref (inst <gtype-instance>) ¶

Returns nothing.

This method calls g-object-unref on the g-inst of instance.

When the reference count for the g-inst reaches 0 (zero), it sets the g-inst slot value for instance to #f and removes instance from the %g-inst-cache.

Note that it used to be mandatory to call this method upon unreachable instances, so that their memory could be freed by the next gc (garbage collector) occurrence, but this is not the case anymore, as auto gc of unreachable <gobject> instances is a now feature [since August 2021].

Procedures ¶

Procedure: gobject-class? val ¶

Returns #t if val is a class and if <gobject> is a member of its class precedence list. Otherwise, it returns #f.

Cache Park ¶

Cache Park - Accessing G-Golf caches.

Procedures ¶

gi-cache-show

gi-cache-ref

Variables ¶

%gi-cache

Description ¶

G-Golf has and uses a cache ‘mechanism’ - actually several, but only one is (partially) exposed to users (and with reserves, see below), also referred to as G-Golf main cache - not only for internal needs, but also to avoid reconstructing things ‘on-the-fly’ unnecessarily, such as already imported <gi-enum>, <gi-flags> and <gi-struct> instances.

G-Golf main cache exposed functionality is ‘access only’ - users should not (never) attempt to change its content - and its design is not (yet) ‘set in stone’, so interfaces here exposed, may (have to be) change(d).

So, keeping the above reserves in mind, G-Golf main cache current data structure is composed of two nested association lists, to which we refer using m-key (main key) and s-key (secondary key).

Procedures ¶

Procedure: gi-cache-show [m-key #f] ¶

Returns nothing.

Displays the content of G-Golf main cache. If m-key (main key) is #f (the default), it displays the list of the main keys present in the cache. Otherwise, it retrieves the content of the main cache for m-key and displays its content if any, or -- is empty -- if none.

Procedure: gi-cache-ref m-key s-key ¶

Returns a %gi-cache entry or #f.

Obtains and returns the %gi-cache entry for m-key and s-key, or #f if none is found.

Remember that you may (always) view the list of main and secondary key names (which is ‘dynamic’, depending on what you have imported) by calling gi-cache-show (without or with an m-key arg appropriately), but as a user, the two most important m-key are 'enum and 'flags, so you may check their member names, or bind their instance locally.

Main key names are given by G-Golf. Secondary key names are always the result of calling g-name->name upon the ‘object’ original name.

For example, let’s import, then retreive and visualize the content of the GtkPositionType (enum) type:

,use (g-golf)
(gi-import-by-name "Gtk" "PositionType")
⇒ $2 = #<<gi-enum> 7ff938938b40>

(gi-cache-ref 'enum 'gtk-position-type)
⇒ $3 = #<<gi-enum> 7ff938938b40>

(describe $3)
-| #<<gi-enum> 7ff938938b40> is an instance of class <gi-enum>
-| Slots are: 
-|     enum-set = ((left . 0) (right . 1) (top . 2) (bottom . 3))
-|     g-type = 94673466933568
-|     g-name = "GtkPositionType"
-|     name = gtk-position-type

Variables ¶

Variable: %gi-cache ¶

Holds a reference the the G-Golf main cache, which as said earlier, currently is composed of two nested association lists.

Customization Square ¶

Customization Square - G-Golf customization functionality.

Procedures and Syntax ¶

g-name-transform-exception

g-name-transform-exception?

g-name-transform-exception-add

g-name-transform-exception-remove

g-name-transform-exception-reset

g-studly-caps-expand-token-exception

g-studly-caps-expand-token-exception?

g-studly-caps-expand-token-exception-add

g-studly-caps-expand-token-exception-remove

g-studly-caps-expand-token-exception-reset

gi-strip-boolean-result

gi-strip-boolean-result?

gi-strip-boolean-result-add

gi-strip-boolean-result-remove

gi-strip-boolean-result-reset

gi-method-short-name-skip

gi-method-short-name-skip?

gi-method-short-name-skip-all

gi-method-short-name-skip-add

gi-method-short-name-skip-remove

gi-method-short-name-skip-reset

syntax-name-protect-prefix

syntax-name-protect-prefix-set

syntax-name-protect-prefix-reset

syntax-name-protect-postfix

syntax-name-protect-postfix-set

syntax-name-protect-postfix-reset

syntax-name-protect-renamer

syntax-name-protect-renamer-set

syntax-name-protect-renamer-reset

syntax-name-protect-reset

Description ¶

Welcome to the G-Golf Customization Square.

This section is organized per customization theme: (-) GI Name Transformation; (-) GI Strip Boolean Result; (-) GI Method Short Name Skip and (-) GI Syntax Name Protect.

GI Name Transformation ¶

In this corner of the square, we expose how you may customize G-Golf with respect to GI Name Transformation that occurs when importing GNOME libraries.

When G-Golf imports a GNOME library, its classes, properties, methods, functions, types and constants are renamed (See Naming Conventions), mainly to (a) avoid ‘Camel Case’, (b) surround class names by ‘<’ ‘>’ and (c) replace ‘_’ (underscore) occurrences using the ‘-’ (hyphen) character.

As the context of name transformation is GNOME in general, as opposed to GI more specifically, (all) procedures involved are named using a g- prefix.

Here is a summary of how the name transformation happens:

• Class names are obtained by calling g-name->class-name, which calls g-name->name;
  
  
• g-name->name first calls g-name-transform-exception? and returns its value if it found one, otherwise, it calls g-studly-caps-expand;
  
  
• g-studly-caps-expand, which does the core of the job, uses g-studly-caps-expand-token-exception? to specially treat its listed token exceptions.

Procedure: g-name-transform-exception ¶

Returns an alist.

Obtains and returns the list of GI name transform exception (key . value) pairs. Both key and value are strings.

The GI name transform exception alist is never empty, as it is initialized and always kept to at least contain the '("GObject" . "gobject") pair²⁰.

As a consequence <gobject> (as opposed to <g-object> is the G-Golf class name for the base class of the GLib Object System.

This only affects the class name though - any procedure or method name that comes from the "GObject" namespace is transformed using the g-object prefix, as the upstream library prefix is g_object.

Procedure: g-name-transform-exception? key ¶

Returns #t if key is a key member of the GI name transform exception alist. Otherwise, it returns #f.

Procedure: g-name-transform-exception-add key value ¶

Procedure: g-name-transform-exception-remove key ¶

Returns nothing.

Add (remove) a (key . value) pair to (from) the GI name transform exception alist.

Procedure: g-name-transform-exception-reset ¶

Returns nothing.

This procedure resets the GI name transform exception alist to its default value - which is to contain the single '("GObject" . "gobject") pair.

Procedure: g-studly-caps-expand-token-exception ¶

Returns an alist.

Obtains and returns the list of GI studly caps expand token exception (key . value) pairs. Both key and value are strings.

The GI studly caps expand token exception alist is never empty, as it is initialized and always kept to at least contain the '("WebKit" . "webkit") pair.

Procedure: g-studly-caps-expand-token-exception? key ¶

Returns #t if key is a key member of the GI studly caps expand token exception alist. Otherwise, it returns #f.

Procedure: g-studly-caps-expand-token-exception-add key value ¶

Procedure: g-studly-caps-expand-token-exception-remove key ¶

Returns nothing.

Add (remove) a (key . value) pair to (from) the GI studly caps expand token exception alist.

Procedure: g-studly-caps-expand-token-exception-reset ¶

Returns nothing.

This procedure resets the GI studly caps expand token exception alist to its default value - which is to contain the single '("WebKit" . "webkit") pair.

GI Strip Boolean Result ¶

In this corner of the square, we expose how you may customize G-Golf with respect to GI Strip Boolean Result, which addresses the problem of typelib functions and methods that (1) have at least one 'inout or 'out argument(s) and (2) return either #t or #f, solely to indicate that the function or method call was successful or not.

The default G-Golf behavior, when there is at least one 'inout or 'out argument(s), is to return multiple values. The first returned value is the function or method result, followed by the 'inout and 'out values, in order of appearance in the function or method call.

G-Golf also offers - through a series of interfaces to get, check, add, remove and reset a list of such function or methods names - to instead elude the function or method returned value when it is #t and raise an exception if the returned value is #f.

Here is a concrete example, for the "Clutter" namespace and the clutter-color-from-string procedure:

,use (g-golf)
(gi-import "Clutter")

(clutter-color-from-string "Blue")
⇒ $2 = #t
⇒ $3 = (0 0 255 255)

And call it with an undefined color name:

(clutter-color-from-string "Bluee")
⇒ $4 = #f
⇒ $5 = (0 0 0 0)

Now, let’s add clutter-color-from-string to the list of GI funtions and methods for which we wish to elude the result of the call from the returned value(s), then experiment the above calls and see how G-Golf changed the way it handles the results:

(gi-strip-boolean-result-add clutter-color-from-string)

(clutter-color-from-string "Blue")
⇒ $7 = (0 0 255 255)

As expected, if we call it with an undefined color name, it will raise an exception²¹

(clutter-color-from-string "Bluee")
-| ice-9/boot-9.scm:1686:16: In procedure raise-exception:
-|   clutter-color-from-string " failed."
-|
-| Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.

G-Golf default is that the list of GI funtions and methods for which to elude the result of the call from the returned value(s) is empty. It is a user responsibility to fill it appropriately, for each namespace they are importing.

Procedure: gi-strip-boolean-result ¶

Returns a (possibly empty) list of (symbol) name(s).

Obtains and returns the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s).

Procedure: gi-strip-boolean-result? name ¶

Returns #t if name is a member of the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s). Otherwise, it returns #f.

Syntax: gi-strip-boolean-result-add name … ¶

Syntax: gi-strip-boolean-result-remove name … ¶

Add (remove) the names to (from) the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s).

Procedure: gi-strip-boolean-result-reset ¶

Resets the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s) to the empty list.

GI Method Short Name Skip ¶

In this corner of the square, we expose how you may customize G-Golf with respect to GI Method Short Name, more specifically, whether you wish to skip the method short name creation, and doing so individually or for all GI imported methods.

By default, as it imports a GI typelib, G-Golf creates a method short name for each imported method, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name.

For example, the <gtk-label> class, which defines the gtk-label-get-text method, would also define, using G-Golf’s default settings, the get-text method. To be more precise, G-Golf would create (if it does not exist) or reuse (if it exists) the get-text generic function, make and add a method with its specializer(s), in this case <gtk-label>.

Now, let’s add gtk-label-get-text to the list of the GI methods for which we wish to skip the short name creation step. In this case, as G-Golf imports the GtkLabel class, it would only create the gtk-label-get-text method, but not the get-text method anymore.

Procedure: gi-method-short-name-skip ¶

Returns a (possibly empty) list of (symbol) name(s).

Obtains and returns the list of GI method long name for which G-Golf will skip the method short name creation step.

Procedure: gi-method-short-name-skip? name ¶

Returns #t if name is a member of the list of GI method long name for which G-Golf will skip the method short name creation step. Otherwise, it returns #f.

Procedure: gi-method-short-name-skip-all ¶

Returns nothing.

Sets the GI method short name skip creation step to 'all.

Syntax: gi-method-short-name-skip-add name … ¶

Syntax: gi-method-short-name-skip-remove name … ¶

Add (remove) the names to (from) the list of GI method long name for which G-Golf will skip the method short name creation step.

Procedure: gi-method-short-name-skip-reset ¶

Resets the list of GI method long name for which G-Golf will skip the method short name creation step to the empty list.

GI Syntax Name Protect ¶

In this corner of the square, we expose how you may customize G-Golf with respect to GI Syntax Name Protect.

When G-Golf creates a method short name, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name, it may lead to a ‘name clash’, with an already defined procedure or syntax.

GI methods are added to their respective generic function, which is created if it does not already exist. When a generic function is created, G-Golf checks if the name is used, and when it is bound to a procedure, the procedure is ‘captured’ into an unspecialized method, which is added to the newly created generic function.

However, when the name is used but its variable value is a syntax, the above can’t be done and the name must be ‘protected’, which is what syntax-name->method-name does²², using a renamer, or by adding a prefix, a postfix or both to its (symbol) name argument.

G-Golf defines the following interfaces to get, set and reset the syntax name protect prefix, postfix and renamer, of which at least one must be set.

Procedure: syntax-name-protect-prefix ¶

Procedure: syntax-name-protect-prefix-set prefix ¶

Procedure: syntax-name-protect-prefix-reset ¶

Respectively get, set and reset the syntax name protect prefix. Its default value is #f.

Procedure: syntax-name-protect-postfix ¶

Procedure: syntax-name-protect-postfix-set postfix ¶

Procedure: syntax-name-protect-postfix-reset ¶

Respectively get, set and reset the syntax name protect postfix. Its default value is '_ (the symbol _).

Procedure: syntax-name-protect-renamer ¶

Procedure: syntax-name-protect-renamer-set renamer ¶

Procedure: syntax-name-protect-renamer-reset ¶

Respectively get, set and reset the syntax name protect renamer. Its default value is '_ (the symbol _).

The syntax name protect renamer, unless set to #f, must be a procedure that takes a (symbol) name as its single argument, and return a ‘none clashing’ (symbol) name.

Procedure: syntax-name-protect-reset ¶

This procedure will conveniently reset all three syntax name protect prefix, postfix and renamer to their default value, which are:

syntax-name-protect-prefix	#f
syntax-name-protect-postfix	'_	(the symbol _)
syntax-name-protect-renamer	#f

VFunc Alley ¶

VFunc Alley - VFunc G-Golf support.

For completion, this section exposes the definition of the <vfunc> class and vfunc syntax, involved in the G-Golf integration of the (GLib Object System) VFunc. From a (strict) user point of view however, these are actually G-Golf internals and, unless you are interested of course, might be ignored.

In the GObject documentation, the terminology (mostly) used is virtual public|private method or simply virtual method. In the GI (GObject Introspection) documentation however, the structure representing a virtual method is named a GIVFuncInfo and the description says it represents a virtual function. The GI core functionality also uses the vfunc or vfunc-info prefix, infix or postfix terms, depending on the context.

Class ¶

<vfunc>

Syntaxes and Accessors ¶

define-vfunc

vfunc

!specializer

!name_______

!g-name_______

!long-name-prefix

!gf-long-name?

!info__

!callback

Special Form ¶

next-vfunc

Description ¶

Welcome to the VFunc G-Golf Alley.

Let’s first recap :-) GObject (the GLib Object System) offers different ways to define object and interface methods and extend them, well introduced and described in the GObject Tutorial:

• non-virtual public methods
• virtual public methods
• virtual private methods
• non-virtual private methods

Of those four, virtual public methods and virtual private methods maybe overridden, through the use of a mechanism that involves the creation of a C closure and the setting of its pointer in the corresponding GObject or Interface class struct.

In G-Golf, this is implemented by the define-vfunc syntax, which must be used to define a VFunc (virtual method). From a user perspective, define-vfunc is very much like define-method (See Methods and Generic Functions in The GNU Guile Reference Manual).

Here is an example, which defines a GObject subclass that inherits the GdkPaintable interface, then overrides the get_flags VFunc, one of its numerous virtual methods:

(define-class <solitaire-peg> (<gobject> <gdk-paintable>)
  (i #:accessor !i #:init-keyword #:i)
  (j #:accessor !j #:init-keyword #:j))

(define-vfunc (get-flags-vfunc (self <solitaire-peg>))
  '(size contents))

The only difference, from a user point of view and as you can see in the example above, is that define-vfunc imposes one (or two, depending on the context) additional constraint(s) to the VFunc name, fully described in the define-vfunc definition.

Class ¶

Class: <vfunc> ¶

The base class of all virtual method.

It is an instance of <class>.

Superclasses are:

<method>

Class Precedence List:

<vfunc>

<method>

<object>

<top>

Direct slots are:

specializer

#:accessor !specializer

name

#:accessor !name

g-name

#:accessor !g-name

long-name-preifx

#:accessor !long-name-preofx

gf-long-name?

#:accessor !gf-long-name?

info

#:accessor !info

callback

#:accessor !callback

All direct slots are initialized automatically and immutable (to be precise, they are not meant to be mutated, see GOOPS Notes and Conventions, ’Slots are not Immutable’).

Syntaxes and Accessors ¶

Syntax: define-vfunc (generic parameter …) body … ¶

Defines a vfunc (a specialized method) for the generic function generic with parameters parameters and body body ....

generic is a generic function, and the following constraints apply to the generic function name:

• the generic function name is valid if it is the scheme representation of a VFunc (name) that exists for at least one of the instance specializer superclasses, followed by the -vfunc postfix²³.
  
  
• if more then one instance specializer superclasses has a VFunc name, then the scheme name must be a so-called long name²⁴, followed by the -vfunc postfix²⁵.

If generic is a variable which is not yet bound to a generic function object, the expansion of define-vfunc will include a call to define-generic.

Each parameter must be either a symbol or a two-element list (symbol class). The symbols refer to variables in the body forms that will be bound to the parameters supplied by the caller when calling this method. The classes, if present, specify the possible combinations of parameters to which this method can be applied.

body … are the bodies of the vfunc definition.

Syntax: vfunc (parameter …) body … ¶

Makes a vfunc (a specialized method) whose specializers are defined by the classes in parameters and whose procedure definition is constructed from the parameter symbols and body forms.

The parameter and body parameters should be as for define-vfunc.

Accessor: !specializer inst ¶

Accessor: !name inst ¶

Accessor: !g-name inst ¶

Accessor: !long-name-prefix inst ¶

Accessor: !gf-long-name? inst ¶

Accessor: !info inst ¶

Accessor: !callback inst ¶

Returns the content of their respective slot for inst (a <vfunc> instance).

Next-vfunc ¶

In G-Golf, from a user perspective, the next-vfunc concept and mechanism is to the GObject virtual method system what the next-method concept and mechanism is to the GOOPS (compute applicable) method system.

If a vfunc refers to ‘next-vfunc’ in its body, that vfunc will call the corresponding ‘immediate parent’ virtual function. The exact ‘next-vfunc’ implementation is only known at runtime, as it is a function of the vfunc specializer argument.

G-Golf implements ‘next-vfunc’ by binding it as a closure variable. An effective virtual method is bound to a specific ‘next-vfunc’ by the internal %next-vfunc-proc, which returns the new closure.

Let’s look at an excerpt form the animated-paintable.scm example, which specializes the GObject finalize virtual method, and as the GNOME team would say, needs to ‘chain-up’:

(define-vfunc (finalize-vfunc (self <nuclear-animation>))
  (g-source-remove (!source-id self))
  ;; This vfunc must 'chain-up' - call the <nuclear-animation> parent
  ;; finalize virtual method.
  (next-vfunc))

Color Hollow ¶

Color Hollow. A color management module.

Procedures ¶

rgb-cc->color

rgba-cc->color

string->color

color-blend

Description ¶

Welcome to the G-Golf Color Hollow, partially inspired by the Chickadee’s color module and the Colorways python library.

In G-Golf, a color is a list of 4 floats in the [0 1] range, each representing the value of the RED (r), GREEN (g), BLUE (b) and ALPHA (a) channels, in that order. For example, an opaque red color instance would be ’(1.0 0.0 0.0 1.0).

G-Golf offers several ways to obtain the list representation of a color, in addition to manually listing the values as showned above:

1. processing its hexadecimal representation

   (rgb-cc->color #x73d216)      ;; cc = color code
   ⇒ (0.45 0.82 0.09 1.0)
   
   (rgba-cc->color #x73d216aa)
   ⇒ (0.45 0.82 0.09 0.67)
   

   In the above examples, #x73d216 is the RGB hexadecimal representation of the (opaque) color, and #x73d216aa is the RGBA hexadecimal representation of the same color with an alpha channel value of 0.67 ²⁶.

2. calling string->color

   (string->color "deepskyblue")
   ⇒ (0 3/4 1 1.0)
   
   (string->color "#aabbccdd")
   ⇒ (0.67 0.73 0.8 0.87)
   

3. refering predefined color symbols

   +blue+
   ⇒ (0 0 1 1.0)
   
   +blanched-almond+
   ⇒ (1 23/25 4/5 1.0)
   

^_ Predefined Color Symbols

G-Golf pre-defines color symbols that come from the following color dictionaries:

• Pango and Gdk (known) colors - As defined here.

  The file mentioned in the above link is maintained by the GNOME team - composed of (sometimes modified) X11 (rgb.txt) and CSS colors - it is used by both the Pango and the Gdk libraries.

• Tango color palette - As described here.
• DawnBringer 32 color palette - As defined here, names taken from here.

Pre-defined color symbols available in G-Golf are defined by taking their corresponding color dictionary entry name, substitute any #\Space by #\-, call g-name->name (which calls g-studly-caps-expand), then pre and postfix the returned symbol name using +. For example:

  +antique-white+
  ⇒ (49/50 23/25 21/25 1.0)

  +tango-chocolate-dark+
  ⇒ (14/25 7/20 1/100 1.0)

  +db32-elf-green+
  ⇒ (11/50 29/50 43/100 1.0)

  +rebeccapurple+
  ⇒ (2/5 1/5 3/5 1.0)

^_ Color Blending

Color blending formulas are mostly taken from here. This is a wip (Work In Progress), as G-Golf currently only provides a few of the numerous color blending modes, to be enhanced in the future.

Unless otherwise specified, color blending procedures (deliberately) apply their formula to the R G B channels (only), and return a (newly allocated) color for which the A (alpha) channel is the base A channel value.

Procedures ¶

Procedure: rgb-cc->color cc ¶

Returns a color, composed of the Red, Green, Blue values for cc (color code), in the [0,1] range, and 1.0 for the Alpha channel.

  (rgb-cc->color #x73d216)
  ⇒ (0.45 0.82 0.09 1.0)

Procedure: rgba-cc->color cc ¶

Returns a color, composed of the Red, Green, Blue, Alpha values for cc (color code), in the [0,1] range.

  (rgba-cc->color #x73d216aa)
  ⇒ (0.45 0.82 0.09 0.67)

Procedure: string->color str ¶

Returns the color, for str.

A valid str value is either an existing G-Golf color dictionary name entry, or an hexadecimal color string. Accepted hexadecimal color string formats are: ‘#rrggbb’, ‘rrggbb’, ‘#rrggbbaa’ and ‘rrggbbaa’.

  (string->color "#73d216aa")
  ⇒ (0.45 0.82 0.09 0.67)

Procedure: color-blend mode base [blend #f] ¶

Returns a (newly allocated) color.

Unless otherwise specified, color blending procedures (deliberately) apply their formula to the R G B channels (only), and return a (newly allocated) color for which the A (alpha) channel is the base A channel value.

The base argument must be a color. The blend argument can either be a color or a float in the [0 1] range (in which case it can also be omited, so as to compute the result of the alternative color blending formula using the default value), for example:

  (color-blend 'darken +red+)
  ⇒ (0.8 0.0 0.0 1.0)

  (color-blend 'darken +red+ 0.3)
  ⇒ (0.7 0.0 0.0 1.0)

  (color-blend 'darken +alice-blue+ +dark-blue+)
  ⇒ (0 0 11/20 1.0)

The mode argument is a symbol. Currently accepted blending mode and alternative color blending formulas are, applied to each of the R G B channel values:

darken

darken base
⇒ (max 0.0 (- chan (* chan 0.2)))

darken base float
⇒ (max 0.0 (- chan (* chan float)))

darken base blend
⇒ (min base-chan blend-chan)

lighten

lighten base
⇒ (min 1.0 (+ chan (* chan 0.2)))

lighten base float
⇒ (min 1.0 (+ chan (* chan float)))

lighten base blend
⇒ (min base-chan blend-chan)

Utils Corner ¶

Utils Corner. Some utilities.

Syntax ¶

scm->g-type

allocate-c-struct

Description ¶

Welcome to the G-Golf Utils Corner.

Syntax ¶

Procedure: scm->g-type value ¶

Returns a GType.

Obtains and returns the GType for value, which may be a number (then assumed to be a valid GType), a string, a symbol (a %g-type-fundamental-types member) or a <gobject-class>.

Syntax: allocate-c-struct name . fields ¶

Returns a (or more) pointer(s).

This syntax takes the name of a GI upstream library C struct²⁷ and returns a pointer to a newly - scheme allocated, zero initialized - memory block.

When fields is not null?, it returns additional value(s), one for each specified field name, a pointer to the field in the C struct.

Here is an example, an excerpt form the peg-solitaire.scm example, distributed with G-Golf. The example shows how to obtain a pointer to newly allocated block for a GskRoundedRect, as well as a pointer to its bounds field:

(receive (outline outline:bounds)
    (allocate-c-struct gsk-rounded-rect bounds)
  ...
  (push-rounded-clip snapshot outline)
  (append-color snapshot
                '(0.61 0.1 0.47 1.0)
                 outline:bounds)
  ...)

Structure and Naming Conventions ¶

G-Golf Core Reference modules and documentation structure and naming conventions are based, whenever it is possible, on the structure and naming conventions of the corresponding GNOME library.

To illustrate, let’s look at a few GLib, GObject and GObject Introspection sections and corresponding G-Golf sections and modules naming examples:

Glib

Memory Allocation

Memory Allocation
(g-golf glib mem-alloc)

The Main Event Loop

The Main Event Loop
(g-golf glib main-event-loop)

…

GObject

Type Information

Type Information
(g-golf gobject type-info)

GObject

GObject
(g-golf gobject gobject)

Enumeration and Flag Types

Enumeration and Flag Types
(g-golf gobject enum-flags)

…

GObject Introspection

GIRepository

Repository
(g-golf gi repository)

common types

Common Types
(g-golf gi common-types)

GIBaseInfo

Base Info
(g-golf gi base-info)

…

Support to the G-Golf Core Reference modules themselves, or additional functionality to G-Golf as a all, is organized and located in other (none GNOME library based) modules, such as (g-golf support …), g-golf override …) …

Version Information (1) ¶

G-Golf Glib Version Information low level API.
Version Information — variables and functions to check the GLib version.

Procedures ¶

glib-get-major-version

glib-get-minor-version

glib-get-micro-version

Description ¶

GLib version information variables and functions.

Procedures ¶

Procedure: glib-get-major-version ¶

Procedure: glib-get-minor-version ¶

Procedure: glib-get-micro-version ¶

Returns an integer.

Obtains and returns the GLib runtime library major, minor and micro version number.

Memory Allocation ¶

G-Golf Glib Memory Allocation low level API.
Memory Allocation — general memory-handling

Procedures ¶

g-malloc

g-malloc0

g-free

g-memdup

Description ¶

These functions provide support for allocating and freeing memory.

Please read the Memory Allocation section from the Glib reference manual for a complete description.

Procedures ¶

Procedure: g-malloc n-bytes ¶

Procedure: g-malloc0 n-bytes ¶

Returns a pointer to the allocated memory, or #f.

Allocates n-bytes of memory. If n-bytes is 0 it returns #f. When using g-malloc0, the allocated memory is initialized to 0.

Procedure: g-free mem ¶

Returns nothing.

Frees the memory pointed to by mem.

Procedure: g-memdup mem n-bytes ¶

Returns a pointer to the allocated memory, or #f.

Allocates n-bytes of memory and copies n-bytes into it from mem. If mem is the %null-pointer or n-bytes is 0 it returns #f.

The Main Event Loop ¶

G-Golf Glib Main Event Loop low level API.
The Main Event Loop — manages all available sources of events

Procedures ¶

g-main-loop-new

g-main-loop-run

g-main-loop-ref

g-main-loop-unref

g-main-loop-quit

g-main-context-new

g-main-context-default

g-timeout-source-new

g-timeout-source-new-seconds

g-idle-source-new

g-source-ref-count

g-source-ref

g-source-unref

g-source-free

g-source-attach

g-source-destroy

g-source-is-destroyed?

g-source-set-priority

g-source-get-priority

g-source-remove

Description ¶

The main event loop manages all the available sources of events for GLib and GTK+ applications. These events can come from any number of different types of sources such as file descriptors (plain files, pipes or sockets) and timeouts. New types of event sources can also be added using g-source-attach.

Please read The Main Event Loop section from the Glib reference manual for a complete description.

Procedures ¶

Note: in this section, the loop, context and source arguments are [must be] pointers to a GMainLoop, a GMainContext and a GSource respectively.

Procedure: g-main-loop-new [context #f] [is-running? #f] ¶

Returns a pointer to a new GMainLoop.

Creates a new GMainLoop structure.

The context must be a pointer to a GMainContext of #f, in which case the default context is used. When is-running? is #t, it indicates that the loop is running. This is not very important since calling g-main-loop-run will set this to #t anyway.

Procedure: g-main-loop-ref loop ¶

Returns loop.

Increases the loop reference count by one.

Procedure: g-main-loop-unref loop ¶

Returns nothing.

Decreases the loop reference count by one. If the result is zero, free the loop and free all associated memory.

Procedure: g-main-loop-run loop ¶

Returns nothing.

Runs a main loop until g-main-loop-quit is called on the loop. If this is called for the thread of the loop’s GMainContext, it will process events from the loop, otherwise it will simply wait.

Procedure: g-main-loop-quit loop ¶

Returns nothing.

Stops a GMainLoop from running. Any calls to g-main-loop-run for the loop will return.

Note that sources that have already been dispatched when g-main-loop-quit is called will still be executed.

Procedure: g-main-context-new ¶

Returns a pointer.

Creates and returns a (pointer to a) new GMainContext structure.

Procedure: g-main-context-default ¶

Returns a pointer.

Returns the global default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the ‘main’ main loop.

Procedure: g-timeout-source-new interval ¶

Returns a pointer.

Creates and returns (a pointer to) a new (timeout) GSource.

The source will not initially be associated with any GMainContext and must be added to one with g-source-attach before it will be executed.

The timeout interval is in milliseconds.

Procedure: g-timeout-source-new-seconds interval ¶

Returns a pointer.

Creates and returns (a pointer to) a new (timeout) GSource.

The source will not initially be associated with any GMainContext and must be added to one with g-source-attach before it will be executed.

The timeout interval is in seconds.

Procedure: g-idle-source-new ¶

Returns a pointer.

Creates and returns (a pointer to) a new (idle) GSource.

The source will not initially be associated with any GMainContext and must be added to one with g-source-attach before it will be executed. Note that the default priority for idle sources is 200, as compared to other sources which have a default priority of 300.

Procedure: g-source-ref-count source ¶

Returns an integer.

Obtains and returns the reference count of source.

Procedure: g-source-ref source ¶

Returns source.

Increases the source reference count by one.

Procedure: g-source-unref source ¶

Returns nothing.

Decreases the source reference count by one. If the resulting reference count is zero the source and associated memory will be destroyed.

Procedure: g-source-free source ¶

Returns nothing.

Calls g-source-destroy and decrements the reference count of source to 0 (so source will be destroyed and freed).

Procedure: g-source-attach source context ¶

Returns an integer.

Adds source to context so that it will be executed within that context.

Returns the ID (greater than 0) for the source within the context.

Remove it by calling g-source-destroy.

Procedure: g-source-destroy source ¶

Returns nothing.

Removes source from its GMainContext, if any, and mark it as destroyed. The source cannot be subsequently added to another context. It is safe to call this on sources which have already been removed from their context.

This does not unref source: if you still hold a reference, use g-source-unref to drop it.

Procedure: g-source-is-destroyed? source ¶

Returns #t if source has been destroyed. Otherwise, it returns #f.

Once a source is destroyed it cannot be un-destroyed.

Procedure: g-source-set-priority source priority ¶

Returns nothing.

Sets the source priority. While the main loop is being run, a source will be dispatched if it is ready to be dispatched and no sources at a higher (numerically smaller) priority are ready to be dispatched.

A child source always has the same priority as its parent. It is not permitted to change the priority of a source once it has been added as a child of another source.

Procedure: g-source-get-priority source priority ¶

Returns an integer.

Obtains and returns the source priority.

Procedure: g-source-remove id ¶

Returns #t.

Removes the source with the given id from the default main context. You must use g-source-destroy for sources added to a non-default main context.

It is an error to attempt to remove a non-existent source.

Source IDs can be reissued after a source has been destroyed. This could lead to the removal operation being performed against the wrong source, unless you are cautious.

For historical reasons, this procedure always returns #t.

IO Channels ¶

G-Golf Glib IO Channels low level API.
IO Channels — portable support for using files, pipes and sockets

Procedures ¶

g-io-channel-unix-new

g-io-channel-ref

g-io-channel-unref

g-io-create-watch

Types and Values ¶

%g-io-condition

Description ¶

The GIOChannel data type aims to provide a portable method for using file descriptors, pipes, and sockets, and integrating them into the main event loop. Currently, full support is available on UNIX platforms, support for Windows is only partially complete.

Please read the IO Channels section from the Glib reference manual for a complete description.

Procedures ¶

Note: in this section, the fd, channel and condition arguments are [must be] respectively an integer (a ‘valid’ file descriptor), a pointer to a GIOChannel and a list of one or more %g-io-condition flags.

Procedure: g-io-channel-unix-new fd ¶

Returns a pointer.

Creates and returns a pointer to a new GIOChannel for fd (file descriptor). On UNIX systems this works for plain files, pipes, and sockets.

The newly created GIOChannel has a reference count of 1.

The default encoding for GIOChannel is UTF-8. If your application is reading output from a command using via pipe, you may need to set the encoding to the encoding of the current locale (FIXME - still missing a binding to g_io_channel_set_encoding).

Procedure: g-io-channel-ref channel ¶

Returns channel.

Increments the channel reference count.

Procedure: g-io-channel-unref channel ¶

Returns nothing.

Decrements the channel reference count.

Procedure: g-io-create-watch channel condition ¶

Returns a pointer.

Creates and returns a pointer to a GSource that’s dispatched when condition is met for the given channel. For example, if condition is '(in), the source will be dispatched when there’s data available for reading.

Types and Values ¶

Instance Variable of <gi-flag>: %g-io-condition ¶

An instance of <gi-flag>, who’s members are the scheme representation of the GIOCondition flags:

g-name: GIOCondition
name: gio-condition
enum-set:

in

There is data to read.

out

Data can be written (without blocking).

pri

There is urgent data to read.

err

Error condition.

hup

Hung up (the connection has been broken, usually for pipes and sockets).

nval

Invalid request. The file descriptor is not open.

Miscellaneous Utility Functions ¶

G-Golf Glib Miscellaneous Utility Functions low level API.
Miscellaneous Utility Functions - a selection of portable utility functions

Procedures ¶

g-get-prgname

g-set-prgname

g-get-system-data-dirs

g-get-system-config-dirs

g-get-os-info

Description ¶

These are portable utility functions.

Procedures ¶

Procedure: g-get-prgname ¶

Returns the name of the program, or #f if it has not been set yet.

Obtains and returns the name of the program. This name should not be localized, in contrast to g-get-application-name.

If you are using GApplication, the program name is set in g-application-run.

Procedure: g-set-prgname name ¶

Returns nothing.

Sets the name of the program to name. This name should not be localized, in contrast to g-set-application-name.

If you are using GApplication, the program name is set in g-application-run.

Note that for thread-safety reasons this function can only be called once.

Procedure: g-get-system-data-dirs ¶

Returns an ordered list of base directories in which to access system-wide application data.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the list of directories retrieved will be XDG_DATA_DIRS.

On Windows it follows XDG Base Directory Specification if XDG_DATA_DIRS is defined. If XDG_DATA_DIRS is undefined, the first elements in the list are the Application Data and Documents folders for All Users. (These can be determined only on Windows 2000 or later and are not present in the list on other Windows versions.) See documentation for CSIDL_COMMON_APPDATA and CSIDL_COMMON_DOCUMENTS.

Then follows the "share" subfolder in the installation folder for the package containing the DLL that calls this function, if it can be determined.

Finally the list contains the "share" subfolder in the installation folder for GLib, and in the installation folder for the package the application’s .exe file belongs to.

The installation folders above are determined by looking up the folder where the module (DLL or EXE) in question is located. If the folder’s name is "bin", its parent is used, otherwise the folder itself.

Note that on Windows the returned list can vary depending on where this function is called.

Procedure: g-get-system-config-dirs ¶

Returns an ordered list of base directories in which to access system-wide configuration information.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the list of directories retrieved will be XDG_CONFIG_DIRS.

On Windows it follows XDG Base Directory Specification if XDG_CONFIG_DIRS is defined. If XDG_CONFIG_DIRS is undefined, the directory that contains application data for all users is used instead. A typical path is C:\Documents and Settings\All Users\Application Data. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer.

Procedure: g-get-os-info key-name ¶

Returns a string or #f.

Obtains and returns information about the operating system.

On Linux this comes from the /etc/os-release file. On other systems, it may come from a variety of sources. You can pass any UTF-8 string key name.

The associated value for the requested key-name is returned or #f if this information is not provided.

UNIX-specific utilities and integration ¶

G-Golf Glib UNIX-specific utilities and integration low level API.
UNIX-specific utilities and integration — pipes, signal handling.

Procedures ¶

g-unix-fd-source-new

Description ¶

Most of GLib is intended to be portable; in contrast, this set of functions is designed for programs which explicitly target UNIX, or are using it to build higher level abstractions which would be conditionally compiled if the platform matches G_OS_UNIX.

Procedures ¶

Note: in this section, the fd and condition arguments are [must be] respectively an integer (a ‘valid’ file descriptor) and a list of one or more %g-io-condition flags.

Procedure: g-unix-fd-source-new fd condition ¶

Returns a pointer.

Creates and returns a pointer to a new GSource to watch for a particular IO condition on fd.

The source will never close the file descriptor, you must do it yourself.

Doubly-Linked Lists ¶

G-Golf Glib Doubly-Linked Lists low level API.
Doubly-Linked Lists — linked lists that can be iterated over in both directions

Procedures ¶

g-list-data

g-list-next

g-list-prev

g-list-free

g-list-length

g-list-nth-data

Description ¶

The GList structure and its associated functions provide a standard doubly-linked list data structure.

Each element in the list contains a piece of data, together with pointers which link to the previous and next elements in the list. Using these pointers it is possible to move through the list in both directions (unlike the singly-linked GSList, which only allows movement through the list in the forward direction).

Please read the Doubly-Linked-Lists section from the Glib reference manual for a complete description.

Procedures ¶

Procedure: g-list-data g-list ¶

Returns a pointer.

Obtains and returns a pointer to the data in g-list, or any integer value, in which case, it is the responsibility of the caller to apply the appropriate type conversion procedure.

Procedure: g-list-next g-list ¶

Returns a pointer or #f.

Obtains and returns the next element in g-list, or #f if there are no more elements.

Procedure: g-list-prev g-list ¶

Returns a pointer or #f.

Obtains and returns the previous element in g-list, or #f if there are no previous element.

Procedure: g-list-free g-list ¶

Returns nothing.

Frees all of the memory used by g-list.

Procedure: g-list-length g-list ¶

Returns an integer.

Obtains and returns the number of elements in g-list. This function iterates over the whole list to count its elements.

Procedure: g-list-nth-data g-list n ¶

Returns a pointer or #f.

Obtains and returns a pointer to the data of the n-th element of g-list. This iterates over the list until it reaches the n-th position. If n is off the end of g-list, it returns #f.

Singly-Linked Lists ¶

G-Golf Glib Singly-Linked Lists low level API.
Singly-Linked Lists — Linked lists that can be iterated over in one direction

Procedures ¶

g-slist-data

g-slist-next

g-slist-append

g-slist-prepend

g-slist-free

g-slist-length

g-slist-nth-data

Description ¶

The GSList structure and its associated functions provide a standard singly-linked list data structure.

Each element in the list contains a piece of data, together with a pointer which links to the next element in the list. Using this pointer it is possible to move through the list in one direction only (unlike the Doubly-Linked Lists, which allow movement in both directions).

Please read the Singly-Linked-Lists section from the Glib reference manual for a complete description.

Procedures ¶

Procedure: g-slist-data g-slist ¶

Returns a pointer.

Obtains and returns a pointer to the data in g-slist, or any integer value, in which case, it is the responsibility of the caller to apply the appropriate type conversion procedure.

Procedure: g-slist-next g-slist ¶

Returns a pointer or #f.

Obtains and returns the next element in g-slist, or #f if there are no more elements.

Procedure: g-slist-append g-slist data ¶

Returns a pointer.

Adds data - which is (must be) a pointer - to the end of g-slist and returns a pointer to the (possibly new) start of the list (so make sure you store the new value).

Note that g-slist-append has to traverse the entire list to find the end, which is inefficient when adding multiple elements. A common idiom to avoid the inefficiency is to prepend the elements and reverse the list when all elements have been added.

Procedure: g-slist-prepend g-slist data ¶

Returns a pointer.

Adds data - which is (must be) a pointer - to the start of g-slist and returns a pointer to the (possibly new) start of the list (so make sure you store the new value).

Procedure: g-slist-free g-slist ¶

Returns nothing.

Frees all of the memory used by g-slist.

Procedure: g-slist-length g-slist ¶

Returns an integer.

Obtains and returns the number of elements in g-slist. This function iterates over the whole list to count its elements.

Procedure: g-slist-nth-data g-slist n ¶

Returns a pointer or #f.

Obtains and returns a pointer to the data of the n-th element of g-slist. This iterates over the list until it reaches the n-th position. If n is off the end of g-slist, it returns #f.

Byte Arrays ¶

G-Golf Glib Byte Arrays low level API.
Byte Arrays — Arrays of bytes.

Procedures ¶

g-bytes-new

Description ¶

FIXME

Procedures ¶

Procedure: g-bytes-new data size ¶

Returns a pointer.

Create a new GBytes²⁸ from data.

data is copied. If size is 0, data may be NULL.

Quarks ¶

G-Golf Glib Quarks low level API.
Quarks — a 2-way association between a string and a unique integer identifier.

Procedures ¶

g-quark-from-string

g-quark-to-string

Description ¶

Quarks are associations between strings and integer identifiers. Given either the string or the GQuark identifier it is possible to retrieve the other.

Procedures ¶

Procedure: g-quark-from-string str ¶

Returns an integer.

Obtains and returns the GQuark identifying the string given by str. If the string does not currently have an associated GQuark, a new GQuark is created, using a copy of the string.

Procedure: g-quark-to-string g-quark ¶

Returns a string.

Obtains and returns the string associated with the GQuark given by g-quark.

Simple XML Subset Parser ¶

G-Golf GLib Simple XML Subset Parser low level API.
Simple XML Subset Parser — parses a subset of XML

Procedures ¶

g-markup-escape-text

Description ¶

The ‘GMarkup’ parser is intended to parse a simple markup format that’s a subset of XML. This is a small, efficient, easy-to-use parser. It should not be used if you expect to interoperate with other applications generating full-scale XML. However, it’s very useful for application data files, config files, etc. where you know your application will be the only one writing the file. Full-scale XML parsers should be able to parse the subset used by GMarkup, so you can easily migrate to full-scale XML at a later time if the need arises.

GMarkup is not guaranteed to signal an error on all invalid XML; the parser may accept documents that an XML parser would not. However, XML documents which are not well-formed are not considered valid GMarkup documents.

Please read the Simple XML Subset Parser section from the GLib reference manual for a complete description.

Procedures ¶

Procedure: g-markup-escape-text text ¶

Returns a string.

Escapes text, some valid UTF-8 text, so that the markup parser will parse it verbatim. Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser.

Note that this function doesn’t protect whitespace and line endings from being processed according to the XML rules for normalization of line endings and attribute values.

Returns a newly allocated string with the escaped text.

Date and Time Functions ¶

G-Golf GLib Date and Time Functions API.
Date and Time Functions — calendrical calculations and miscellaneous time stuff

Procedures ¶

g-get-monotonic-time

Description ¶

The upstream description (which G-Golf usually copies and presents ’unchanged’) talks about the GDate data structure representation and api. As from this section, G-Golf only binds the g-get-monotonic-time, we skip it entirely.

Procedures ¶

Procedure: g-get-monotonic-time ¶

Returns the monotonic time, in microseconds.

Queries the system monotonic time, if available.

On POSIX systems with clock_gettime() and CLOCK_MONOTONIC this call is a very shallow wrapper for that. Otherwise, we make a best effort that probably involves returning the wall clock time (with at least microsecond accuracy, subject to the limitations of the OS kernel).

Note that, on Windows, "limitations of the OS kernel" is a rather substantial statement. Depending on the configuration of the system, the wall clock time is updated as infrequently as 64 times a second (which is approximately every 16ms).

Type Information ¶

G-Golf GObject Type Information low level API.
Type Information — The GLib Runtime type identification and management system

Procedures ¶

g-type->symbol

symbol->g-type

g-type-from-class

g-type-name

g-type-from-name

g-type-parent

g-type-is-a

g-type-class-ref

g-type-class-peek

g-type-class-unref

g-type-class-peek-parent

g-type-interface-peek

g-type-interfaces

g-type-query

g-type-register-static-simple

g-type-add-interface-static

g-type-fundamental

g-type-ensure

Types and Values ¶

%g-type-fundamental-flags

%g-type-fundamental-types

Object Hierarchy ¶

gpointer
  +— GType

Description ¶

The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined object and interface types.

Please read the Type Information section from the GObject reference manual for a complete description.

Procedures ¶

Procedure: g-type->symbol g-type ¶

Returns a symbol.

Get the symbol that correspond to the type ID g-type. Note that this function (like all other GType API) cannot cope with invalid type IDs. It accepts validly registered type ID, but randomized type IDs should not be passed in and will most likely lead to a crash.

Procedure: symbol->g-type symbol ¶

Returns a type ID.

Get the type ID for symbol. Note that this function (like all other GType API) cannot cope with invalid type ID symbols. It accepts validly registered type ID symbol, but randomized type IDs should not be passed in and will most likely lead to a crash.

Procedure: g-type-from-class g-class ¶

Returns a GType.

Obtains and returns the GType for g-class (a pointer to a valid GTypeClass structure).

Procedure: g-type-name g-type ¶

Returns a string.

Get the unique name that is assigned to g-type, a type ID. Note that this function (like all other GType API) cannot cope with invalid type IDs. It accepts validly registered type ID, but randomized type IDs should not be passed in and will most likely lead to a crash.

Procedure: g-type-from-name name ¶

Returns a type ID or #f.

Obtains and returns the type ID for the given type name, or #f if no type has been registered under this name (this is the preferred method to find out by name whether a specific type has been registered yet).

Procedure: g-type-parent g-type ¶

Returns a GType.

Returns the direct parent type for g-type. If g-type has no parent, i.e. is a fundamental type, 0 is returned.

Procedure: g-type-is-a g-type is-a-g-type ¶

Returns #t if g-type is a is-a-g-type.

If is-a-g-type is a derivable type, check whether g-type is a descendant of is-a-g-type. If is-a-g-type is an interface, check whether g-type conforms to it.

Procedure: g-type-class-ref g-type ¶

Returns a pointer.

Obtains and returns a pointer to the GTypeClass structure for g-type (a GObject class GType). The reference count of the class is incremented, and the class is ‘created’ (instanciated) if/when it doesn’t exist already.

Procedure: g-type-class-peek g-type ¶

Returns a pointer.

Obtains and returns a pointer to the GTypeClass structure for g-type (a GObject class GType). The reference count of the class isn’t incremented. As a consequence, this function may return #f - if the class of the type passed in does not currently exist (hasn’t been referenced before).

Procedure: g-type-class-unref g-class ¶

Returns nothing.

Decrements the reference count for g-class (a pointer to a GTypeClass structure). Once the last reference count of a class has been released, it may be finalized by the type system. Attempting to further dereference a finalized class is invalid.

Procedure: g-type-class-peek-parent g-class ¶

Returns a pointer or #f.

Obtains and returns a pointer to the class structure of the immediate parent type for g-class (a pointer to a GTypeClass structure). If no immediate parent type exists, it returns #f.

Procedure: g-type-interface-peek g-class iface-type ¶

Returns a pointer of #f.

Obtains and returns the (a pointer to) GTypeInterface structure for iface-type if implemented by g-class, Otherwise. it returs #f.

Procedure: g-type-interfaces g-type ¶

Returns a (possibily empty) list.

Obtains and returns the (possibily empty) list of the interface IDs (g-type) that g-type conforms to.

Procedure: g-type-query g-type ¶

Returns a list.

Obtains and returns the (g-type type-name class-size instance-size) list for g-type.

Procedure: g-type-register-static-simple parent-type type-name class-size class-init-func instance-size instance-init-func flags ¶

Returns a new type ID.

Registers type-name as the name of a new static type derived from parent-type. The value of flags determines the nature (e.g. abstract or not) of the type. It works by filling a GTypeInfo struct and calling g_type_register_static.

Procedure: g-type-add-interface-static g-type iface-type iface-info ¶

Returns nothing.

Adds iface-type to the static g-type. The information contained in the GInterfaceInfo structure pointed to by iface-info is used to manage the relationship.

If iface-info is #f, a new GInterfaceInfo structure is made, with iface-init-func and iface-finalize-func set to no-op procedures, and iface-data set to the %null-pointer (this is only meant to be used for testing and debugging purposes).

Procedure: g-type-fundamental g-type ¶

Returns a type ID.

Extracts the fundamental type ID portion for g-type.

Procedure: g-type-ensure g-type ¶

Returns nothing.

Ensures that the indicated g-type has been registered with the type system, and that its _class_init method has been run.

Types and Values ¶

Instance Variable of <gi-enum>: %g-type-fundamental-flags ¶

Bit masks used to check or determine specific characteristics of a fundamental type.

An instance of <gi-enum>, who’s members are the scheme representation of the GTypeFundamentalFlags:

g-name: GTypeFundamentalFlags
name: g-type-fundamental-flags
enum-set:

classed

Indicates a classed type

instantiable

Indicates an instantiable type (implies classed)

derivable

Indicates a flat derivable type

deep-derivable

Indicates a deep derivable type (implies derivable)

Instance Variable of <gi-enum>: %g-type-fundamental-types ¶

An instance of <gi-enum>, who’s members are the scheme representation of the GType obtained from the fundamentl types defined using G_TYPE_MAKE_FUNDAMENTAL, which starts with G_TYPE_INVALID and ends with G_TYPE_OBJECT.

g-name: #f²⁹

name: g-type-fundamental-types
enum-set:

invalid

An invalid GType used as error return value in some functions which return a GType.

none

A fundamental type which is used as a replacement for the C void return type.

interface

The fundamental type from which all interfaces are derived.

char

The fundamental type corresponding to gchar. It is unconditionally an 8-bit signed integer. This may or may not be the same type a the C type "gchar".

uchar

The fundamental type corresponding to guchar.

boolean

The fundamental type corresponding to gboolean.

int

The fundamental type corresponding to gint.

uint

The fundamental type corresponding to guint.

long

The fundamental type corresponding to glong.

ulong

The fundamental type corresponding to gulong.

int64

The fundamental type corresponding to gint64.

uint64

The fundamental type corresponding to guint64.

enum

The fundamental type from which all enumeration types are derived.

flags

The fundamental type from which all flags types are derived.

float

The fundamental type corresponding to gfloat.

double

The fundamental type corresponding to gdouble.

string

The fundamental type corresponding to nul-terminated C strings.

pointer

The fundamental type corresponding to gpointer.

boxed

The fundamental type from which all boxed types are derived.

param

The fundamental type from which all GParamSpec types are derived.

object

The fundamental type for GObject.

GObject ¶

G-Golf GObject low level API.
GObject — The base object type

Procedures ¶

g-object-class-install-property

g-object-class-find-property

g-object-class-list-properties

g-object-new

g-object-new-with-properties

g-object-ref

g-object-unref

g-object-ref-sink

g-object-ref-count

g-object-is-floating

g-object-add-toggle-ref

g-object-remove-toggle-ref

g-object-type

g-object-type-name

g-object-get-property

g-object-set-property

Object Hierarchy ¶

GObject
  +— GBinding
  +— GInitiallyUnowned
  +— GTypeModule

Description ¶

GObject is the fundamental type providing the common attributes and methods for all object types in GTK+, Pango and other libraries based on GObject. The GObject class provides methods for object construction and destruction, property access methods, and signal support.

Please read the GObject section from the GObject reference manual for a complete description.

Procedures ¶

Note: in this section, unless otherwise specified, the object argument is [must be] a pointer to a GObject (instance).

Procedure: g-object-class-install-property g-class p-id p-spec ¶

Returns nothing.

Installs a new property.

The arguments are g-class a (pointer to a) GObjectClass), p-id the id for the new property, and p-spec the (a pointer to the) GParamSpec for the new property.

All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads.

Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value.

Procedure: g-object-class-find-property g-class name ¶

Returns a pointer or #f.

Obtains and returns (a pointer to) the GParamSpec for name, or #f if g-class (a pointer to a GObjectClass) doesn’t have a property of that name.

Procedure: g-object-class-list-properties g-class ¶

Returns two values.

Obtains and returns (1) the (possibly empty) list of GParamSpec pointers for g-class and (2) its length (the number of properties for g-class).

Procedure: g-object-new gtype ¶

Returns a pointer.

Creates and returns a (pointer to) a new instance of a GObject subtype gtype. All properties are set to there default values.

Procedure: g-object-new-with-properties gtype n-prop names g-values ¶

Returns a pointer.

Creates and returns a (pointer to) a new instance of a GObject subtype gtype. The other arguments are n-prop the number of properties, names a pointer to an array of pointers to strings with the names of each property to be set and values an array of GValue containing the values of each property to be set.

Properties that are not explicitly specified are set to there default values.

Procedure: g-object-ref object ¶

Returns a pointer.

Increases the reference count of object.

Procedure: g-object-unref object ¶

Returns nothing.

Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

Procedure: g-object-ref-sink object ¶

Returns a pointer.

If object has a floating reference, then this call ‘assumes ownership’ of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged.

If object is not floating, then this call adds a new normal reference increasing the reference count by one.

Procedure: g-object-ref-count object ¶

Returns an integer.

Obtains and returns the (public GObject struct field) ref_count value for object.

Procedure: g-object-is-floating object ¶

Returns #t if object has a floating reference, otherwise it returns #f.

Procedure: g-object-add-toggle-ref object notify data ¶

Returns nothing.

Increases the reference count of object by one and sets a callback, notify, to be called when all other references to object are dropped, or when this is already the last reference to object and another reference is established.

Please refer to the GObject g_object_add_toggle_ref documentation for a complete description.

Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed.

object is (a pointer to) a GObject, notify is a function to call when this reference is the last reference to the object, or is no longer the last reference, and data is (a pointer to) the data to pass to notify. The data argument can be #f.

Procedure: g-object-remove-toggle-ref object notify data ¶

Returns nothing.

Removes a reference added with g-object-add-toggle-ref. The reference count of object is decreased by one.

object is (a pointer to) a GObject, notify is a function to call when this reference is the last reference to the object, or is no longer the last reference, and data is (a pointer to) the data to pass to notify. The data argument can be #f.

Procedure: g-object-type object ¶

Returns the GType (the type id) for object.

Procedure: g-object-type-name object ¶

Returns the GType name for object.

Procedure: g-object-get-property object property [g-type #f] ¶

Returns the property value for object.

The property argument is (must be) a pointer to a valid GIPropertyInfo (property must point to one of the properties infos of the class of object). The g-type argument must be a valid GType value. If #f, which is the default, gi-property-g-type is called.

Procedure: g-object-set-property object property value [g-type #f] ¶

Returns value.

Sets the object property to value. The property argument is (must be) a pointer to a valid GIPropertyInfo (property must point to one of the properties infos of the class of object). The g-type argument must be a valid GType value. If #f, which is the default, gi-property-g-type is called.

Enumeration and Flag Types ¶

G-Golf GObject Enumeration and Flag Types low level API.
Enumeration and Flag Types — Enumeration and flags types.

Description ¶

The GLib type system provides fundamental types for enumeration and flags types. (Flags types are like enumerations, but allow their values to be combined by bitwise or). A registered enumeration or flags type associates a name and a nickname with each allowed value. When an enumeration or flags type is registered with the GLib type system, it can be used as value type for object properties.

Boxed Types ¶

G-Golf GObject Boxed Types low level API.
Boxed Types — A mechanism to wrap opaque C structures registered by the type system.

Procedures ¶

g-boxed-free

g-strv-get-type

Description ¶

GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy them (a GBoxedCopyFunc) and how to free them (a GBoxedFreeFunc) — beyond that they are treated as opaque chunks of memory.

Please read the Boxed Types section from the GObject reference manual for a complete description.

Procedures ¶

Procedure: g-boxed-free g-type pointer ¶

Returns nothing.

Frees the boxed structure at pointer, which is of type g-type.

Procedure: g-strv-get-type ¶

Returns a GType.

Registers (unless already registered) the GStrv GLib type in GObject and returns its GType, the GType for a boxed type holding a NULL-terminated array of strings. This procedure must have been called at least once before (g-type-from-name "GStrv") calls may be honoured.

Generic Values ¶

G-Golf GObject Generic Values low level API.
Generic values — A polymorphic type that can hold values of any other type.

Procedures ¶

g-value-size

g-value-new

g-value-init

g-value-unset

Object Hierarchy ¶

GBoxed
  +— GValue

Description ¶

The GValue structure is basically a variable container that consists of a type identifier and a specific value of that type. The type identifier within a GValue structure always determines the type of the associated value. To create a undefined GValue structure, simply call g-value-new, which create a zero-filled GValue structure. To create and initialize a GValue, use the g-value-init procedure. A GValue cannot be used until it is initialized. The basic type operations (such as freeing and copying) are determined by the GTypeValueTable associated with the type ID stored in the GValue.

Please read the Generic Values section from the GObject reference manual for a complete description.

Procedures ¶

Procedure: g-value-size ¶

Returns an integer.

Obtains and returns the size of a GValue.

Procedure: g-value-new ¶

Returns a pointer to a GValue.

Creates and returns (a pointer to) an empty (uninitialized) GValue.

Procedure: g-value-init g-type ¶

Returns a pointer to a GValue.

Creates and initializes a GValue with the default value for g-type, which can either be an integer - a GType static or dynamic value, or a symbol - a member of the %g-type-fundamental-types.

Procedure: g-value-unset g-value ¶

Returns nothing.

Clears the current value in g-value (if any) and ‘unsets’ the type. This releases all resources associated with g-value. An unset GValue is the same as an uninitialized (zero-filled) GValue structure.

Parameters and Values ¶

G-Golf GObject Parameters and Values low level API.
Parameters and Values — Standard Parameter and Value Types

Procedures and Methods ¶

g-value-type

g-value-type-tag

g-value-type-name

g-value-ref

g-value-set!

g-param-spec-boolean

g-value-get-boolean

g-value-set-boolean

g-param-spec-int

g-value-get-int

g-value-set-int

g-param-spec-uint

g-value-get-uint

g-value-set-uint

g-param-spec-float

g-value-get-float

g-value-set-float

g-param-spec-double

g-value-get-double

g-value-set-double

g-param-spec-enum

g-value-get-enum

g-value-set-enum

g-param-spec-flags

g-value-get-flags

g-value-set-flags

g-param-spec-string

g-value-get-string

g-value-set-string

g-param-spec-param

g-value-get-param

g-value-set-param

g-param-spec-boxed

g-value-get-boxed

g-value-set-boxed

g-value-get-pointer

g-value-set-pointer

g-param-spec-object

g-value-get-object

g-value-set-object

g-value-get-variant

Types and Values ¶

g-type-param-boolean

g-type-param-char

g-type-param-uchar

g-type-param-int

g-type-param-uint

g-type-param-long

g-type-param-ulong

g-type-param-int64

g-type-param-uint64

g-type-param-float

g-type-param-double

g-type-param-enum

g-type-param-flags

g-type-param-string

g-type-param-param

g-type-param-boxed

g-type-param-pointer

g-type-param-object

g-type-param-unichar

g-type-param-override

g-type-param-gtype

g-type-param-variant

Description ¶

GValue provides an abstract container structure which can be copied, transformed and compared while holding a value of any (derived) type, which is registered as a GType with a GTypeValueTable in its GTypeInfo structure. Parameter specifications for most value types can be created as GParamSpec derived instances, to implement e.g. GObject properties which operate on GValue containers.

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a ’-’. All other characters are replaced by a ’-’ during construction.

Procedures and Methods ¶

Note: in this section, the g-value argument is [must be] a pointer to a GValue.

Procedure: g-value-type g-value ¶

Procedure: g-value-type-tag g-value ¶

Procedure: g-value-type-name g-value ¶

Returns an integer, a symbol or a string, respectively.

Obtains and returns the GType, the GType tag (see %g-type-fundamental-types) or the GType name (see g-type-name for g-value, respectively.

Procedure: g-value-ref g-value ¶

Returns the content of g-value.

Obtains and returns the content of g-value. Supported GType (their scheme representaion) for g-value are: boolean, uint, int, float, double, enum, flags, string, boxed, pointer, object, interface.

Procedure: g-value-set! g-value value ¶

Returns nothing.

Sets the content of g-value to value. Supported GType (their scheme representaion) for g-value are: boolean, uint, int, float, double, enum, flags, string, boxed, pointer, object, interface.

Note that this procedure cannot cope with invalid values (the type of value must correspond to the GType for g-value, otherwise it will most likely lead to a crash.

Procedure: g-param-spec-boolean name nick blurb default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecBoolean instance specifying a G_TYPE_BOOLEAN property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-boolean g-value ¶

Returns #t or #f.

Obtains the content of g-value and returns #f if it is 0, otherwise it returns #t.

Procedure: g-value-set-boolean g-value val ¶

Returns nothing.

Sets the content of g-value to 0 if val is #f, otherwise sets the content to 1.

Procedure: g-param-spec-int name nick blurb minimum maximum default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecInt instance specifying a G_TYPE_INT property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, minimum the minimum value, maximum the maximum value, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-int g-value ¶

Returns a integer.

Obtains and returns the content of g-value.

Procedure: g-value-set-int g-value int ¶

Returns nothing.

Sets the content of g-value to int.

Procedure: g-param-spec-uint name nick blurb minimum maximum default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecUInt instance specifying a G_TYPE_UINT property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, minimum the minimum value, maximum the maximum value, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-uint g-value ¶

Returns an unsigned integer.

Obtains and returns the content of g-value.

Procedure: g-value-set-uint g-value uint ¶

Returns nothing.

Sets the content of g-value to uint.

Procedure: g-param-spec-float name nick blurb minimum maximum default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecFloat instance specifying a G_TYPE_FLOAT property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, minimum the minimum value, maximum the maximum value, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-float g-value ¶

Returns a float.

Obtains and returns the content of g-value.

Procedure: g-value-set-float g-value float ¶

Returns nothing.

Sets the content of g-value to float.

Procedure: g-param-spec-double name nick blurb minimum maximum default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecDouble instance specifying a G_TYPE_DOUBLE property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, minimum the minimum value, maximum the maximum value, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-double g-value ¶

Returns a double.

Obtains and returns the content of g-value.

Procedure: g-value-set-double g-value double ¶

Returns nothing.

Sets the content of g-value to double.

Procedure: g-param-spec-enum name nick blurb type default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecEnum instance specifying a G_TYPE_ENUM property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, type a <gi-enum> instance, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-enum g-value ¶

Returns a symbol.

Obtains and returns the (registered) enum type info symbol for g-value.

Method: g-value-set-enum g-value (id <integer>) ¶

Method: g-value-set-enum g-value (sym <symbol>) ¶

Returns nothing.

Sets the content of g-value to id, or to the id corresponding to sym respectively. The id or the sym must be valid (as in being a valid member of the (registered) enum type info for g-value), otherwise an exception is raised.

Procedure: g-param-spec-flags name nick blurb type default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecFlags instance specifying a G_TYPE_FLAGS property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, type a <gi-flags> instance, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-flags g-value ¶

Returns a list.

Obtains and returns the (registered) list of flags for g-value.

Method: g-value-set-flags g-value (val <integer>) ¶

Method: g-value-set-flags g-value (flags <list>) ¶

Returns nothing.

Sets the content of g-value to val, or to the value given by calling flags->integer upon the list of flags, respectively. The val or the flags must be valid (as in being a valid member of the (registered) gi-flags type for g-value), otherwise an exception is raised.

Procedure: g-param-spec-string name nick blurb default flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecString instance specifying a G_TYPE_STRING property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, default the default value and flags the flags - for the property specified.

Procedure: g-value-get-string g-value ¶

Returns a string or #f.

Obtains and returns the content of g-value, a string or #f if the g-value content is the %null-pointer.

Procedure: g-value-set-string g-value str ¶

Returns nothing.

Sets the content of g-value to str.

Procedure: g-param-spec-param name nick blurb type flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecParam instance specifying a G_TYPE_PARAM property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, type a GType derived from G_TYPE_PARAM and flags the flags - for the property specified.

Procedure: g-value-get-param g-value ¶

Returns a (pointer to) GParamSpec or #f.

Obtains and returns the content of g-value, a (pointer to) GParamSpec or #f if the g-value content is the %null-pointer.

Procedure: g-value-set-param g-value param ¶

Returns nothing.

Sets the content of g-value to param.

Procedure: g-param-spec-boxed name nick blurb type flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecBoxed instance specifying a G_TYPE_BOXED derived property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, type a GType derived from G_TYPE_BOXED and flags the flags - for the property specified.

Procedure: g-value-get-boxed g-value ¶

Returns either a list of values, or a pointer.

Obtains and returns the content of g-value. If the boxed type !is-opaque? or !is-semi-opaque?, it ‘blindingly’ returns the boxed instance g-value pointer. Otherwise, the boxed instance is ‘decoded’, and a list of its field values is returned.

Procedure: g-value-set-boxed g-value boxed ¶

Returns nothing.

Sets the content of g-value to boxed. If the boxed type !is-opaque? or !is-semi-opaque?, then boxed is (supposed to be) a pointer, used to ‘blindingly’ set g-value. Otherwise, the boxed instance is (supposed to be) a list of values, that are ‘encoded’, and its (newly created) pointer is used to set g-value.

Procedure: g-value-get-pointer g-value ¶

Returns a pointer.

Obtains and returns the content of g-value.

Procedure: g-value-set-pointer g-value pointer ¶

Returns nothing.

Sets the content of g-value to pointer.

Procedure: g-param-spec-object name nick blurb type flags ¶

Returns a pointer.

Creates and returns a pointer to a new GParamSpecBoxed instance specifying a G_TYPE_OBJECT derived property.

The name is the canonical name of the property specified, nick its nick name, blurb its description, type a <gobject> derived type of this property and flags the flags - for the property specified.

Procedure: g-value-get-object g-value ¶

Returns a pointer.

Obtains and returns the content of g-value.

Procedure: g-value-set-object g-value object ¶

Returns nothing.

Sets the content of g-value to object (a pointer to a GObject instance) and increases the object reference count.

Procedure: g-value-get-variant g-value ¶

Returns a pointer or #f.

Obtains and returns content of a variant g-value, or #f (may be NULL).

Types and Values ¶

Note: in GObject, G_TYPE_PARAM_BOOLEAN, G_TYPE_PARAM_CHAR, etc., are defined as macros. In G-Golf, we define a procedure for each of those types, which binds a libg-golf function which merely invoques the macro, the expansion of which returns the corresponding (dynamic - runtime) GType value.

Procedure: g-type-param-boolean ¶

Procedure: g-type-param-char ¶

Procedure: g-type-param-uchar ¶

Procedure: g-type-param-int ¶

Procedure: g-type-param-uint ¶

Procedure: g-type-param-long ¶

Procedure: g-type-param-ulong ¶

Procedure: g-type-param-int64 ¶

Procedure: g-type-param-uint64 ¶

Procedure: g-type-param-float ¶

Procedure: g-type-param-double ¶

Procedure: g-type-param-enum ¶

Procedure: g-type-param-flags ¶

Procedure: g-type-param-string ¶

Procedure: g-type-param-param ¶

Procedure: g-type-param-boxed ¶

Procedure: g-type-param-pointer ¶

Procedure: g-type-param-object ¶

Procedure: g-type-param-unichar ¶

Procedure: g-type-param-override ¶

Procedure: g-type-param-gtype ¶

Procedure: g-type-param-variant ¶

Returns a GType.

Obtains and returns the GType of GParamSpecBoolean, GParamSpecChar, etc.

GParamSpec ¶

G-Golf GObject GParamSpec low level API.
GParamSpec — Metadata for parameter specifications.

Procedures ¶

gi-g-param-spec-show

g-param-spec-type

g-param-spec-type-name

g-param-spec-get-default-value

g-param-spec-get-name

g-param-spec-get-nick

g-param-spec-get-blurb

g-param-spec-get-flags

Types and Values ¶

%g-param-flags

Description ¶

GParamSpec is an object structure that encapsulates the metadata required to specify parameters, such as e.g. GObject properties.

Procedures ¶

Note: in this section, the p-spec argument is [must be] a pointer to a GParamSpec.

Procedure: gi-g-param-spec-show p-spec ¶

Returns nothing.

Obtains and displays the following informations about the interface pointed to by p-spec:

,use (g-golf)
(g-irepository-require "Gtk" #:version "4.0")
⇒ $2 = #<pointer 0x55ae43d74a60>

(gi-import-by-name "Gtk" "Label")
⇒ $3 = #<<gobject-class> <gtk-label> 7f1a75436a50>

(!g-class <gtk-label>)
⇒ $4 = #<pointer 0x55ae43deb0c0>

(g-object-class-find-property $4 "css-classes")
⇒ $5 = #<pointer 0x55ae43d9d510>

(gi-g-param-spec-show $5)
-|
-| #<pointer 0x55ae43d9d510> is a (pointer to a) GParamSpec:
-|
-|                name: "css-classes"
-|                nick: "CSS Style Classes"
-|               blurb: "List of CSS classes"
-|              g-type: 94206951022032
-|         g-type-name: "GStrv"
-|           type-name: g-strv
-|

Note that the last item, type-name: g-strv is not part of the GParamSpec structure. It is obtained (and used by G-Golf internally by calling (g-name->name g-type-name).

Procedure: g-param-spec-type p-spec ¶

Procedure: g-param-spec-type-name p-spec ¶

Returns an integer or a (symbol) name, respectively.

Obtains and returns the GType or the GType (symbol) name for p-spec, respectively.

Procedure: g-param-spec-get-default-value p-spec ¶

Returns a pointer.

Obtains and returns the p-spec default value as pointer to a GValue, which will remain valid for the life of p-spec and must not be modified.

Procedure: g-param-spec-get-name p-spec ¶

Procedure: g-param-spec-get-nick p-spec ¶

Procedure: g-param-spec-get-blurb p-spec ¶

Returns a string.

Obtains and returns the name, nickname or short description for p-spec, respectively.

Procedure: g-param-spec-get-flags p-spec ¶

Returns a (possibly empty) list.

Obtains and returns a list of the combination of %g-param-flags that applies to p-spec.

Types and Values ¶

Instance Variable of <gi-enum>: %g-param-flags ¶

An instance of <gi-enum>, who’s members are the scheme representation of the GParamFlags:

type-name: GParamFlags
name: g-param-flags
enum-set:

readable

the parameter is readable

writable

the parameter is writable

readwrite

alas for readable writable

construct

the parameter will be set upon object construction

construct-only

the parameter can only be set upon object construction

lax-validation

upon parameter conversion, strict validation is not required

static-name

the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8

private

internal

static-nick

the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8

static-blurb

the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8

explicit-notify

calls to g_object_set_property for this property will not automatically result in a ‘notify’ signal being emitted: the implementation must call g_object_notify themselves in case the property actually changes. Since: 2.42

deprecated

the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26

Closures ¶

G-Golf GObject Closures low level API.

Closures - Functions as first-class objects

Procedures ¶

g-closure-size

g-closure-ref-count

g-closure-ref

g-closure-sink

g-closure-unref

g-closure-free

g-closure-invoke

g-closure-add-invalidate-notifier

g-closure-new-simple

g-closure-set-marshal

g-source-set-closure

Object Hierarchy ¶

GBoxed
  +— GClosure

Description ¶

A GClosure represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a GValue.

Please read the Closures section from the GObject reference manual for a complete description.

Procedures ¶

Note: in this section, the closure, marshal, source and function arguments are [must be] pointers to a GClosure, a GSource, a GClosureMarshal and a GClosureNotify respectively.

Procedure: g-closure-size ¶

Returns an integer.

Obtains and returns the size (the number of bytes) that a GClosure occupies in memory.

Procedure: g-closure-ref-count closure ¶

Returns an integer.

Obtains and returns the reference count of closure.

Procedure: g-closure-ref closure ¶

Returns a pointer.

Increments the reference count of closure, to force it staying alive while the caller holds a pointer to it.

Procedure: g-closure-sink closure ¶

Returns nothing.

Takes over the initial ownership of closure. Each closure is initially created in a ‘floating’ state, which means that the initial reference count is not owned by any caller. g-closure-sink checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, g-closure-sink does nothing.

Because g-closure-sink may decrement the reference count of closure (if it hasn’t been called on closure yet) just like g-closure-unref, g-closure-ref should be called prior to this function.

Procedure: g-closure-unref closure ¶

Returns nothing.

Decrements the reference count of closure after it was previously incremented by the same caller. If no other callers are using closureclosure, then it will be destroyed and freed.

Procedure: g-closure-free closure ¶

Returns nothing.

Decrements the reference count of closure to 0 (so closure will be destroyed and freed).

Procedure: g-closure-invoke closure return-value n-param param-vals invocation-hit ¶

Returns nothing.

Invokes the closure, i.e. executes the callback represented by the closure.

The arguments are closure (a pointer to a GClosure), return-value (a pointer to a GValue), n-param (the length of the param-vals array), param-vals (a pointer to an array of GValue) and invocation-hint (a context dependent invocation hint).

Procedure: g-closure-add-invalidate-notifier closure data function ¶

Returns nothing.

Registers an invalidation notifier which will be called when the closure is invalidated with g-closure-invalidate. Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.

The data argumet is (must be) a pointer to the notifier data (or #f).

Procedure: g-closure-new-simple size data ¶

Returns a pointer.

Allocates a structure of the given size and initializes the initial part as a GClosure. The data (if any) are used to iitialize the data fields of the newly allocated GClosure.

The returned value is a floating reference (a pointer) to a new GClosure.

Procedure: g-closure-set-marshal closure marshal ¶

Returns nothing.

Sets the closure marshaller to marshal.

Procedure: g-source-set-closure source closure ¶

Returns nothing.

Set the source callback to closure.

If the source is not one of the standard GLib types, the closure_callback and closure_marshal fields of the GSourceFuncs structure must have been filled in with pointers to appropriate functions.

Signals ¶

G-Golf GObject Signals low level API.
Signals — A means for customization of object behaviour and a general purpose notification mechanism

Procedures ¶

g-signal-newv

g-signal-query

g-signal-lookup

g-signal-list-ids

g-signal-emitv

g-signal-connect-closure-by-id

g-signal-handler-disconnect

g-signal-parse-name

Types and Values ¶

%g-signal-flags

Description ¶

The basic concept of the signal system is that of the emission of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are available in derived types as well, so basically they are a per-type facility that is inherited.

Please read the Signals section from the GObject reference manual for a complete description.

Procedures ¶

Procedure: g-signal-newv name iface-type flags class-closure accumulator accu-data c-marshaller return-type n-param param-types ¶

Returns the signal id.

Creates a new signal. The arguments are:

name

The name for the signal.

iface-type

The type this signal pertains to. It will also pertain to types which are derived from this type.

flags

A list of %g-signal-flags, specifying detail of when the default handler is to be invoked. It should at least specify run-first or run-last.

class-closure

The closure to invoke on signal emission, may be #f.

accumulator

The accumulator for this signal; may be #f.

accu-data

User data for the accumulator.

c-marshaller

The function to translate arrays of parameter values to signal emissions into C language callback invocations or #f.

return-type

The GType of the signal returned value. The caller may obtain the GType, given a scheme object (or 'none for a signal without a return value), by calling scm->g-type.

n-param

The length of param-types.

param-types

An list of types, one for each parameter (may be '() if n-param is zero).

Procedure: g-signal-query id ¶

Returns a list.

Obtains and returns a list composed of the signal id, name, interface-type³⁰, flags, return-type, number of arguments and their types. For example³¹:

,use (g-golf)
(gi-import "Clutter")

(make <clutter-actor>)
⇒ $2 = #<<clutter-actor> 565218c88a80>

(!g-type (class-of $2))
⇒ $3 = 94910597864000

(g-signal-list-ids $3)
⇒ $4 = (5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30)

(g-signal-query 20)
⇒ $5 = (20 "enter-event" 94910597864000 (run-last) boolean 1 (boxed))

As you may have noticed, the signal query argument(s) list does not include the instance (and its type) upon which the signal is called, but both at C level and within the context of GClosure, callbacks must assume that the instance upon which a signal is called is always the first argument of the callback.

Procedure: g-signal-lookup name g-type ¶

Returns an integer.

Obtains and returns the signal’s identifying integer, given the name of the signal and the object g-type it connects to. If a signal identifier can’t be find for the given name and g-type, an exception is raised.

Procedure: g-signal-list-ids g-type ¶

Returns a list of integers.

Obtains and returns the list of signal’s identifying integers for g-type (Note that at least one g-type instance must have been created prior to attempt to list or query signal’s identifying integers for a given g-type).

Procedure: g-signal-emitv params id detail return-value ¶

Returns nothing.

Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped.

Note that g-signal-emitv doesn’t change return-value if no handlers are connected.

The params points to the argument list for the signal emission. The first element in the array is a GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. The id is the signal id, detail the detail (a g-quark and return-value the location to store the return value of the signal emission (it must be provided if the specified signal returns a value, but may be ignored otherwise).

Procedure: g-signal-connect-closure-by-id instance id detail closure after ¶

Returns the handler ID (always greater than 0 for successful connections).

Connects a closure to a signal for a particular object.

If closure is a floating reference (see g-closure-sink), this function takes ownership of closure.

The instance is the instance to connect to, the id the id of the signal, detail the detail (a g-quark). closure the closure to connect, after (a boolean) whether the handler should be called before or after the default handler of the signal.

Procedure: g-signal-handler-disconnect instance handler-id ¶

Returns nothing.

Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler-id becomes invalid and may be reused.

The handler-id has to be a valid signal handler id, connected to a signal of instance .