GNU G-Golf Reference Manual
***************************
This manual documents GNU G-Golf version 0.8.0-rc-3.
Copyright (C) 2016 - 2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License."
GNU G-Golf Reference Manual
Preface
Contributors to this Manual
Join the GNU Project
The G-Golf License
I. Introduction
About G-Golf
Obtaining and installing G-Golf
Contact Information
Reporting Bugs
II. Using G-Golf
Before you start
Naming Conventions
GOOPS Notes and Conventions
Configuring Guile for G-Golf
Customizing G-Golf
SXML Support - Emacs users
Getting Started with G-Golf
Hello World!
Selective Import
Scripting
Building Applications
G-Golf on Mobile Devices
Working with GNOME
Import
Events
GObject
G-Golf Valley
Cache Park
Customization Square
VFunc Alley
Utils Arcade
III. G-Golf Core Reference
Overview
Structure and Naming Conventions
Glib
Version Information (1)
Memory Allocation
The Main Event Loop
IO Channels
Miscellaneous Utility Functions
UNIX-specific utilities and integration
Doubly-Linked Lists
Singly-Linked Lists
Byte Arrays
Quarks
GObject
Type Information
GObject
Enumeration and Flag Types
Boxed Types
Generic Values
Parameters and Values
GParamSpec
Closures
Signals
GObject Introspection
Repository
Typelib
Common Types
Version Information (2)
Base Info
Callable Info
Function Info
Signal Info
VFunc Info
Registered Type Info
Enum Info
Struct Info
Union Info
Object Info
Interface Info
Arg Info
Constant Info
Field Info
Property Info
Type Info
FFI Interface
Utilities
Support
Module
Goops
Enum
Flags
Struct
Union
Utilities
G-Golf High Level API
Closure
Function
Import
Utilities
Appendix A GNU Free Documentation License
Concept Index
Procedure Index
Variable Index
Type Index
List of Examples
Preface
*******
This manual describes how to use G-Golf. It relates particularly to
G-Golf version 0.8.0-rc-3.
Contributors to this Manual
===========================
Like G-Golf itself, the G-Golf reference manual is a living entity.
Right now, the contributor to this manual is:
• David Pirotte
who is also the author and maintainer of G-Golf.
You are most welcome to join and help. Visit G-Golf's web site at
#:title "Peg Solitaire"
#:default-width 420
#:default-height 420
#:application app))
(header-bar (make ))
(restart (make
#:icon-name "view-refresh-symbolic")))
(connect restart
'clicked
(lambda (bt)
(restart-game window)))
(set-titlebar window header-bar)
(pack-start header-bar restart)
(create-board window)
(show window)))
G-Golf comes with some examples, listed on the learn page
(https://www.gnu.org/software/g-golf/learn.html) of the G-Golf web site.
Each example comes with a screenshot and has a link that points to its
source code, in the G-Golf sources repository
(http://git.savannah.gnu.org/cgit/g-golf.git).
Savannah
--------
GNU G-Golf also has a project page on Savannah
(https://savannah.gnu.org/projects/g-golf).
---------- Footnotes ----------
(1) GNU Guile (http://www.gnu.org/software/guile)
an interpreter and compiler for the Scheme (http://schemers.org)
programming language.
(2) The Guile Object Oriented System, *Note (guile)GOOPS::
Obtaining and installing G-Golf
===============================
G-Golf can be obtained from the following archive site
Dependencies
------------
** Main Dependencies*
G-Golf needs the following software to run:
• Autoconf ≥ 2.69
• Automake ≥ 1.14
• Makeinfo ≥ 6.6
• Guile (http://www.gnu.org/software/guile) 2.0 (≥ 2.0.14), 2.2 or
3.0 (≥ 3.0.7)
• Glib-2.0 (https://developer.gnome.org/glib/stable/) ≥ 2.73.0
• Gobject-2.0 (https://developer.gnome.org/gobject/stable/) ≥ 2.73.0
• GObject-Introspection-1.0 (https://developer.gnome.org/stable/gi) ≥
1.72.0
** Test-Suite Dependencies*
G-Golf currently needs the following additional software to run its
test-suite:
• Guile-Lib (http://www.nongnu.org/guile-lib) ≥ 0.2.5
• Gtk-3.0 (https://developer.gnome.org/gtk3/stable) ≥ 3.10.0
** Examples Dependencies*
_ - Gtk-4.0 examples - _
G-Golf currently needs the following additional software to run its
Gtk-4.0 examples:
• Gtk-4.0 (https://docs.gtk.org/gtk4/index.html) ≥ 4.10.0
• Guile-Cairo (http://www.nongnu.org/guile-cairo) > 1.11.2
G-Golf actually requires a patched version of guile-cairo that
contains the following new interface (which is not in guile-cairo
1.11.2): ‘cairo-pointer->context’.
_ - Adwaita examples - _
G-Golf currently needs the following additional software to run its
Adw-1 examples:
• Adw-1
(https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/) ≥
1.5.0
Install from the tarball
------------------------
Assuming you have satisfied the dependencies, open a terminal and
proceed with the following steps:
cd
tar zxf g-golf-0.8.0-rc-3.tar.gz
cd g-golf-0.8.0-rc-3
./configure [--prefix=/your/prefix] [--with-guile-site]
make
make install
Happy G-Golf (http://www.gnu.org/software/g-golf/)!
Install from the source
-----------------------
G-Golf (http://www.gnu.org/software/g-golf/) uses Git
(https://git-scm.com/) for revision control, hosted on Savannah
(https://savannah.gnu.org/projects/g-golf), you may browse the sources
repository here (http://git.savannah.gnu.org/cgit/g-golf.git).
There are currently 2 [important] branches: ‘master’ and ‘devel’.
G-Golf (http://www.gnu.org/software/g-golf/) stable branch is master,
developments occur on the devel branch.
So, to grab, compile and install from the source, open a terminal and:
git clone git://git.savannah.gnu.org/g-golf.git
cd g-golf
./autogen.sh
./configure [--prefix=/your/prefix] [--with-guile-site]
make
make install
The above steps ensure you're using G-Golf
(http://www.gnu.org/software/g-golf/) bleeding edge ‘stable’ version.
If you wish to participate to developments, checkout the ‘devel’ branch:
git checkout devel
Happy ‘hacking!’
*Notes:*
1. The ‘default’ and ‘--prefix’ installation locations for source
modules and compiled files (in the absence of ‘--with-guile-site’)
are:
$(datadir)/g-golf
$(libdir)/g-golf/guile/$(GUILE_EFFECTIVE_VERSION)/site-ccache
If you pass ‘--with-guile-site’, these locations become:
Guile global site directory
Guile site-ccache directory
2. The configure step reports these locations as the content of the
‘sitedir’ and ‘siteccachedir’ variables.
After installation, you may consult these variables using
pkg-config:
pkg-config g-golf-1.0 --variable=sitedir
pkg-config g-golf-1.0 --variable=siteccachedir
3. Unless you have used ‘--with-guile-site’, or unless these locations
are already ’known’ by Guile, you will need to define or augment
your ‘GUILE_LOAD_PATH’ and ‘GUILE_COMPILED_PATH’ environment
variables accordingly (or ‘%load-path’ and ‘%load-compiled-path’ at
run time if you prefer(1) (See Environment Variables
(https://www.gnu.org/software/guile/manual/guile.html#Environment-Variables)
and Load Path
(https://www.gnu.org/software/guile/manual/guile.html#Load-Paths)
in the Guile Reference Manual).
4. G-Golf also installs its ‘libg-golf.*’ library files, in
‘$(libdir)’. The configure step reports its location as the
content of the ‘libdir’ variable, which depends on on the content
of the ‘prefix’ and ‘exec_prefix’ variables (also reported).
After installation, you may consult these variables using
pkg-config:
pkg-config g-golf-1.0 --variable=prefix
pkg-config g-golf-1.0 --variable=exec_prefix
pkg-config g-golf-1.0 --variable=libdir
5. Unless the ‘$(libdir)’ location is already 'known' by your system,
you will need - to either define or augment your ‘$LD_LIBRARY_PATH’
environment variable, or alter the ‘/etc/ld.so.conf’ (or add a file
in ‘/etc/ld.so.conf.d’) and run (as root) ‘ldconfig’, so that
G-Golf finds its ‘libg-golf.*’ library files(2).
6. To install G-Golf, you must have write permissions to the default
or ‘$(prefix)’ directory and its subdirs, as well as to both
Guile's site and site-ccache directories if ‘--with-guile-site’ was
passed.
7. Like for any other GNU Tool Chain compatible software, you may
install the documentation locally using ‘make install-info’, ‘make
install-html’ and/or ‘make install-pdf’.
8. G-Golf comes with a ‘test-suite’, which we recommend you to run
(especially before *note Reporting Bugs::):
make check
9. To try/run an uninstalled version of G-Golf, use the pre-inst-env
script:
./pre-inst-env your-program [arg1 arg2 ...]
---------- Footnotes ----------
(1) In this case, you may as well decide to either alter your
‘$HOME/.guile’ personal file, or, if you are working in a mult-user
environmet, you may also opt for a global configuration. In this case,
the file must be named ‘init.scm’ and placed it here (evaluate the
following expression in a terminal): ‘guile -c "(display
(%global-site-dir))(newline)"’.
(2) Contact your administrator if you opt for the second solution but
don't have ‘write’ priviledges on your system.
Contact Information
===================
Mailing list
------------
G-Golf uses Guile's mailing lists:
• is for general user help and discussion.
• is used to discuss most aspects of G-Golf,
including development and enhancement requests.
Please use ‘G-Golf - ’ to preceed the subject line of G-Golf related
emails, thanks!
You can (un)subscribe to the one or both of these mailing lists by
following instructions on their respective list information page
(https://lists.gnu.org/mailman/listinfo/).
IRC
---
Most of the time you can find me on irc, channel _#guile_, _#guix_ and
_#scheme_ on _irc.libera.chat_, _#clutter_ and _#introspection_ on
_irc.gnome.org_, under the nickname _daviid_.
Reporting Bugs
==============
G-Golf uses a bug control and manipulation mailserver. You may send
your bugs report here:
•
You can (un)subscribe to the bugs report list by following instructions
on the list information page
(https://lists.gnu.org/mailman/listinfo/bug-g-golf).
Further information and a list of available commands are available here
(https://debbugs.gnu.org/server-control.html).
II. Using G-Golf
****************
Before you start
================
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
*note g-name->class-name:: and *note g-name->name:: appropriately.
As described in their respective documentation entry, as well as in the
*note 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, *note (guile)GOOPS::), and their respective name is
given by the result of calling *note g-name->class-name::, for example:
GtkWindow ⇒
ClutterActor ⇒
WebKitWebView ⇒ (1)
...
^{_} *Properties*
GNOME libraries class properties are imported as GOOPS class slots, and
their respective name is given by calling *note g-name->name::. Each
property slot defines an ‘init-keyword’ and an ‘accessor’, following
G-Golf's accessors naming conventions (*Note GOOPS Notes and
Conventions::).
As an example, the ‘’ 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 *note g-name->name::.
Unless otherwise specified (*note 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 ‘’ 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
*note 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
*note g-name->name:: (and cached, *Note Cache Park:: section).
Enum and flag type members are renamed by calling *note g-name->name::.
To illustrate, here is an example:
,use (g-golf)
(gi-import-by-name "Gtk" "WindowPosition")
⇒ $2 = #< 5618c7a18090>
(describe $2)
⊣ #< 5618c7a18090> is an instance of class
⊣ 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
⇒ *note g-main-loop-new::
g_irepository_get_loaded_namespaces
⇒ *note 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 (http://www.gnu.org/software/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:
*note call-with-input-typelib::
• syntax names that start as ‘with-’ followed by a Glib, GObject, Gdk
or GI type, such as:
*note with-gerror::
When an ‘obvious’ name can't be find ‘on its own’, or to avoid possible
conflict outside G-Golf(2), 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 *note g-studly-caps-expand::.
For example, from the ‘GIBaseInfo’ section:
GIInfoType
⇒ *note %gi-info-type::
---------- Footnotes ----------
(1) By default, G-Golf sets ‘WebKit’ as a renaming exception token,
otherwise, the class name would be .
(2) As an example, it would not be a good idea to use (the name)
‘import’ for the G-Golf procedure that reads and build the interface for
a ‘GIR’ library, since it is an R6RS reserved word.
GOOPS Notes and Conventions
---------------------------
G-Golf extensively uses GOOPS, the Guile Object Oriented System (*note
(guile)GOOPS::), in a way that is largely inspired by Guile-Gnome
(https://www.gnu.org/software/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’)(1).
However, you will find a few places in this manual using phrase excerpts
like ‘instances of this are immutable’, or ‘this 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 (*note (guile)Merging
Generics::).
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(2), 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 ()
(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(3).
• 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.
---------- Footnotes ----------
(1) Actually, to be complete, there is a way, which is to define the
slot using ‘#:class ’, but (a) it is undocumented and
(b), it requires the use use of libguile to initialize the slot value,
something that I don't wan't to do in G-Golf. If you are interested by
this (undocumented) feature for your own project though, I suggest you
look for some exmples in the Guile-Gnome
(https://www.gnu.org/software/guile-gnome), source tree, where it is
extensively used.
(2) You need write privileges to add or modify this file, contact
your system administrator if you're not in charge of the system you are
working on.
(3) Slot names tends to be extremelly common, like ‘name’, ‘color’,
... and naming their respective accessor using the slot name would very
likely provoque numerous name clashes with user variables, procedures
and methods names.
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 (*note (guile)Merging
Generics::).
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(1), here (evaluate the following expression
in a terminal): ‘guile -c "(display (%global-site-dir))(newline)"’.
---------- Footnotes ----------
(1) You need write privileges to add or modify this file, contact
your system administrator if you're not in charge of the system you are
working on.
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 (*Note Naming Conventions::),
mainly to (a) avoid ‘Camel Case
(https://en.wikipedia.org/wiki/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.
*Note 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’.
*Note 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.
*Note 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.
*Note 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.
Getting Started with G-Golf
===========================
G-Golf will let you import and work with any GObject-Introspectable
GNOME library(1). Since we need to make a choice among so many, to
guide new comers and get them started with G-Golf, let's pick-up Gtk
(https://docs.gtk.org/gtk4/index.html), and show how to Create
interfaces that users just love (https://gtk.org/).
Please note that in the entire course of the G-Golf manual, unless
otherwise specified, examples are based on and use Gtk-4.0
(https://docs.gtk.org/gtk4/index.html), Gdk-4.0
(https://docs.gtk.org/gdk4/index.html) and Gsk-4.0
(https://docs.gtk.org/gsk4/index.html) - which is new and only available
with Gtk-4.0.
G-Golf itself perfectly works and support Gtk-3.0
(https://developer.gnome.org/gtk3/stable) and Gdk-3.0
(https://developer.gnome.org/gdk3/stable).
We shall complete this brief introduction mentioning that the GNOME team
wrote a guide to help Migrating from GTK 3.x to GTK 4
(https://developer.gnome.org/gtk4/stable/gtk-migrating-3-to-4.html).
---------- Footnotes ----------
(1) In its compiled form, a GObject-Introspectable GNOME library is
called a Typelib (https://gi.readthedocs.io/en/latest) - a binary,
readonly, memory-mappable database containing reflective information
about a GObject library.
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
#:title "Hello"
#:application app))
(button (make
#: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
#: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)(1), 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.
[hello-world-1]
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
#: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
‘ / g-application-run’ instance creation and run
mechanism in detail, for this, please consult and carefully read their
respective entries in the Gtk
(https://docs.gtk.org/gtk4/class.Application.html) and Gio
(https://developer.gnome.org/gio/stable/GApplication.html) reference
manuals.
The GNOME team also maintains a wiki called HowDoI
(https://wiki.gnome.org/HowDoI), and two pages are dedicated to this
subject: HowDoI GtkApplication
(https://wiki.gnome.org/HowDoI/GtkApplication) and HowDoI
GtkApplication/CommandLine
(https://wiki.gnome.org/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
(https://docs.gtk.org/gtk4/class.Application.html) 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
(https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid).
In G-Golf, you may check if your application ID is valid by calling
‘g-application-id-is-valid’(2), 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 ‘’ 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 *note Selective Import::, used to reduce the time G-Golf has to
spend importing the typelib(s) that your application requires.
---------- Footnotes ----------
(1) If you haven't done so, please read the *note Configuring Guile
for G-Golf::, _Merging Generics_ and configure your repl as proposed,
before to run the example.
(2) After you at least import either directly ‘(gi-import-by-name
"Gio" "Application")’, or ‘(gi-import-by-name "Gtk" "Application")’,
which triggers the appropriate Gio imports, as described in the next
section
Selective Import
----------------
To selectively import namespace components, use *note
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 *note 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, *note (guile)Guile Scripting::.
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’(1).
In Guile, (2) is achieved by calling the ‘eval-when’ syntax(2).
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
#:title "Hello"
#:default-width 320
#:default-height 240
#:application app))
(box (make
#:margin-top 6
#:margin-start 12
#:margin-bottom 6
#:margin-end 6
#:orientation 'vertical))
(label (make
#:label "Hello, World!"
#:hexpand #t
#:vexpand #t))
(button (make
#: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
#: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:
[hello-world-2]
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, *note Building Applications::.
---------- Footnotes ----------
(1) As seen in *note Configuring Guile for G-Golf:: (and in *note
GOOPS Notes and Conventions:: - 'Merging Generics').
(2) *Note (guile)Eval-when:: for a complete description.
Building Applications
---------------------
G-Golf on Mobile Devices
------------------------
Working with GNOME
==================
Working with GNOME exposes, grouped by theme, the user interfaces to
import and work with GObject-Introspectable GNOME libraries.
Please note that within the scope of the G-Golf manual in general, in
the sections presented here in particular, we simply (as in merely and
in the simplest possible way) exposes the scheme representation and
G-Golf interfaces of the elements that are being addressed. For a
deep(er) understanding of the original concepts, components and
interfaces, you must refer to the upstream library documentation itself.
This is particularly true for the GLib Object System related sections.
For a thorough understanding of the GLib Object System - its background,
design goals, dynamic type system, base class instantiation, memory
management, properties, closures and signals messaging system - please
consult the GObject - Type System Concepts
(https://docs.gtk.org/gobject/concepts.html) of the GObject reference
manual.
Import
------
G-Golf Import interfaces.
Importing GNOME libraries.
Procedures
----------
‘*note gi-import::’
‘*note gi-import-by-name::’
Description
-----------
The G-Golf GIR namespace (Typelib) import interfaces.
Procedures
----------
-- Procedure: gi-import namespace [#: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 *note gi-import-by-name::
here below.
-- Procedure: gi-import-by-name namespace name [#:version #f]
[#:with-method #t]
Returns the object or constant returned by *note gi-import-info::
called upon the GIBaseInfo ‘info’ named NAME in NAMESPACE.
Obtains and imports 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 keyword #:WITH-METHOD 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.
This is likely to only be the case if/when you intend to
selectively import an enum, flags or struct from GLib or GObject,
which is what G-Golf itself does, for example, in the top level
(g-golf) module:
(gi-import-by-name "GLib" "IOChannel" #:with-method #f)
Events
------
G-Golf Events interfaces.
Handling events from the window system.
^{_} SPECIAL NOTE ^{_}
Most of the numerous, important and sometimes radical changes in between
Gtk-3.0 (https://developer.gnome.org/gtk3/stable)/Gdk-3.0
(https://developer.gnome.org/gdk3/stable) and Gtk-4.0
(https://docs.gtk.org/gtk4/index.html)/Gdk-4.0
(https://docs.gtk.org/gdk4/index.html)/Gsk-4.0
(https://docs.gtk.org/gsk4/index.html) 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 (https://developer.gnome.org/gdk3/stable), 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
-----
‘*note ::’
Accessors
---------
‘*note !event::’
‘*note !axis::’
‘*note !button::’
‘*note !click-count::’
‘*note !coords::’
‘*note !device::’
‘*note !device-tool::’
‘*note !event-sequence::’
‘*note !event-type::’
‘*note !keycode::’
‘*note !keyval::’
‘*note !pointer-emulated::’
‘*note !root-coords::’
‘*note !scancode::’
‘*note !screen::’
‘*note !scroll-deltas::’
‘*note !scroll-direction::’
‘*note !seat::’
‘*note !source-device::’
‘*note !state::’
‘*note !time::’
‘*note !window::’
‘*note !keyname::’
‘*note !x::’
‘*note !y::’
‘*note !root-x::’
‘*note !root-y::’
Class
-----
-- Class:
It is an instance of ‘’.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
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 )
Returns the content of the event slot for INST, a pointer to a
‘GdkEvent’.
-- Accessor: !axis (inst )
-- Accessor: !button (inst )
-- Accessor: !click-count (inst )
-- Accessor: !coords (inst )
-- Accessor: !device (inst )
-- Accessor: !device-tool (inst )
-- Accessor: !event-sequence (inst )
-- Accessor: !event-type (inst )
-- Accessor: !keycode (inst )
-- Accessor: !keyval (inst )
-- Accessor: !pointer-emulated (inst )
-- Accessor: !root-coords (inst )
-- Accessor: !scancode (inst )
-- Accessor: !screen (inst )
-- Accessor: !scroll-deltas (inst )
-- Accessor: !scroll-direction (inst )
-- Accessor: !seat (inst )
-- Accessor: !source-device (inst )
-- Accessor: !state (inst )
-- Accessor: !time (inst )
-- Accessor: !window (inst )
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 ‘’ 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
(https://developer.gnome.org/gdk3/stable/gdk3-Events.html)
documentation for a description of the event (struct) element
accessor returned value.
To complete the above listed ‘’ 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 )
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 )
-- Accessor: !y (inst )
-- Accessor: !root-x (inst )
-- Accessor: !root-y (inst )
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 *note !coords:: and *note !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 *note 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 *note :: 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 (https://docs.gtk.org/gdk4/index.html), GdkEvent is a
class(1). 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.
---------- Footnotes ----------
(1) From a GI point of view - internally, it is a C struct.
GObject
-------
G-Golf GObject interfaces.
The G-Golf integration with the GLib Object System.
^{_} SPECIAL NOTE ^{_}
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 *note Getting Started with
G-Golf:: sections, the description of this (and related) sections and in
the examples that come with G-Golf.
Classes
-------
‘*note ::’
‘*note ::’
‘*note ::’
‘*note ::’
‘*note ::’
Procedures, Accessors and Methods
---------------------------------
‘*note gobject-class?::’
‘*note !info::’
‘*note !derived::’
‘*note !namespace::’
‘*note !g-type::’
‘*note !g-name (2)::’
‘*note !g-class::’
‘*note !g-inst::’
‘*note unref::’
Description
-----------
GObject(1) is the GLib Object System.
The GLib Object System (https://developer.gnome.org/gobject/stable/) - a
C based object-oriented framework and APIs - is composed of three
principal elements: (1) GType(2), the lower-level GLib Dynamic Type
System (https://developer.gnome.org/gobject/stable/chapter-gtype.html),
(2) GObject, the base object type
(https://developer.gnome.org/gobject/stable/chapter-gobject.html) and
(3) the GObject closures and signals messaging system
(https://developer.gnome.org/gobject/stable/chapter-signal.html).
All the GNOME libraries that use the GLib type system inherit from
GObject
(https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html),
the base object type, which provides methods for object construction and
destruction, property access methods, and signal support.
G-Golf uses GOOPS(3) and defines the *note :: class, from which
all imported GNOME libraries inherit, as their class hierarchy is being
built in Guile Scheme.
Classes
-------
-- Class:
The base class of the GLib Object System.
It is an instance of *note ::.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
‘’
(No direct slot)
-- Class:
The base class for GLib's interface types. Not derivable in
Scheme.
It is an instance of *note ::.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
‘’
(No direct slot)
-- Class:
The metaclass of the *note :: and *note ::
classes.
It is an instance of ‘’.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
‘’
‘’
(No direct slot)
-- 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 ‘’.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
‘’
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 *note :: 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 *note GOOPS Notes and Conventions::,
'Slots are not Immutable').
-- Accessor: !info (inst )
-- Accessor: !derived (inst )
-- Accessor: !namespace (inst )
-- Accessor: !g-type (inst )
-- Accessor: !g-name (inst )
-- Accessor: !g-class (inst )
Returns the content of their respective slot for INST.
-- Class:
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 *note ::.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
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 *note GOOPS Notes and
Conventions::, 'Slots are not Immutable').
-- Accessor: !g-inst (inst )
Returns the content of the G-INST slot for INSTANCE.
-- Method: unref (inst )
Returns nothing.
This method calls *note 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_ instances is a now
feature [since August 2021].
Procedures
----------
-- Procedure: gobject-class? val
Returns #t if VAL is a class and if *note :: is a member
of its class precedence list. Otherwise, it returns #f.
---------- Footnotes ----------
(1) The name GObject, depending on the context, can actually be used
and refer to the GLib Object System
(https://developer.gnome.org/gobject/stable/) language system as a all,
or be used and refer to the fundamental type implementation, the base
object type
(https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html),
upon which GNOME libraries object hierarchies are based.
(2) The name GType, depending on the context, can actually be used
and refer to the The GLib Dynamic Type System
(https://developer.gnome.org/gobject/stable/chapter-gtype.html), or be
used and refer to the type it denotes, a unique ID (Identifier) - an
‘unsigned-long’ to be precise.
(3) The Guile Object Oriented System (*note (guile)GOOPS::). If you
haven't done so already, please make sure you read both the *note Naming
Conventions:: and *note GOOPS Notes and Conventions:: sections.
G-Golf Valley
=============
Cache Park
----------
Cache Park - Accessing G-Golf caches.
Procedures
----------
‘*note gi-cache-show::’
‘*note gi-cache-ref::’
Variables
---------
‘*note %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 *note ::, *note :: and *note
:: 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 *note %gi-cache:: entry or ‘#f’.
Obtains and returns the *note %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 *note 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 *note 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 = #< 7ff938938b40>
(gi-cache-ref 'enum 'gtk-position-type)
⇒ $3 = #< 7ff938938b40>
(describe $3)
⊣ #< 7ff938938b40> is an instance of class
⊣ 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
---------------------
‘*note g-name-transform-exception::’
‘*note g-name-transform-exception?::’
‘*note g-name-transform-exception-add::’
‘*note g-name-transform-exception-remove::’
‘*note g-name-transform-exception-reset::’
‘*note g-studly-caps-expand-token-exception::’
‘*note g-studly-caps-expand-token-exception?::’
‘*note g-studly-caps-expand-token-exception-add::’
‘*note g-studly-caps-expand-token-exception-remove::’
‘*note g-studly-caps-expand-token-exception-reset::’
‘*note gi-strip-boolean-result::’
‘*note gi-strip-boolean-result?::’
‘*note gi-strip-boolean-result-add::’
‘*note gi-strip-boolean-result-remove::’
‘*note gi-strip-boolean-result-reset::’
‘*note gi-method-short-name-skip::’
‘*note gi-method-short-name-skip?::’
‘*note gi-method-short-name-skip-all::’
‘*note gi-method-short-name-skip-add::’
‘*note gi-method-short-name-skip-remove::’
‘*note gi-method-short-name-skip-reset::’
‘*note syntax-name-protect-prefix::’
‘*note syntax-name-protect-prefix-set::’
‘*note syntax-name-protect-prefix-reset::’
‘*note syntax-name-protect-postfix::’
‘*note syntax-name-protect-postfix-set::’
‘*note syntax-name-protect-postfix-reset::’
‘*note syntax-name-protect-renamer::’
‘*note syntax-name-protect-renamer-set::’
‘*note syntax-name-protect-renamer-reset::’
‘*note 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 (*Note Naming Conventions::),
mainly to (a) avoid ‘Camel Case
(https://en.wikipedia.org/wiki/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 *note g-name->class-name::,
which calls *note g-name->name::;
• *note g-name->name:: first calls *note
g-name-transform-exception?:: and returns its value if it found
one, otherwise, it calls *note g-studly-caps-expand::;
• *note g-studly-caps-expand::, which does the core of the job, uses
*note 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(1).
As a consequence *note :: (as opposed to ‘’ 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(2)
(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 ‘’ 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 ‘’.
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
*note syntax-name->method-name:: does(3), 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:
*note syntax-name-protect-prefix::‘#f’
*note syntax-name-protect-postfix::‘'_’(the symbol _)
*note syntax-name-protect-renamer::‘#f’
---------- Footnotes ----------
(1) This is the only name for which G-Golf maintains compatibility
with Guile-GNOME (which has a long list of exceptions)..
(2) Note that the raised exception message and formatting depends on
the version of guile you are using. Fwiw, this example was produced
using ‘GNU Guile 3.0.8’.
(3) Users should normally not call this procedure - except for
testing purposes, if/when they customize its default settings - it is
appropriately and automatically called by G-Golf when importing a GI
typelib.
VFunc Alley
-----------
VFunc Alley - VFunc G-Golf support.
^{_} SPECIAL NOTES ^{_}
For completion, this section exposes the definition of the *note
:: class and *note 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
-----
‘*note ::’
Syntaxes and Accessors
----------------------
‘*note define-vfunc::’
‘*note vfunc::’
‘*note !specializer::’
‘*note !name_______::’
‘*note !g-name_______::’
‘*note !long-name-prefix::’
‘*note !gf-long-name?::’
‘*note !info__::’
‘*note !callback::’
Special Form
------------
‘*note 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
(https://docs.gtk.org/gobject/tutorial.html):
• 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 *note 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 (*Note
(guile)Methods and Generic Functions::).
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 ( )
(i #:accessor !i #:init-keyword #:i)
(j #:accessor !j #:init-keyword #:j))
(define-vfunc (get-flags-vfunc (self ))
'(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 *note define-vfunc:: definition.
Class
-----
-- Class:
The base class of all virtual method.
It is an instance of ‘’.
Superclasses are:
‘’
Class Precedence List:
‘’
‘’
‘’
‘’
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 *note 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(1).
• if more then one instance specializer superclasses has a VFunc
name, then the scheme name must be a so-called long name(2),
followed by the ‘-vfunc’ postfix(3).
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 *note
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
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 ))
(g-source-remove (!source-id self))
;; This vfunc must 'chain-up' - call the parent
;; finalize virtual method.
(next-vfunc))
---------- Footnotes ----------
(1) This is because most of the cases, in the upstream lib, the VFunc
is a virtual public method, that is, both a method and a VFunc exist
that use the same name. When that happens, the upstream lib method
normally has the same arity and definition (spec), and it 'just' calls
the VFunc - however, it is (unfortunately) not guaranteed to always be
the case, hence all GI lang bindings impose a specific VFunc naming
convention. Pygobject for example imposes to use a ‘do-’ prefix. In
G-Golf, we opted for a ‘-vfunc’ postfix.
(2) It must be prefixed using the scheme representation name of the
GObject or Interface that owns the Vfunc, followed by ‘-’ (hyphen), i.e.
gdk-paintable-get-flags-vfunc is the valid define-vfunc long name for
the get_flags virtual method of the GdkPaintable interface.
(3) Otherwise, it would be impossible to deternine which iface or
gobject class struct the *-vfunc user code is meant to override.
Consider (define-class ( )), with both
and defining a get_flags VFunc: in this context (define-vfunc
(get-flags-vfunc (self ))...) is an invalid definition, as it is
not possible for G-Golf to deternine if it is the or the
iface class struct VFunc that must be overridden. In such cases, the
user must pass a method long name, i.e. (define-vfunc
(bar-get-flags-vfunc (self )) ...) or (define-vfunc
(baz-get-flags-vfunc (self )) ...).
Utils Arcade
------------
Utils Arcade. G-Golf utilities.
Syntax
------
‘*note scm->g-type::’
‘*note allocate-c-struct::’
Description
-----------
Welcome to the G-Golf Utils Arcade.
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 *note
%g-type-fundamental-types:: member) or a .
-- Syntax: allocate-c-struct name . fields
Returns a (or more) pointer(s).
This syntax takes the NAME of a GI upstream library C struct(1) 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)
...)
---------- Footnotes ----------
(1) More specifically, an unquoted scheme representation name of a GI
upstream library C struct.
III. G-Golf Core Reference
**************************
Overview
========
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 (https://developer.gnome.org/glib/stable/glib-Memory-Allocation.html)’
*note Memory Allocation::
‘(g-golf glib mem-alloc)’
‘The Main Event Loop (https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html)’
*note The Main Event Loop::
‘(g-golf glib main-event-loop)’
‘...’
*GObject*
‘Type Information (https://developer.gnome.org/gobject/stable/gobject-Type-Information.html)’
*note Type Information::
‘(g-golf gobject type-info)’
‘GObject (https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html)’
*note GObject_::
‘(g-golf gobject gobject)’
‘Enumeration and Flag Types (https://developer.gnome.org/gobject/stable/gobject-Enumeration-and-Flag-Types.html)’
*note Enumeration and Flag Types::
‘(g-golf gobject enum-flags)’
‘...’
*GObject Introspection*
‘GIRepository (https://developer.gnome.org/gi/stable/GIRepository.html)’
*note Repository::
‘(g-golf gi repository)’
‘common types (https://developer.gnome.org/gi/stable/gi-common-types.html)’
*note Common Types::
‘(g-golf gi common-types)’
‘GIBaseInfo (https://developer.gnome.org/gi/stable/gi-GIBaseInfo.html)’
*note 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 ...)’ ...
Glib
====
G-Golf Glib modules are defined in the ‘glib’ subdirectory, such as
‘(g-golf glib main-event-loop)’.
Where you may load these modules individually, the easiest way to use
G-Golf Glib is to import its main module, which imports and re-exports
the public interface of (oop goops), (system foreign), all G-Golf
support and G-Golf Glib modules:
(use-modules (g-golf glib))
G-Golf Glib low level API modules correspond to a Glib section, though
they might be some exception in the future.
Version Information (1)
-----------------------
G-Golf Glib Version Information low level API.
Version Information — variables and functions to check the GLib version.
Procedures
----------
‘*note glib-get-major-version::’
‘*note glib-get-minor-version::’
‘*note 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
----------
‘*note g-malloc::’
‘*note g-malloc0::’
‘*note g-free::’
‘*note g-memdup::’
Description
-----------
These functions provide support for allocating and freeing memory.
Please read the Memory Allocation
(https://developer.gnome.org/glib/stable/glib-Memory-Allocation.html)
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
----------
‘*note g-main-loop-new::’
‘*note g-main-loop-run::’
‘*note g-main-loop-ref::’
‘*note g-main-loop-unref::’
‘*note g-main-loop-quit::’
‘*note g-main-context-new::’
‘*note g-main-context-default::’
‘*note g-timeout-source-new::’
‘*note g-timeout-source-new-seconds::’
‘*note g-idle-source-new::’
‘*note g-source-ref-count::’
‘*note g-source-ref::’
‘*note g-source-unref::’
‘*note g-source-free::’
‘*note g-source-attach::’
‘*note g-source-destroy::’
‘*note g-source-is-destroyed?::’
‘*note g-source-set-priority::’
‘*note g-source-get-priority::’
‘*note 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
(https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html)
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 *note 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 *note
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 *note 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 *note 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 *note 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 *note 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 *note 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 *note 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
----------
‘*note g-io-channel-unix-new::’
‘*note g-io-channel-ref::’
‘*note g-io-channel-unref::’
‘*note g-io-create-watch::’
Types and Values
----------------
‘*note %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
(https://developer.gnome.org/glib/stable/glib-IO-Channels.html) 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 *note %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 : %g-io-condition
An instance of ‘’, 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
----------
‘*note g-get-prgname::’
‘*note g-set-prgname::’
‘*note g-get-system-data-dirs::’
‘*note g-get-system-config-dirs::’
‘*note 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
(http://www.freedesktop.org/Standards/basedir-spec). 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
(http://www.freedesktop.org/Standards/basedir-spec). 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
----------
‘*note 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 *note %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
----------
‘*note g-list-data::’
‘*note g-list-next::’
‘*note g-list-prev::’
‘*note g-list-free::’
‘*note g-list-length::’
‘*note 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
(https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html)
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
----------
‘*note g-slist-data::’
‘*note g-slist-next::’
‘*note g-slist-append::’
‘*note g-slist-prepend::’
‘*note g-slist-free::’
‘*note g-slist-length::’
‘*note 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 *note Doubly-Linked Lists::, which allow movement in both
directions).
Please read the Singly-Linked-Lists
(https://developer.gnome.org/glib/stable/glib-Singly-Linked-Lists.html)
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 *note 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
----------
‘*note g-bytes-new::’
Description
-----------
FIXME
Procedures
----------
-- Procedure: g-bytes-new data size
Returns a pointer.
Create a new ‘GBytes’(1) from ‘data’.
‘data’ is copied. If ‘size’ is 0, ‘data’ may be NULL.
---------- Footnotes ----------
(1) A simple refcounted data type representing an immutable sequence
of zero or more bytes from an unspecified origin.
Quarks
------
G-Golf Glib Quarks low level API.
Quarks — a 2-way association between a string and a unique integer
identifier.
Procedures
----------
‘*note g-quark-from-string::’
‘*note 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.
GObject
=======
G-Golf GObject modules are defined in the ‘gobject’ subdirectory, such
as ‘(g-golf gobject enum-flags)’.
Where you may load these modules individually, the easiest way to use
G-Golf is to import its main module, which imports and re-exports the
public interface of (oop goops), (system foreign), all G-Golf support
and G-Golf GObject modules:
(use-modules (g-golf gobject))
G-Golf GObject low level API modules correspond to a GObject section,
though they might be some exception in the future.
Type Information
----------------
G-Golf GObject Type Information low level API.
Type Information — The GLib Runtime type identification and management
system
Procedures
----------
‘*note g-type->symbol::’
‘*note symbol->g-type::’
‘*note g-type-from-class::’
‘*note g-type-name::’
‘*note g-type-from-name::’
‘*note g-type-parent::’
‘*note g-type-is-a::’
‘*note g-type-class-ref::’
‘*note g-type-class-peek::’
‘*note g-type-class-unref::’
‘*note g-type-class-peek-parent::’
‘*note g-type-interface-peek::’
‘*note g-type-interfaces::’
‘*note g-type-query::’
‘*note g-type-register-static-simple::’
‘*note g-type-add-interface-static::’
‘*note g-type-fundamental::’
‘*note g-type-ensure::’
Types and Values
----------------
‘*note %g-type-fundamental-flags::’
‘*note %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
(https://developer.gnome.org/gobject/stable/gobject-Type-Information.html)
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 : %g-type-fundamental-flags
Bit masks used to check or determine specific characteristics of a
fundamental type.
An instance of ‘’, 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 : %g-type-fundamental-types
An instance of ‘’, 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(1)
_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 *note
GParamSpec:: types are derived.
‘object’
The fundamental type for *note GObject_::.
---------- Footnotes ----------
(1) There is no corresponding ‘enum’ in GOject. These fundamental
types (in GObject) are defined using a macro, ‘G_TYPE_MAKE_FUNDAMENTAL’,
that applies bitwise arithmetic shift given by
‘G_TYPE_FUNDAMENTAL_SHIFT’ (which we also have to apply, to get to the
type ID for the fundamental number ‘x’).
GObject
-------
G-Golf GObject low level API.
GObject — The base object type
Procedures
----------
‘*note g-object-class-install-property::’
‘*note g-object-class-find-property::’
‘*note g-object-class-list-properties::’
‘*note g-object-new::’
‘*note g-object-new-with-properties::’
‘*note g-object-ref::’
‘*note g-object-unref::’
‘*note g-object-ref-sink::’
‘*note g-object-ref-count::’
‘*note g-object-is-floating::’
‘*note g-object-add-toggle-ref::’
‘*note g-object-remove-toggle-ref::’
‘*note g-object-type::’
‘*note g-object-type-name::’
‘*note g-object-get-property::’
‘*note 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
(https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html)
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).
If the pointer to the GObject may be reused in future (for example,
if it is an instance variable of another object), it is recommended
to clear the pointer to NULL rather than retain a dangling pointer
to a potentially invalid GObject instance. Use ‘g-clear-object’
for this.
-- 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
(https://docs.gtk.org/gobject/method.Object.add_toggle_ref.html)
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 *note 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, *note
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, *note 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
----------
‘*note g-boxed-free::’
‘*note 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
(https://developer.gnome.org/gobject/stable/gobject-Boxed-Types.html)
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
----------
‘*note g-value-size::’
‘*note g-value-new::’
‘*note g-value-init::’
‘*note 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
*note g-value-new::, which create a zero-filled GValue structure. To
create and initialize a GValue, use the *note 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
(https://developer.gnome.org/gobject/stable/gobject-Generic-Values.html)
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 *note
%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
----------------------
‘*note g-value-type::’
‘*note g-value-type-tag::’
‘*note g-value-type-name::’
‘*note g-value-ref::’
‘*note g-value-set!::’
‘*note g-param-spec-boolean::’
‘*note g-value-get-boolean::’
‘*note g-value-set-boolean::’
‘*note g-param-spec-int::’
‘*note g-value-get-int::’
‘*note g-value-set-int::’
‘*note g-param-spec-uint::’
‘*note g-value-get-uint::’
‘*note g-value-set-uint::’
‘*note g-param-spec-float::’
‘*note g-value-get-float::’
‘*note g-value-set-float::’
‘*note g-param-spec-double::’
‘*note g-value-get-double::’
‘*note g-value-set-double::’
‘*note g-param-spec-enum::’
‘*note g-value-get-enum::’
‘*note g-value-set-enum::’
‘*note g-param-spec-flags::’
‘*note g-value-get-flags::’
‘*note g-value-set-flags::’
‘*note g-param-spec-string::’
‘*note g-value-get-string::’
‘*note g-value-set-string::’
‘*note g-param-spec-param::’
‘*note g-value-get-param::’
‘*note g-value-set-param::’
‘*note g-param-spec-boxed::’
‘*note g-value-get-boxed::’
‘*note g-value-set-boxed::’
‘*note g-value-get-pointer::’
‘*note g-value-set-pointer::’
‘*note g-param-spec-object::’
‘*note g-value-get-object::’
‘*note g-value-set-object::’
‘*note g-value-get-variant::’
Types and Values
----------------
‘*note g-type-param-boolean::’
‘*note g-type-param-char::’
‘*note g-type-param-uchar::’
‘*note g-type-param-int::’
‘*note g-type-param-uint::’
‘*note g-type-param-long::’
‘*note g-type-param-ulong::’
‘*note g-type-param-int64::’
‘*note g-type-param-uint64::’
‘*note g-type-param-float::’
‘*note g-type-param-double::’
‘*note g-type-param-enum::’
‘*note g-type-param-flags::’
‘*note g-type-param-string::’
‘*note g-type-param-param::’
‘*note g-type-param-boxed::’
‘*note g-type-param-pointer::’
‘*note g-type-param-object::’
‘*note g-type-param-unichar::’
‘*note g-type-param-override::’
‘*note g-type-param-gtype::’
‘*note 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 *note
%g-type-fundamental-types::) or the ‘GType’ name (see *note
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 ‘’ 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 )
-- Method: g-value-set-enum g-value (sym )
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 ‘’ 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 )
-- Method: g-value-set-flags g-value (flags )
Returns nothing.
Sets the content of G-VALUE to VAL, or to the value given by
calling *note 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
*note !is-opaque?:: or *note !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 *note
!is-opaque?:: or *note !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 ‘’ 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
----------
‘*note gi-g-param-spec-show::’
‘*note g-param-spec-type::’
‘*note g-param-spec-type-name::’
‘*note g-param-spec-get-default-value::’
‘*note g-param-spec-get-name::’
‘*note g-param-spec-get-nick::’
‘*note g-param-spec-get-blurb::’
‘*note g-param-spec-get-flags::’
Types and Values
----------------
‘*note %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 = #
(gi-import-by-name "Gtk" "Label")
⇒ $3 = #< 7f1a75436a50>
(!g-class )
⇒ $4 = #
(g-object-class-find-property $4 "css-classes")
⇒ $5 = #
(gi-g-param-spec-show $5)
⊣
⊣ # 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 ‘(*note 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 *note
%g-param-flags:: that applies to P-SPEC.
Types and Values
----------------
-- Instance Variable of : %g-param-flags
An instance of ‘’, 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
----------
‘*note g-closure-size::’
‘*note g-closure-ref-count::’
‘*note g-closure-ref::’
‘*note g-closure-sink::’
‘*note g-closure-unref::’
‘*note g-closure-free::’
‘*note g-closure-invoke::’
‘*note g-closure-add-invalidate-notifier::’
‘*note g-closure-new-simple::’
‘*note g-closure-set-marshal::’
‘*note 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
(https://developer.gnome.org/gobject/stable/gobject-Closures.html)
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. *note
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, *note g-closure-sink:: does
nothing.
Because *note g-closure-sink:: may decrement the reference count of
CLOSURE (if it hasn't been called on closure yet) just like *note
g-closure-unref::, *note 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
----------
‘*note g-signal-newv::’
‘*note g-signal-query::’
‘*note g-signal-lookup::’
‘*note g-signal-list-ids::’
‘*note g-signal-emitv::’
‘*note g-signal-connect-closure-by-id::’
‘*note g-signal-handler-disconnect::’
‘*note g-signal-parse-name::’
Types and Values
----------------
‘*note %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
(https://developer.gnome.org/gobject/stable/gobject-Signals.html)
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 *note %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 *note
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(1), flags, return-type, number of arguments and
their types. For example(2):
,use (g-golf)
(gi-import "Clutter")
(make )
⇒ $2 = #< 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 *note 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 *note 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 .
-- Procedure: g-signal-parse-name detailed-signal g-type
[force-detail-quark #t]
Returns two integer values.
Obtains and returns the signal-id and a detail corresponding to
DETAILED-SIGNAL for G-TYPE. The DETAILED-SIGNAL can be passed as a
symbol or a string. When FORCE-DETAIL-QUARK is ‘#t’ it forces the
creation of a ‘GQuark’ for the detail.
If the signal name could not successfully be parsed, it raises an
exception.
Types and Values
----------------
-- Instance Variable of : %g-signal-flags
The signal flags are used to specify a signal's behaviour, the
overall signal description outlines how especially the RUN flags
control the stages of a signal emission.
An instance of ‘’, who's members are the scheme
representation of the ‘GSignalFlags’:
_g-name_: GSignalFlags
_name_: g-signal-flags
_enum-set_:
‘run-first’
Invoke the object method handler in the first
emission stage.
‘run-last’
Invoke the object method handler in the third
emission stage.
‘run-cleanup’
Invoke the object method handler in the last
emission stage.
‘no-recurse’
Signals being emitted for an object while currently
being in emission for this very object will not be
emitted recursively, but instead cause the first
emission to be restarted.
‘detailed’
This signal supports "::detail" appendices to the
signal name upon handler connections and emissions.
‘action’
Action signals are signals that may freely be
emitted on alive objects from user code via
‘g-signal-emit’ and friends, without the need of
being embedded into extra code that performs pre or
post emission adjustments on the object. They can
also be thought of as object methods which can be
called generically by third-party code.
‘no-hooks’
No emissions hooks are supported for this signal.
‘must-collect’
Varargs signal emission will always collect the
arguments, even if there are no signal handlers
connected. Since 2.30.
‘deprecated’
The signal is deprecated and will be removed in a
future version. A warning will be generated if it
is connected while running with
‘G_ENABLE_DIAGNOSTIC=1’. Since 2.32.
---------- Footnotes ----------
(1) Within this context, the interface-type is the ‘GType’ of the
‘GObject’ subclass the signal is ‘attached to’ - knowing that signals
are inhereted.
(2) At least one ‘GObject’ subclass instance must have been created
prior to attempt to query any of its class signal(s).
GObject Introspection
=====================
G-Golf GObject Introspection modules are defined in the ‘gi’
subdirectory, such as ‘(g-golf gi repository)’.
Where you may load these modules individually, the easiest way to use
G-Golf GObject Introspection is to import the ‘g-golf’ module, which
imports and re-exports the public interface of all modules used and
defined by G-Golf (for a complete list, visit its source definition):
(use-modules (g-golf))
Most G-Golf GObject Introspection modules correspond to a GObject
Intropection (manual) section, but there are some exceptions, such as
‘init’ and ‘utils’ ...
Repository
----------
G-Golf Introspection Repository low level API.
GIRepository — GObject Introspection repository manager.
Procedures
----------
‘*note g-irepository-get-default::’
‘*note g-irepository-get-dependencies::’
‘*note g-irepository-get-loaded-namespaces::’
‘*note g-irepository-get-n-infos::’
‘*note g-irepository-get-info::’
‘*note g-irepository-enumerate-versions::’
‘*note g-irepository-get-typelib-path::’
‘*note g-irepository-require::’
‘*note g-irepository-get-c-prefix::’
‘*note g-irepository-get-shared-library::’
‘*note g-irepository-get-version::’
‘*note g-irepository-find-by-gtype::’
‘*note g-irepository-find-by-name::’
Description
-----------
‘GIRepository’ is used to manage repositories of namespaces. Namespaces
are represented on disk by type libraries (.typelib files).
Object Hierarchy
----------------
GObject
|___ GIRepository
Procedures
----------
Note: in this section, when the #:REPOSITORY optional keyword argument
is passed, it is [must be] a pointer to a ‘GIRepository’. Its default
value is ‘#f’, the scheme representation for ‘NULL’, meaning the
singleton process-global default ‘GIRepository’ (*note
g-irepository-get-default::).
-- Procedure: g-irepository-get-default
Returns a pointer to the singleton process-global default
‘GIRepository’.
GObject Introspection does not currently support multiple
repositories in a particular process, but this procedure is
provided in the unlikely eventuality that it would become possible.
All G-Golf low level API procedures on GIRepository also accept an
optional #:REPOSITORY keyword argument which defaults to ‘#f’,
meaning this singleton process-global default ‘GIRepository’.
-- Procedure: g-irepository-get-dependencies namespace [#:repository
#f]
Returns a list of all (transitive) versioned dependencies for
NAMESPACE. Returned string are of the form ‘namespace-version’.
Note: The NAMESPACE must have already been loaded using a procedure
such as ‘g-irepository-require’ before calling this procedure.
-- Procedure: g-irepository-get-loaded-namespaces [#:repository #f]
Return the list of currently loaded namespaces.
-- Procedure: g-irepository-get-n-infos namespace [#:repository #f]
Returns the number of metadata entries in NAMESPACE. The NAMESPACE
must have already been loaded before calling this procedure.
-- Procedure: g-irepository-get-info namespace index [#:repository #f]
Returns a pointer to a particular metadata entry in the given
NAMESPACE.
The NAMESPACE must have already been loaded before calling this
procedure. See ‘g-irepository-get-n-infos’ to find the maximum
number of entries.
INDEX is a 0-based offset into NAMESPACE for entry.
-- Procedure: g-irepository-enumerate-versions namespace [#:repository
#f]
Returns a (possibly empty) list.
Obtains and returns an unordered (possibly empty) list of versions
(either currently loaded or available) for NAMESPACE in REPOSITORY.
-- Procedure: g-irepository-get-typelib-path namespace [#:repository
#f]
Returns the full path to the .typelib file NAMESPACE was loaded
from, if loaded. If NAMESPACE is not loaded or does not exist, it
will return ‘#f’. If the typelib for NAMESPACE was included in a
shared library, it returns the special string "".
-- Procedure: g-irepository-require namespace [#:version #f]
[#:repository #f]
Returns a pointer a ‘GITypelib’ structure, if the ‘Typelib’ file
for NAMESPACE exists. Otherwise, it raises an error.
Force the NAMESPACE to be loaded if it isn't already. If NAMESPACE
is not loaded, this procedure will search for a ‘".typelib"’ file
using the repository search path. In addition, a version version
of namespace may be specified. If version is not specified, the
latest will be used.
-- Procedure: g-irepository-get-c-prefix namespace [#:repository #f]
Returns the "C prefix", or the C level namespace associated with
the given introspection NAMESPACE. Each C symbol starts with this
prefix, as well each ‘GType’ in the library.
Note: The NAMESPACE must have already been loaded using a procedure
such as ‘g-irepository-require’ before calling this procedure.
-- Procedure: g-irepository-get-shared-library namespace [#:repository
#f]
Returns a list of paths to the shared C libraries associated with
the given NAMESPACE. There may be no shared library path
associated, in which case this procedure will return an empty list.
-- Procedure: g-irepository-get-version namespace [#:repository #f]
Returns the loaded version associated with the given NAMESPACE.
Note: The NAMESPACE must have already been loaded using a procedure
such as ‘g-irepository-require’ before calling this procedure.
-- Procedure: g-irepository-find-by-gtype gtype [#:repository #f]
Returns a pointer to a ‘GIBaseInfo’ representing metadata about
GTYPE, or ‘#f’.
Searches all loaded namespaces for a particular ‘GType’. Note that
in order to locate the metadata, the namespace corresponding to the
type must first have been loaded. There is currently no mechanism
for determining the namespace which corresponds to an arbitrary
‘GType’ - thus, this procedure will operate most reliably when you
know the ‘GType’ to originate from be from a loaded namespace.
-- Procedure: g-irepository-find-by-name namespace name [#:repository
#f]
Returns a pointer to a ‘GIBaseInfo’ representing metadata about
type, or ‘#f’.
Searches for a particular entry in NAMESPACE. Before calling this
function for a particular namespace, you must call
‘g-irepository-require’ once to load the NAMESPACE, or otherwise
ensure the NAMESPACE has already been loaded.
Typelib
-------
G-Golf Typelib low level API.
GITypelib — Layout and accessors for typelib.
Procedures
----------
‘*note g-golf-typelib-new::’
‘*note call-with-input-typelib::’
‘*note g-typelib-new-from-memory::’
‘*note g-typelib-free::’
‘*note g-typelib-get-namespace::’
Description
-----------
TODO.
Procedures
----------
Note: in this section, the TYPELIB argument is [must be] a pointer to a
‘GITypelib’.
-- Procedure: g-golf-typelib-new file
Returns a pointer to a new ‘GITypelib’.
FILE must be a valid typelib filename.
This procedure actually sets things up and calls *note
g-typelib-new-from-memory::.
-- Procedure: call-with-input-typelib file proc
Returns the value(s) returned by PROC.
FILE must be a valid typelib filename. Makes a new ‘GITypelib’ by
calling ‘(g-golf-typelib-new file)’ and calls ‘(proc typelib)’ with
the resulting ‘GITypelib’.
When PROC returns, the ‘GITypelib’ is free'd by calling
‘g-typelib-free’. Otherwise the [Glib - C] memory chunk might not
be free'd automatically, though the scheme pointer returned by
‘g-golf-typelib-new’ will be garbage collected in the usual way if
not otherwise referenced.
-- Procedure: g-typelib-new-from-memory pointer size gerror
Returns a pointer to a new ‘GITypelib’.
POINTER must be the address of a memory chunk containing the
typelib, SIZE is the number of bytes of the memory chunk containing
the typelib, and GERROR a pointer to a ‘GError’.
Creates a new ‘GITypelib’ from a memory location. The memory block
pointed to by typelib will be automatically ‘g_free()’d when the
repository is destroyed.
-- Procedure: g-typelib-free typelib
Returns nothing.
Free a GITypelib.
-- Procedure: g-typelib-get-namespace typelib
Returns the namespace of TYPELIB.
Common Types
------------
G-Golf Common Types low level API.
common types - TODO
Procedures
----------
‘*note g-type-tag-to-string::’
Types and Values
----------------
‘*note %gi-type-tag::’
‘*note %gi-array-type::’
Procedures
----------
-- Procedure: g-type-tag-to-string type-tag
Returns a string or ‘#f’.
Obtains the string representation for TYPE-TAG or ‘#f’ if it does
not exist (note that in this case, the upstream function returns
‘"unknown"’).
TYPE-TAG can either be an ‘id’ or a ‘symbol’, a member of the
‘enum-set’ of *note %gi-type-tag::.
Types and Values
----------------
-- Instance Variable of : %gi-type-tag
An instance of ‘’, who's members are the type tag of a
‘GITypeInfo’:
_g-name_: GITypeTag
_name_: gi-type-tag
_enum-set_:
void
boolean
int8
uint8
int16
uint16
int32
uint32
int64
uint64
float
double
gtype
utf8
filename
array
interface
glist
gslist
ghash
error
unichar
-- Instance Variable of : %gi-array-type
An instance of ‘’, who's members are the type of array in
a ‘GITypeInfo’:
_g-name_: GIArrayType
_name_: gi-array-type
_enum-set_:
c
array
ptr-array
byte-array
Version Information (2)
-----------------------
G-Golf GIRepository Version Informatrion low level API.
Version Information - Procedures to check the GIRepository version.
Procedures
----------
‘*note gi-version::’
‘*note gi-effective-version::’
‘*note gi-major-version::’
‘*note gi-minor-version::’
‘*note gi-micro-version::’
‘*note gi-check-version::’
Description
-----------
Procedures to check the GIRepository version.
Procedures
----------
-- Procedure: gi-version
-- Procedure: gi-effective-version
-- Procedure: gi-major-version [as-integer? #f]
-- Procedure: gi-minor-version [as-integer? #f]
-- Procedure: gi-micro-version [as-integer? #f]
Returns a string describing GIRepository full version number,
effective version number, major, minor or micro version number,
respectively.
The last three procedures will return the major, minor or micro
version number as an integer if the optional AS-INTEGER? argument
is ‘#t’.
-- Procedure: gi-check-version major minor micro
Returns ‘#t’ if the GIRepository version is the same as or newer
than the MAJOR MINOR MICRO passed-in version.
Base Info
---------
G-Golf Base Info low level API.
GIBaseInfo — Base struct for all GITypelib structs.
Procedures
----------
‘*note g-base-info-ref::’
‘*note g-base-info-unref::’
‘*note g-base-info-equal::’
‘*note g-base-info-get-type::’
‘*note g-base-info-get-typelib::’
‘*note g-base-info-get-namespace::’
‘*note g-base-info-get-name::’
‘*note g-base-info-get-attribute::’
‘*note g-base-info-iterate-attributes::’
‘*note g-base-info-get-container::’
‘*note g-base-info-is-deprecated::’
Types and Values
----------------
‘*note %gi-info-type::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIArgInfo
+-- GICallableInfo
+-- GIConstantInfo
+-- GIFieldInfo
+-- GIPropertyInfo
+-- GIRegisteredTypeInfo
+-- GITypeInfo
Description
-----------
‘GIBaseInfo’ is the common base struct of all other *Info structs
accessible through the ‘GIRepository API’.
Most ‘GIRepository APIs’ returning a ‘GIBaseInfo’ is actually creating a
new struct, in other words, *note g-base-info-unref:: has to be called
when done accessing the data. ‘GIBaseInfos’ are normally accessed by
calling either *note g-irepository-find-by-name::, *note
g-irepository-find-by-gtype:: or *note g-irepository-get-info::.
*Example:* Getting the Button of the Gtk typelib
,use (g-golf gi)
(g-irepository-require "Gtk")
(g-irepository-find-by-name "Gtk" "Button")
⇒ $4 = #
... use button info ...
(g-base-info-unref $4)
Procedures
----------
Note: in this section, the INFO, INFO1 and INFO2 arguments are [must be]
pointers to a ‘GIBaseInfo’.
-- Procedure: g-base-info-ref info
Returns the same INFO.
Increases the reference count of INFO.
-- Procedure: g-base-info-unref info
Returns nothing.
Decreases the reference count of INFO. When its reference count
drops to 0, the INFO is freed.
-- Procedure: g-base-info-equal info1 info2
Returns #t if and only if INFO1 equals INFO2.
Compares two ‘GIBaseInfo’.
Using pointer comparison is not practical since many functions
return different instances of ‘GIBaseInfo’ that refers to the same
part of the typelib: use this procedure instead to do ‘GIBaseInfo’
comparisons.
-- Procedure: g-base-info-get-type info
Returns the info type of INFO.
-- Procedure: g-base-info-get-typelib info
Returns a pointer to the ‘GITypelib’ the INFO belongs to.
-- Procedure: g-base-info-get-namespace info
Returns the namespace of INFO
-- Procedure: g-base-info-get-name info
Returns the name of INFO or ‘#f’ if it lacks a name.
What the name represents depends on the ‘GIInfoType’ of the info.
For instance for ‘GIFunctionInfo’ it is the name of the function.
-- Procedure: g-base-info-get-attribute info name
Returns the value of the attribute or ‘#f’ if not such attribute
exists.
-- Procedure: g-base-info-iterate-attributes info proc
Returns nothing.
Iterate and calls PROC over all attributes associated with this
node. PROC must be a procedure of two arguments, the NAME and the
VALUE of the attribute.
-- Procedure: g-base-info-get-container info
Returns a pointer to a ‘GIBaseInfo’.
The container is the parent ‘GIBaseInfo’. For instance, the parent
of a ‘GIFunctionInfo’ is an ‘GIObjectInfo’ or ‘GIInterfaceInfo’.
-- Procedure: g-base-info-is-deprecated info
Returns ‘#t’ if deprecated.
Obtain whether INFO represents a metadata which is deprecated or
not.
Types and Values
----------------
-- Instance Variable of : %gi-info-type
An instance of ‘’, who's members are the scheme
representation of the type of a ‘GIBaseInfo’ struct:
_g-name_: GIInfoType
_name_: gi-info-type
_enum-set_:
invalid
function
callback
struct
boxed
enum
flags
object
interface
constant
error-domain
union
value
signal
vfunc
property
field
arg
type
unresolved
Callable Info
-------------
G-Golf Callable Info low level API.
GICallableInfo — Struct representing a callable.
Procedures
----------
‘*note g-callable-info-can-throw-gerror::’
‘*note g-callable-info-get-n-args::’
‘*note g-callable-info-get-arg::’
‘*note g-callable-info-get-caller-owns::’
‘*note g-callable-info-get-instance-ownership-transfer::’
‘*note g-callable-info-get-return-type::’
‘*note g-callable-info-invoke::’
‘*note g-callable-info-is-method::’
‘*note g-callable-info-may-return-null::’
‘*note g-callable-info-create-closure::’
Struct Hierarchy
----------------
GIBaseInfoInfo
+-- GICallableInfo
+-- GIFunctionInfo
+-- GICallbackInfo
+-- GISignalInfo
+-- GIVFuncInfo
Description
-----------
‘GICallableInfo’ represents an entity which is callable. Examples of
callable are: functions (‘GIFunctionInfo’), virtual functions,
(‘GIVFuncInfo’), callbacks (‘GICallbackInfo’).
A callable has a list of arguments (‘GIArgInfo’), a return type,
direction and a flag which decides if it returns null.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GICallableInfo’.
-- Procedure: g-callable-info-can-throw-gerror info
Returns ‘#t’ if the callable INFO can throw a GError, otherwise it
returns ‘#f’.
-- Procedure: g-callable-info-get-n-args info
Returns the number of arguments this INFO expects.
Obtain the number of arguments (both IN and OUT) for this INFO.
-- Procedure: g-callable-info-get-arg info n
Returns a pointer to the Nth ‘GIArgInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-callable-info-get-caller-owns info
Returns a ‘GITransfer’ enumerated value.
See whether the caller owns the return value of this callable. See
*note %gi-transfer:: for the list of possible values.
-- Procedure: g-callable-info-get-instance-ownership-transfer info
Returns a ‘GITransfer’ enumerated value.
Obtains the ownership transfer for the instance argument. See
*note %gi-transfer:: for the list of possible values.
-- Procedure: g-callable-info-get-return-type info
Returns a pointer to the ‘GITypeInfo’.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-callable-info-invoke info function in-args n-in
out-args n-out r-val is-method throws g-error
Returns ‘#t’ if the function has been invoked, ‘#f’ if an error
occured.
Invokes the function described in INFO with the given arguments.
Note that i‘nout’ parameters must appear in both argument lists.
The arguments are:
‘_info_’
a pointer to a ‘GIFunctionInfo’ describing the function
to invoke.
‘_function_’
a pointer to the function to invoke.
‘_in-args_’
a pointer to an array of ‘GIArguments’, one for each ‘in’
and ‘inout’ parameter of INFO. If there are no ‘in’
parameter, IN-ARGS must be the ‘%null-pointer’.
‘_n-in_’
the length of the IN-ARGS array.
‘_out-args_’
a pointer to an array of ‘GIArguments’, one for each
‘out’ and ‘inout’ parameter of INFO. If there are no
‘out’ parameter, OUT-ARGS must be the ‘%null-pointer’.
‘_n-out_’
the length of the OUT-ARGS array.
‘_r-val_’
a pointer to a ‘GIArguments’, the return location for the
return value of the function. If the function returns
‘void’, R-VAL must be the ‘%null-pointer’.
‘_is-method_’
is the callable info is a method.
‘_throws_’
can the callable throw a ‘GError’.
‘_g-error_’
a pointer to a newly allocated (and ‘empty’) ‘GError’
(the recommended way for procedure calls that need such a
pointer is to ‘surround’ the call using *note
with-gerror::).
-- Procedure: g-callable-info-is-method info
Returns ‘#t’ if the callable INFO is a method, otherwise it return
‘#f’.
Determines if the callable INFO is a method. For ‘GIVFuncInfo’ and
‘GISignalInfo’, this is always true. Otherwise, this looks at the
‘GI_FUNCTION_IS_METHOD’ flag on the ‘GIFunctionInfo’.
Concretely, this function returns whether *note
g-callable-info-get-n-args:: matches the number of arguments in the
raw C method. For methods, there is one more C argument than is
exposed by introspection: the ‘self’ or ‘this’ object.
-- Procedure: g-callable-info-may-return-null info
Returns ‘#t’ if the callable INFO could return ‘NULL’.
See if a callable could return NULL.
-- Procedure: g-callable-info-create-closure info ffi-cif
ffi-closure-callback user-data
Returns the ffi-closure or ‘#f’ on error.
The return value should be freed by calling
‘g-callable-info-destroy-closure’.
Function Info
-------------
G-Golf Function Info low level API.
GIFunctionInfo — Struct representing a function.
Procedures
----------
‘*note gi-function-info-is-method?::’
‘*note g-function-info-get-flags::’
‘*note g-function-info-get-property::’
‘*note g-function-info-get-symbol::’
‘*note g-function-info-get-vfunc::’
‘*note g-function-info-invoke::’
Types and Values
----------------
‘*note %g-function-info-flags::’
Struct Hierarchy
----------------
GIBaseInfoInfo
+-- GICallableInfo
+-- GIFunctionInfo
+-- GISignalInfo
+-- GIVFuncInfo
Description
-----------
‘GIFunctionInfo’ represents a function, method or constructor. To find
out what kind of entity a GIFunctionInfo represents, call *note
g-function-info-get-flags::.
See also *note Callable Info:: for information on how to retreive
arguments and other metadata.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GIFunctionInfo’.
-- Procedure: gi-function-info-is-method? info [flags #f]
Returns ‘#t’ if INFO is a method, that is if ‘is-method’ is a
member of the INFO flags. Otherwise, it returns ‘#f’.
The optional FLAGS argument, if passed, must be the list of the
function info flags as returned by *note
g-function-info-get-flags::.
-- Procedure: g-function-info-get-flags info
Returns a list of *note %g-function-info-flags::.
Obtain the ‘GIFunctionInfoFlags’ for INFO.
-- Procedure: g-function-info-get-property info
Returns a pointer or ‘#f’.
Obtains the ‘GIPropertyInfo’ associated with INFO. Only
‘GIFunctionInfo’ with the flag ‘is-getter’ or ‘is-setter’ have a
property set. For other cases, ‘#f’ will be returned.
The ‘GIPropertyInfo’ must be freed by calling *note
g-base-info-unref:: when done.
-- Procedure: g-function-info-get-symbol info
Returns a string.
Obtain the ‘symbol’ of the function(1).
-- Procedure: g-function-info-get-vfunc info
Returns a pointer or ‘#f’.
Obtains the ‘GIVFuncInfo’ associated with INFO. Only
‘GIFunctionInfo’ with the flag ‘wraps-vfunc’ has its virtual
function set. For other cases, ‘#f’ will be returned.
The ‘GIVFuncInfo’ must be freed by calling *note
g-base-info-unref:: when done.
-- Procedure: g-function-info-invoke info in-args n-in out-args n-out
r-val g-error
Returns ‘#t’ if the function has been invoked, ‘#f’ if an error
occured.
Invokes the function described in INFO with the given arguments.
Note that i‘nout’ parameters must appear in both argument lists.
The arguments are:
‘_info_’
a pointer to a ‘GIFunctionInfo’ describing the function
to invoke.
‘_in-args_’
a pointer to an array of ‘GIArguments’, one for each ‘in’
and ‘inout’ parameter of INFO. If there are no ‘in’
parameter, IN-ARGS must be the ‘%null-pointer’.
‘_n-in_’
the length of the IN-ARGS array.
‘_out-args_’
a pointer to an array of ‘GIArguments’, one for each
‘out’ and ‘inout’ parameter of INFO. If there are no
‘out’ parameter, OUT-ARGS must be the ‘%null-pointer’.
‘_n-out_’
the length of the OUT-ARGS array.
‘_r-val_’
a pointer to a ‘GIArguments’, the return location for the
return value of the function. If the function returns
‘void’, R-VAL must be the ‘%null-pointer’.
‘_g-error_’
a pointer to a newly allocated (and ‘empty’) ‘GError’
(the recommended way for procedure calls that need such a
pointer is to ‘surround’ the call using *note
with-gerror::).
Types and Values
----------------
-- Instance Variable of : %g-function-info-flags
An instance of *note ::, who's members are the scheme
representation of the ‘GIFunctionInfoFlags’:
_g-name_: GIFunctionInfoFlags
_name_: gi-function-info-flags
_enum-set_:
‘is-method’
Is a method.
‘is-constructor’
Is a constructor.
‘is-getter’
Is a getter of a ‘GIPropertyInfo’.
‘is-setter’
Is a setter of a ‘GIPropertyInfo’.
‘wraps-vfunc’
Represent a virtul function.
‘throws’
The function may throw an error.
---------- Footnotes ----------
(1) As you have noticed already, since ‘g-function-info-get-symbol’
returns a string, in the Glib, GObject and GObject Instrospection
worlds, symbol has a different meaning then in the Lisp/Scheme worlds.
However, since the procedure is part of the G-Golf low-level API, we
decided to keep its name as close as the original name as possible,
which in ‘Glib’ terms is the name of the exported function, ‘suitable to
be used as an argument to g_module_symbol()’
Signal Info
-----------
G-Golf Signal Info low level API.
GISignalInfo — Struct representing a signal.
Procedures
----------
‘*note g-signal-info-get-flags::’
Description
-----------
‘GISignalInfo’ represents a signal. It's a sub-struct of
‘GICallableInfo’ and contains a set of flags and a class closure.
See also *note Callable Info:: for information on how to retreive
arguments and other metadata from the signal.
Struct Hierarchy
----------------
GIBaseInfoInfo
+-- GICallableInfo
+-- GIFunctionInfo
+-- GISignalInfo
+-- GIVFuncInfo
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GISignalInfo’.
-- Procedure: g-signal-info-get-flags info
Returns a list of *note %g-signal-flags::.
Obtain the flags for this signal info. See *note %g-signal-flags::
for more information about posible flag values.
VFunc Info
----------
G-Golf VFunc Info low level API.
GIVFuncInfo — Struct representing a virtual function
Procedures
----------
‘*note g-vfunc-info-get-flags::’
‘*note g-vfunc-info-get-offset::’
‘*note g-vfunc-info-get-signal::’
‘*note g-vfunc-info-get-invoker::’
Types and Values
----------------
‘*note %gi-vfunc-info-flags::’
Description
-----------
‘GIVFuncInfo’ represents a virtual function.
A virtual function is a callable object that belongs to either a *note
Object Info:: or a *note Interface Info::.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GIVFuncInfo’.
-- Procedure: g-vfunc-info-get-flags info
Returns a (possibly empty) list.
Obtains and returns the flags for the virtual function INFO. See
*note %gi-vfunc-info-flags:: for the possible flag values.
-- Procedure: g-vfunc-info-get-offset info
Returns an offset or ‘#f’.
Obtains and returns the offset of the virtual function in the class
struct. The value ‘#f’ indicates that the offset is unknown.
-- Procedure: g-vfunc-info-get-signal info
Returns a pointer or ‘#f’.
Obtains and returns a signal (a pointer to a *note Signal Info::)
for the virtual function if one is set. The signal comes from the
object or interface to which this virtual function belongs.
-- Procedure: g-vfunc-info-get-invoker info
Returns a pointer or ‘#f’.
If this virtual function has an associated invoker method, this
procedure will return it (a pointer to a *note Function Info::).
An invoker method is a C entry point.
Not all virtuals will have invokers.
The ‘GIFunctionInfo’, if one was returned, must be freed by calling
*note g-base-info-unref::
Types and Values
----------------
-- Instance Variable of : %gi-vfunc-info-flags
An instance of *note ::, who's members are the scheme
representation of the flags of a ‘GIVFuncInfo’:
_g-name_: GIVFuncInfoFlags
_name_: gi-vfunc-info-flags
_enum-set_:
‘must-chain-up’
‘must-override’
‘must-not-override’
‘throws’
Registered Type Info
--------------------
G-Golf Registered Type Info low level API.
GIRegisteredTypeInfo — Struct representing a struct with a ‘GType’.
Procedures
----------
‘*note gi-registered-type-info-name::’
‘*note g-registered-type-info-get-type-name::’
‘*note g-registered-type-info-get-type-init::’
‘*note g-registered-type-info-get-g-type::’
Struct Hierarchy
----------------
GIBaseInfo
+---GIRegisteredTypeInfo
+---GIEnumInfo
+---GIInterfaceInfo
+---GIObjectInfo
+---GIStructInfo
+---GIUnionInfo
Description
-----------
‘GIRegisteredTypeInfo’ represents an entity with a ‘GType’ associated.
Could be either a ‘GIEnumInfo’, ‘GIInterfaceInfo’, ‘GIObjectInfo’,
‘GIStructInfo’ or a ‘GIUnionInfo’.
A registered type info struct has a name and a type function.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GIRegisteredTypeInfo’.
-- Procedure: gi-registered-type-info-name info
Returns a type name.
Some registered type are not ‘registered’, and calling *note
g-registered-type-info-get-type-name:: returns ‘#f’(1).
Even though they are ‘unnamed’, some are present in their typelib,
like ‘"GLib" "SpawnFlags"’, or ‘"GObject" "ParamFlags"’, and may be
imported - sometimes manually, sometimes automatically.
In G-Golf, imported ‘GIRegisteredTypeInfo’ must have a unique name,
since it is used as the secondary key in its cache ‘mechanism’ (See
*note Cache Park::).
Obtains and returns a unique name for INFO. If *note
g-registered-type-info-get-type-name:: returns a name, that name is
returned. Otherwise, it returns a name composed of the ‘namespace’
and ‘name’ for INFO.
Here is an example, to illustrate:
(g-irepository-find-by-name "GObject" "ParamFlags")
⇒ $2 = #
(g-registered-type-info-get-type-name $2)
⇒ $3 = #f
(gi-registered-type-info-name $2)
⇒ $4 = "GObjectParamFlags"
(g-name->name $4)
⇒ $5 = g-object-param-flags
-- Procedure: g-registered-type-info-get-type-name info
Returns the type name.
Obtain the type name of the struct within the GObject type system.
This name can be passed to g_type_from_name to get a GType.
-- Procedure: g-registered-type-info-get-type-init info
Returns the name of the type init function.
Obtain the type init function for INFO. The type init function is
the function which will register the ‘GType’ within the ‘GObject’
type system. Usually this is not called by langauge bindings or
applications.
-- Procedure: g-registered-type-info-get-g-type info
Returns the ‘GType’ for INFO.
Obtain the ‘GType’ for this registered type or ‘G_TYPE_NONE’ which
has a special meaning. It means that either there is no type
information associated with this info or that the shared library
which provides the type_init function for this info cannot be
called.
---------- Footnotes ----------
(1) Another symptom for those is that if if you call ‘(*note
g-type-name:: g-type)’, it returns ‘"void"’.
Enum Info
---------
G-Golf Enum Info low level API.
GIEnumInfo — Structs representing an enumeration and its values.
Procedures
----------
‘*note gi-enum-import::’
‘*note gi-enum-value-values::’
‘*note g-enum-info-get-n-values::’
‘*note g-enum-info-get-value::’
‘*note g-enum-info-get-n-methods::’
‘*note g-enum-info-get-method::’
‘*note g-value-info-get-value::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIRegisteredTypeInfo
+-- GIEnumInfo
Description
-----------
‘GIEnumInfo’ represents an argument. An argument is always part of a
‘GICallableInfo’.
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIEumInfo’.
-- Procedure: gi-enum-import info
Returns a ‘’ instance.
Obtains the values this enumeration contains, then makes and
returns a ‘’ instance.
-- Procedure: gi-enum-value-values info
Returns an alist.
Obtains and returns the list pairs ‘(symbol . id)’ the enum GI
definition pointed by INFO contains. If you think the name is
strange, compare it with, for example *note
gi-struct-field-types::: just like a ‘GIStructInfo’ holds a list of
pointers to ‘GIFieldInfo’ from which we get the (field) type,
a‘GIEnumInfo’ holds a list of pointers to ‘GIValueInfo’ from which
we get the (enum) value - which in the GI world is a name (a
string) that we transform, in the scheme world, to a symbol.
-- Procedure: g-enum-info-get-n-values info
Returns the number of values.
Obtains the number of values this enumeration contains.
-- Procedure: g-enum-info-get-value info index
Returns a pointer to a ‘GIValueInfo’ or #f if type tag is wrong.
Obtains a value for this enumeration. The ‘GIValueInfo’ must be
free'd using ‘g-base-info-unref’ when done.
INDEX is a 0-based offset into INFO for a value.
-- Procedure: g-enum-info-get-n-methods info
Returns the number of methods.
Obtains the number of methods this enumeration has.
-- Procedure: g-enum-info-get-method info index
Returns a pointer to a ‘GIFunctionInfo’ or #f if type tag is wrong.
Obtains a method for this enumeration. The ‘GIFunctionInfo’ must
be free'd using ‘g-base-info-unref’ when done.
INDEX is a 0-based offset into INFO for a method.
-- Procedure: g-value-info-get-value info
Returns the enumeration value.
Obtains a value of the ‘GIValueInfo’.
INFO is [must be] a pointer to a ‘GIValueInfo’.
Struct Info
-----------
G-Golf Struct Info low level API.
GIStructInfo — Structs representing a C structure.
Procedures
----------
‘*note gi-struct-import::’
‘*note gi-struct-field-desc::’
‘*note gi-struct-field-types::’
‘*note g-struct-info-get-alignment::’
‘*note g-struct-info-get-size::’
‘*note g-struct-info-is-gtype-struct::’
‘*note g-struct-info-is-foreign::’
‘*note g-struct-info-get-n-fields::’
‘*note g-struct-info-get-field::’
‘*note g-struct-info-get-n-methods::’
‘*note g-struct-info-get-method::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIRegisteredTypeInfo
+-- GIStructInfo
Description
-----------
‘GIStructInfo’ represents a generic C strucuture type.
A structure has methods and fields.
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIStructInfo’.
-- Procedure: gi-struct-import info
Returns a ‘’ instance.
Obtains the list of (field) types the C struct GI definition
pointed by INFO contains, then makes and returns a ‘’
instance.
-- Procedure: gi-struct-field-desc info
Returns a list.
Obtains and returns the list of (field) descriptions for INFO. A
field description is a list: ‘(name type-tag offset flags)’.
-- Procedure: gi-struct-field-types info
Returns a list.
Obtains and returns the list of (field) types the C struct GI
definition pointed by INFO contains.
-- Procedure: g-struct-info-get-alignment info
Returns an integer.
Obtains and returns the required alignment for INFO.
-- Procedure: g-struct-info-get-size info
Returns an integer.
Obtains and returns the total size of the structure specified INFO.
-- Procedure: g-struct-info-is-gtype-struct info
Returns #t or #f.
Return true if the structure specified by INFO represents the
"class structure" for some GObject or GInterface.
-- Procedure: g-struct-info-is-foreign info
Returns #t or #f.
FIXME. No upstream documentation, though the procedure works.
-- Procedure: g-struct-info-get-n-fields info
Returns an integer.
Obtains the number of fields for INFO.
-- Procedure: g-struct-info-get-field info n
Returns a pointer.
Obtains and returns the INFO type information (a pointer to a
‘GIFieldInfo’) for the field at the specified N index.
The ‘GIFieldInfo’ must be freed by calling *note
g-base-info-unref:: when done.
-- Procedure: g-struct-info-get-n-methods info
Returns an integer.
Obtains the number of methods for INFO.
-- Procedure: g-struct-info-get-method info n
Returns a pointer.
Obtains and returns the INFO type information (a pointer to a
‘GIFunctionInfo’) for the method at the specified N index.
The ‘GIFunctionInfo’ must be freed by calling *note
g-base-info-unref:: when done.
Union Info
----------
G-Golf Union Info low level API.
GIUnionInfo — Struct representing a C union.
Procedures
----------
‘*note g-union-info-get-n-fields::’
‘*note g-union-info-get-field::’
‘*note g-union-info-get-n-methods::’
‘*note g-union-info-get-method::’
‘*note g-union-info-is-discriminated?::’
‘*note g-union-info-get-discriminator-offset::’
‘*note g-union-info-get-discriminator-type::’
‘*note g-union-info-get-discriminator::’
‘*note g-union-info-get-size::’
‘*note g-union-info-get-alignment::’
Description
-----------
‘GIUnionInfo’ represents a union type.
A union has methods and fields. Unions can optionally have a
discriminator, which is a field deciding what type of real union fields
is valid for specified instance.
Struct Hierarchy
----------------
GIBaseInfo
+-- GIRegisteredTypeInfo
+-- GIUnionInfo
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIUnionInfo’.
-- Procedure: g-union-info-get-n-fields info
Returns an integer.
Obtains and returns the number of fields the INFO union has.
-- Procedure: g-union-info-get-field info n
Returns a pointer.
Obtains and returns a pointer to the ‘GIFieldInfo’ for INFO, given
its N. The ‘GIFieldInfo’ must be free'd by calling *note
g-base-info-unref:: when done.
-- Procedure: g-union-info-get-n-methods info
Returns an integer.
Obtains and returns the number of methods the INFO union has.
-- Procedure: g-union-info-get-method info n
Returns a pointer.
Obtains and returns a pointer to the ‘GIFunctionInfo’ for INFO,
given its N, which must be free'd by calling *note
g-base-info-unref:: when done.
-- Procedure: g-union-info-is-discriminated? info
Returns #t if INFO contains a discriminator field, otherwise it
returns #f.
-- Procedure: g-union-info-get-discriminator-offset info
Returns an integer.
Obtains and returns the offset of the discriminator field for INFO.
-- Procedure: g-union-info-get-discriminator-type info
Returns a pointer.
Obtains and returns a pointer to the ‘GITypeInfo’ for INFO, which
must be free'd by calling *note g-base-info-unref:: when done.
-- Procedure: g-union-info-get-discriminator info n
Returns a pointer.
Obtains and returns a pointer to the ‘GIConstantInfo’ assigned for
the INFO N-th union field - i.e. the N-th union field is the
active one if discriminator contains this constant (value) - which
must be free'd by calling *note g-base-info-unref:: when done.
-- Procedure: g-union-info-get-size info
Returns an integer.
Obtains and returns the total size of the union specified by INFO.
-- Procedure: g-union-info-get-alignment info
Returns an integer.
Obtains and returns the required alignment for INFO.
Object Info
-----------
G-Golf Object Info low level API.
GIObjectInfo — Structs representing a GObject.
Procedures
----------
‘*note gi-object-show::’
‘*note gi-object-property-names::’
‘*note gi-object-method-names::’
‘*note gi-object-method-find-by-name::’
‘*note g-object-info-get-abstract::’
‘*note g-object-info-get-parent::’
‘*note g-object-info-get-type-name::’
‘*note g-object-info-get-type-init::’
‘*note g-object-info-get-n-constants::’
‘*note g-object-info-get-constant::’
‘*note g-object-info-get-n-fields::’
‘*note g-object-info-get-field::’
‘*note g-object-info-get-n-interfaces::’
‘*note g-object-info-get-interface::’
‘*note g-object-info-get-n-methods::’
‘*note g-object-info-get-method::’
‘*note g-object-info-find-method::’
‘*note g-object-info-get-n-properties::’
‘*note g-object-info-get-property::’
‘*note g-object-info-get-n-signals::’
‘*note g-object-info-get-signal::’
‘*note g-object-info-find-signal::’
‘*note g-object-info-get-n-vfuncs::’
‘*note g-object-info-get-vfunc::’
‘*note g-object-info-get-class-struct::’
‘*note g-object-info-get-set-value-function::’
‘*note g-object-info-get-set-value-function-pointer::’
‘*note g-object-info-get-get-value-function::’
‘*note g-object-info-get-get-value-function-pointer::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIRegisteredTypeInfo
+-- GIObjectInfo
Description
-----------
‘GIObjectInfo’ represents a classed type.
Classed types in GType inherit from GTypeInstance
(https://docs.gtk.org/gobject/classes_hierarchy.html). The most common
type is GObject. This doesn't represent a specific instance of a
GObject, instead this represent the object type (eg class).
A ‘GIObjectInfo’ has methods, fields, properties, signals, interfaces,
constants and virtual functions.
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIObjectInfo’.
-- Procedure: gi-object-show info
Returns nothing.
Obtains and displays the following informations about the object
(and its parent) pointed to by INFO:
,use (g-golf)
(g-irepository-require "Clutter")
⇒ $2 = #
(g-irepository-find-by-name "Clutter" "Actor")
⇒ $3 = #
(gi-object-show $3)
⊣
⊣ # is a (pointer to a) GIObjectInfo:
⊣
⊣ Parent:
⊣ namespace: "GObject"
⊣ name: "InitiallyUnowned"
⊣ g-type: 94804596757600
⊣ g-type-name: "GInitiallyUnowned"
⊣
⊣ Object:
⊣ namespace: "Clutter"
⊣ name: "Actor"
⊣ g-type: 94804596864480
⊣ g-type-name: "ClutterActor"
⊣ abstract: #f
⊣ n-constants: 0
⊣ n-fields: 4
⊣ n-interfaces: 4
⊣ n-methods: 238
⊣ n-properties: 82
⊣ n-signals: 26
⊣ n-vfuncts: 35
-- Procedure: gi-object-property-names info
Returns a (possibly empty) list.
Obtains and returns the (possibly empty) list of the (untranslated)
GI property names for INFO (see *note g-name->name:: to obtain
their scheme representation).
-- Procedure: gi-object-method-names info
Returns a (possibly empty) list.
Obtains and returns the (possibly empty) list of pairs of the
(untranslated) GI method names for INFO (see *note g-name->name::
to obtain their scheme representation).
Each pair is composed of the INFO *note
g-function-info-get-symbol:: and *note g-base-info-get-name::
names.
-- Procedure: gi-object-method-find-by-name info name
Returns a pointer or ‘#f’.
Obtains and returns a pointer to the method ‘GIFunctionInfo’
contained in INFO, for which *note g-function-info-get-symbol:: is
‘string=?’ to NAME. If there is such method, it returns ‘#f’.
-- Procedure: g-object-info-get-abstract info
Returns #t if the INFO object type is abstract.
Obtain if the object type is an abstract type, eg if it cannot be
instantiated.
-- Procedure: g-object-info-get-parent info
Returns a pointer or #f.
Obtains and returns a pointer to the INFO's parent ‘GIObjectInfo’,
or #f if INFO has no parent.
-- Procedure: g-object-info-get-type-name info
Returns the name of the object type for INFO.
Obtain the name of the object class/type for INFO.
-- Procedure: g-object-info-get-type-init info
Returns a function name (a string).
Obtain the function name which when called will return the GType
function for which this object type is registered.
-- Procedure: g-object-info-get-n-constants info
Returns the number of constants for INFO.
Obtain the number of constants that this object type has.
-- Procedure: g-object-info-get-constant info n
Returns a pointer to the Nth ‘GIConstantInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-fields info
Returns the number of fields for INFO.
Obtain the number of fields that this object type has.
-- Procedure: g-object-info-get-field info n
Returns a pointer to the Nth ‘GIFieldInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-interfaces info
Returns the number of interfaces for INFO.
Obtain the number of interfaces that this object type has.
-- Procedure: g-object-info-get-interface info n
Returns a pointer to the Nth ‘GIInterfaceInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-methods info
Returns the number of methods for INFO.
Obtain the number of methods that this object type has.
-- Procedure: g-object-info-get-method info n
Returns a pointer to the Nth ‘GIFunctionInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-find-method info name
Returns a pointer to a ‘GIFunctionInfo’ or #f if there is no method
available with that name.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-properties info
Returns the number of properties for INFO.
Obtain the number of properties that this object type has.
-- Procedure: g-object-info-get-property info n
Returns a pointer to the Nth ‘GIPropertyInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-signals info
Returns the number of signals for INFO.
Obtain the number of signals that this object type has.
-- Procedure: g-object-info-get-signal info n
Returns a pointer to the Nth ‘GISignalInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-find-signal info name
Returns a pointer to a ‘GISignalInfo’ or #f if there is no signal
available with that name.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-n-vfuncs info
Returns the number of vfuncs for INFO.
Obtain the number of vfuncs that this object type has.
-- Procedure: g-object-info-get-vfunc info n
Returns a pointer to the Nth ‘GIVfuncInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-class-struct info
Returns a pointer to the Nth ‘GIStructInfo’ of INFO, or #f.
Every ‘GObject’ has two structures: an instance structure and a
class structure. This function returns a pointer to the INFO class
structure.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-object-info-get-set-value-function info
Returns a string.
Obtain the symbol name (within the GI context, a symbol name is a
string) of the function that should be called to set a GValue
giving an object instance pointer of this object type.
-- Procedure: g-object-info-get-set-value-function-pointer info
Returns a pointer.
Obtain a pointer to a function which can be used to set a GValue
giving an object instance pointer of this object type. This takes
derivation into account and will reversely traverse the base
classes of this type, starting at the top type.
-- Procedure: g-object-info-get-get-value-function info
Returns a string.
Obtain the symbol name (within the GI context, a symbol name is a
string) of the function that should be called to get a GValue
instance pointer of this object type giving an object instance
pointer of this object type.
-- Procedure: g-object-info-get-get-value-function-pointer info
Returns a pointer.
Obtain a pointer to a function which can be used to get a GValue
instance pointer giving an object instance pointer of this object
type. This takes derivation into account and will reversely
traverse the base classes of this type, starting at the top type.
Interface Info
--------------
G-Golf Interface Info low level API.
GIInterfaceInfo — Structs representing a GInterface.
Procedures
----------
‘*note gi-interface-import::’
‘*note gi-interface-show::’
‘*note g-interface-info-get-n-prerequisites::’
‘*note g-interface-info-get-prerequisite::’
‘*note g-interface-info-get-n-properties::’
‘*note g-interface-info-get-property::’
‘*note g-interface-info-get-n-methods::’
‘*note g-interface-info-get-method::’
‘*note g-interface-info-find-method::’
‘*note g-interface-info-get-n-signals::’
‘*note g-interface-info-get-signal::’
‘*note g-interface-info-find-signal::’
‘*note g-interface-info-get-n-vfuncs::’
‘*note g-interface-info-get-vfunc::’
‘*note g-interface-info-find-vfunc::’
‘*note g-interface-info-get-n-constants::’
‘*note g-interface-info-get-constant::’
‘*note g-interface-info-get-iface-struct::’
Description
-----------
‘GIInterfaceInfo’ represents a GInterface
(https://developer.gnome.org/gobject/stable/GTypeModule.html).
A GInterface has methods, properties, signals, constants, virtual
functions and prerequisites.
Struct Hierarchy
----------------
GIBaseInfo
+-- GIRegisteredTypeInfo
+-- GIInterfaceInfo
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIInterfaceInfo’.
-- Procedure: gi-interface-import info
Returns a list.
In the current version of G-Golf, interfaces are ‘opaques’.
Returns a list composed of the 'interface (type-tag) symbol, the
interface (scheme and symbol) name, g-name, g-type and #t (a
boolean that means the type is confirmed). Here is an example:
(interface gtk-orientable "GtkOrientable" 94578771473520 #t)
-- Procedure: gi-interface-show info
Returns nothing.
Obtains and displays the following informations about the interface
pointed to by INFO:
,use (g-golf)
(g-irepository-require "Gdk" #:version "4.0")
⇒ $2 = #
(g-irepository-find-by-name "Gdk" "Paintable")
⇒ $3 = #
(gi-interface-show $3)
⊣ # is a (pointer to a) GIInterfaceInfo:
⊣
⊣ namespace: "Gdk"
⊣ name: "Paintable"
⊣ g-type: 93947637686432
⊣ g-type-name: "GdkPaintable"
⊣ n-prerequisites: 0
⊣ n-properties: 0
⊣ n-methods: 10
⊣ n-signals: 2
⊣ n-vfuncts: 6
⊣ n-constants: 0
⊣ iface-struct: #
⊣ iface-struct-name: "PaintableInterface"
⊣
⊣ Methods:
⊣
⊣ 0. #f
⊣ gdk-paintable-new-empty
⊣
⊣ 1. compute-concrete-size
⊣ gdk-paintable-compute-concrete-size
⊣
⊣ 2. get-current-image
⊣ gdk-paintable-get-current-image
⊣
⊣ 3. get-flags
⊣ gdk-paintable-get-flags
⊣ ...
⊣
⊣ VFuncs:
⊣
⊣ 0. get-current-image
⊣
⊣ 1. get-flags
⊣
⊣ 2. get-intrinsic-aspect-ratio
⊣
⊣ 3. get-intrinsic-height
⊣
⊣ 4. get-intrinsic-width
⊣
⊣ 5. snapshot
-- Procedure: g-interface-info-get-n-prerequisites info
Returns the number of prerequisites for INFO.
Obtain the number of prerequisites for this interface type. A
prerequisites is another interface that needs to be implemented for
interface, similar to a base class for GObjects.
-- Procedure: g-interface-info-get-prerequisite info n
Returns a pointer to the Nth prerequisite for INFO.
The prerequisite as a ‘GIBaseInfo’. It must be freed by calling
*note g-base-info-unref:: when done accessing the data.
-- Procedure: g-interface-info-get-n-properties info
Returns the number of properties for INFO.
Obtain the number of properties that this interface type has.
-- Procedure: g-interface-info-get-property info n
Returns a pointer to the Nth ‘GIPropertyInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-get-n-methods info
Returns the number of methods for INFO.
Obtain the number of methods that this interface type has.
-- Procedure: g-interface-info-get-method info n
Returns a pointer to the Nth ‘GIFunctionInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-find-method info name
Returns a pointer to a ‘GIFunctionInfo’ or #f if there is no method
available with that name.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-get-n-signals info
Returns the number of signals for INFO.
Obtain the number of signals that this interface type has.
-- Procedure: g-interface-info-get-signal info n
Returns a pointer to the Nth ‘GISignalInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-find-signal info name
Returns a pointer to a ‘GISignalInfo’ or #f if there is no signal
available with that name.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-get-n-vfuncs info
Returns the number of vfuncs for INFO.
Obtain the number of vfuncs that this interface type has.
-- Procedure: g-interface-info-get-vfunc info n
Returns a pointer to the Nth ‘GIVfuncInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-find-vfunc info name
Returns a pointer to a ‘GIFunctionInfo’ or #f if there is no signal
available with that name.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-get-n-constants info
Returns the number of constants for INFO.
Obtain the number of constants that this interface type has.
-- Procedure: g-interface-info-get-constant info n
Returns a pointer to the Nth ‘GIConstantInfo’ of INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
-- Procedure: g-interface-info-get-iface-struct info
Returns a pointer to a ‘GIStructInfo’ for INFO, or #f.
Obtains and returns the layout C structure associated with INFO.
It must be freed by calling *note g-base-info-unref:: when done
accessing the data.
Arg Info
--------
G-Golf Arg Info low level API.
GIArgInfo — Struct representing an argument.
Procedures
----------
‘*note g-arg-info-get-closure::’
‘*note g-arg-info-get-destroy::’
‘*note g-arg-info-get-direction::’
‘*note g-arg-info-get-ownership-transfer::’
‘*note g-arg-info-get-scope::’
‘*note g-arg-info-get-type::’
‘*note g-arg-info-may-be-null::’
‘*note g-arg-info-is-caller-allocates::’
‘*note g-arg-info-is-optional::’
‘*note g-arg-info-is-return-value::’
‘*note g-arg-info-is-skip::’
Types and Values
----------------
‘*note %gi-direction::’
‘*note %gi-scope-type::’
‘*note %gi-transfer::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIArgInfo
Description
-----------
‘GIArgInfo’ represents an argument. An argument is always part of a
‘GICallableInfo’.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GIArgInfo’.
-- Procedure: g-arg-info-get-closure info
Returns the index of the user data argument or -1 if there is none.
Obtains the index of the user data argument. This is only valid
for arguments which are callbacks.
-- Procedure: g-arg-info-get-destroy info
Returns the index of the ‘GDestroyNotify’ argument or -1 if there
is none.
Obtains the index of the ‘GDestroyNotify’ argument. This is only
valid for arguments which are callbacks.
-- Procedure: g-arg-info-get-direction info
Returns a symbol.
Obtains and returns the *note %gi-direction:: of the argument.
-- Procedure: g-arg-info-get-ownership-transfer info
Returns a symbol.
Obtains and returns the *note %gi-transfer:: for this argument.
-- Procedure: g-arg-info-get-scope info
Returns a symbol.
Obtains and returns the *note %gi-scope-type:: for this argument.
The scope type explains how a callback is going to be invoked, most
importantly when the resources required to invoke it can be freed.
-- Procedure: g-arg-info-get-type info
Returns a pointer.
Obtains the ‘GITypeInfo’ holding the type information for INFO.
Free it using *note g-base-info-unref:: when done.
-- Procedure: g-arg-info-may-be-null info
Returns ‘#t’ or ‘#f’.
Obtains if the type of the argument includes the possibility of
‘NULL’. For 'in' values this means that ‘NULL’ is a valid value.
For 'out' values, this means that ‘NULL’ may be returned.
-- Procedure: g-arg-info-is-caller-allocates info
Returns ‘#t’ or ‘#f’.
Obtain if the argument is a pointer to a struct or object that will
receive an output of a function. The default assumption for ‘out’
arguments which have allocation is that the callee allocates; if
this is TRUE, then the caller must allocate.
-- Procedure: g-arg-info-is-optional info
Returns ‘#t’ or ‘#f’.
Obtains if the argument is optional. For 'out' arguments this
means that you can pass ‘NULL’ in order to ignore the result.
-- Procedure: g-arg-info-is-return-value info
Returns ‘#t’ or ‘#f’.
Obtains if the argument is a retur value. It can either be a
parameter or a return value.
-- Procedure: g-arg-info-is-skip info
Returns ‘#t’ or ‘#f’.
Obtains if an argument is only useful in C.
Types and Values
----------------
-- Instance Variable of : %gi-direction
An instance of ‘’, who's members are the scheme
representation of the direction of a ‘GIArgInfo’:
_g-name_: GIDirection
_name_: gi-direction
_enum-set_:
‘in’
in argument.
‘out’
out argument.
‘inout’
in and out argument.
-- Instance Variable of : %gi-scope-type
An instance of ‘’, who's members are the scheme
representation of the scope of a ‘GIArgInfo’. Scope type of a
‘GIArgInfo’ representing callback, determines how the callback is
invoked and is used to decide when the invoke structs can be freed.
_g-name_: GIScopeType
_name_: gi-scope-type
_enum-set_:
‘invalid’
The argument is not of callback type.
‘call’
The callback and associated user_data is only used
during the call to this function.
‘async’
The callback and associated user_data is only used
until the callback is invoked, and the callback. is
invoked always exactly once.
‘notified’
The callback and and associated user_data is used
until the caller is notfied via the destroy_notify.
-- Instance Variable of : %gi-transfer
The transfer is the exchange of data between two parts, from the
callee to the caller. The callee is either a
function/method/signal or an object/interface where a property is
defined. The caller is the side accessing a property or calling a
function. ‘GITransfer’ specifies who's responsible for freeing the
resources after the ownership transfer is complete. In case of a
containing type such as a list, an array or a hash table the
container itself is specified differently from the items within the
container itself. Each container is freed differently, check the
documentation for the types themselves for information on how to
free them.
An instance of ‘’, who's members are the scheme
representation of the ‘GITransfer’:
_g-name_: GITransfer
_name_: gi-transfer
_enum-set_:
‘nothing’
transfer nothing from the callee (function or the
type instance the property belongs to) to the
caller. The callee retains the ownership of the
transfer and the caller doesn't need to do anything
to free up the resources of this transfer
‘container’
transfer the container (list, array, hash table)
from the callee to the caller. The callee retains
the ownership of the individual items in the
container and the caller has to free up the
container resources ‘g_list_free’,
‘g_hash_table_destroy’, ... of this transfer
‘everything’
transfer everything, eg the container and its
contents from the callee to the caller. This is the
case when the callee creates a copy of all the data
it returns. The caller is responsible for cleaning
up the container and item resources of this transfer
Constant Info
-------------
G-Golf Constant Info low level API.
GIConstantInfo — Struct representing a constant.
Procedures
----------
‘*note g-constant-info-free-value::’
‘*note g-constant-info-get-type::’
‘*note g-constant-info-get-value::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIConstantInfo
Description
-----------
‘GIConstantInfo’ represents a constant. A constant has a type
associated which can be obtained by calling *note
g-constant-info-get-type:: and a value, which can be obtained by calling
*note g-constant-info-get-value::.
Procedures
----------
Note: in this section, the INFO and VALUE arguments are [must be]
pointers to a ‘GIConstantInfo’ and a ‘GIArgument’, respectively.
-- Procedure: g-constant-info-free-value info value
Returns nothing.
Frees the value returned from *note g-constant-info-get-value::.
-- Procedure: g-constant-info-get-type info
Returns a pointer.
Obtains and returns a pointer to the ‘GITypeInfo’ for INFO. Free
it using *note g-base-info-unref:: when done.
-- Procedure: g-constant-info-get-value info value
Returns an integer (the size of a constant).
Obtains the value associated with INFO and store it in the VALUE
parameter, which must be allocated before passing it.
The size of the constant value stored in argument will be returned.
Free the VALUE argument with *note g-constant-info-free-value::.
Field Info
----------
G-Golf Field Info low level API.
GIFieldInfo — Struct representing a struct or union field.
Procedures
----------
‘*note g-field-info-get-flags::’
‘*note g-field-info-get-offset::’
‘*note g-field-info-get-type::’
Struct Hierarchy
----------------
GIBaseInfo
+-- GIFieldInfo
Description
-----------
A ‘GIFieldInfo’ struct represents a field of a struct (see *note Struct
Info::), union (see ‘GIUnionInfo’) or an object (see *note Object
Info::). The GIFieldInfo is fetched by calling *note
g-struct-info-get-field::, ‘g-union-info-get-field’ or *note
g-object-info-get-field::. A field has a size, type and a struct offset
asssociated and a set of flags, which are currently ‘readable’ or
‘writable’.
Procedures
----------
Note: in this section, unless otherwise specified, the INFO argument is
[must be] a pointer to a ‘GIFieldInfo’.
-- Procedure: g-field-info-get-flags info
Returns a (possibly empty) list.
Obtains and returns the flags for INFO, which currently are
‘readable’ or ‘writable’.
-- Procedure: g-field-info-get-offset info
Returns an unsigned integer.
Obtains and returns the offset in bytes for INFO, the field member,
this is relative to the beginning of the struct or union.
-- Procedure: g-field-info-get-type info
Returns a pointer.
Obtains and returns the ‘GITypeInfo’ for INFO.
The ‘GITypeInfo’ must be freed by calling *note g-base-info-unref::
when done.
Property Info
-------------
G-Golf Property Info low level API.
GIPropertyInfo — Struct representing a property.
Procedures
----------
‘*note gi-property-g-type::’
‘*note g-property-info-get-flags::’
‘*note g-property-info-get-ownership-transfer::’
‘*note g-property-info-get-type::’
Struct Hierarchy
----------------
GIBaseInfoInfo
+-- GIPropertyInfo
Description
-----------
‘GIPropertyInfo’ represents a property. A property belongs to either a
‘GIObjectInfo’ or a ‘GIInterfaceInfo’.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GIPropertyInfo’.
-- Procedure: gi-property-g-type info
Returns an integer.
Obtains and returns the ‘GType’ value of the property.
-- Procedure: g-property-info-get-flags info
Returns a list of *note %g-param-flags::.
Obtain the flags for this property INFO. See *note GParamSpec::
for the list of possible flag values.
-- Procedure: g-property-info-get-ownership-transfer info
Returns the ownership transfer for this property.
Obtain the ownership transfer for this property. See *note
%gi-transfer:: for more information about transfer values.
-- Procedure: g-property-info-get-type info
Returns a pointer to a ‘GITypeInfo’.
Obtain the type information for this property. The ‘GITypeInfo’
must be free'd using ‘g-base-info-unref’ when done.
Type Info
---------
G-Golf Type Info low level API.
GITypeInfo — Struct representing a type.
Procedures
----------
‘*note g-info-type-to-string::’
‘*note g-type-info-is-pointer::’
‘*note g-type-info-get-tag::’
‘*note g-type-info-get-param-type::’
‘*note g-type-info-get-interface::’
‘*note g-type-info-get-array-length::’
‘*note g-type-info-get-array-fixed-size::’
‘*note g-type-info-is-zero-terminated::’
‘*note g-type-info-get-array-type::’
Struct Hierarchy
----------------
GIBaseInfoInfo
+-- GITypeInfo
Description
-----------
‘GITypeInfo’ represents a type. You can retrieve a type info from an
argument (see *note Arg Info::), a functions return value (see *note
Function Info::), a field (see ‘GIFieldInfo’), a property (see *note
Property Info::), a constant (see ‘GIConstantInfo’) or for a union
discriminator (see ‘GIUnionInfo’).
A type can either be a of a basic type which is a standard C primitive
type or an interface type. For interface types you need to call
‘g-type-info-get-interface’ to get a reference to the base info for that
interface.
Procedures
----------
Note: in this section, the INFO argument is [must be] a pointer to a
‘GITypeInfo’.
-- Procedure: g-info-type-to-string info-type
Returns a string or ‘#f’.
Obtains the string representation for INFO-TYPE or ‘#f’ if it does
not exists.
INFO-TYPE can either be a ‘symbol’ or an ‘id’, a member of the
‘enum-set’ of *note %gi-info-type:: (otherwise, ‘#f’ is returned).
-- Procedure: g-type-info-is-pointer info
Returns ‘#t’ or ‘#f’.
Obtains if the INFO type is passed as a reference.
Note that the types of ‘out’ and ‘inout’ parameters (see *note
%gi-direction::) will only be pointers if the underlying type being
transferred is a pointer (i.e. only if the type of the C
function’s formal parameter is a pointer to a pointer).
-- Procedure: g-type-info-get-tag info
Returns a symbol.
Obtains the type tag for INFO (see *note %gi-type-tag:: for the
list of type tags).
-- Procedure: g-type-info-get-param-type info n
Returns a pointer or ‘#f’.
Obtains the parameter type N (the index of the parameter). When
there is no such N parameter, the procedure returns ‘#f’.
-- Procedure: g-type-info-get-interface info
Returns a pointer or ‘#f’.
For ‘interface’ types (see *note %gi-type-tag::) such as GObjects
and boxed values, this procedure returns a (pointer to a)
‘GIBaseInfo’, holding full information about the referenced type.
You can then inspect the type of the returned ‘GIBaseInfo’ to
further query whether it is a concrete GObject, a GInterface, a
structure, etc. using *note g-base-info-get-type::.
-- Procedure: g-type-info-get-array-length info
Returns an interger.
Obtain the array length of the type. The type tag must be a
‘array’ (see *note %gi-type-tag::), or -1 will returned.
-- Procedure: g-type-info-get-array-fixed-size info
Returns an interger.
Obtain the fixed array syze of the type. The type tag must be a
‘array’ (see *note %gi-type-tag::), or -1 will returned.
-- Procedure: g-type-info-is-zero-terminated info
Returns ‘#t’ or ‘#f’.
Obtains if the last element of the array is ‘NULL’. The type tag
must be a ‘array’ (see *note %gi-type-tag::), or ‘#f’ will
returned.
-- Procedure: g-type-info-get-array-type info
Returns a symbol or ‘#f’.
Obtain the array type for this type (see *note %gi-array-type::).
If the type tag of this type is not array, ‘#f’ will be returned.
FFI Interface
-------------
G-Golf FFI Interface low level API.
girffi — TODO.
Procedures
----------
‘*note gi-type-tag-get-ffi-type::’
‘*note g-type-info-get-ffi-type::’
‘*note gi-type-info-extract-ffi-return-value::’
‘*note gi-type-tag-extract-ffi-return-value::’
‘*note g-callable-info-prepare-closure::’
Description
-----------
TODO.
Procedures
----------
-- Procedure: gi-type-tag-get-ffi-type type-tag is-pointer?
Returns a (pointer to) ‘ffi-type’ corresponding to the platform
default C ABI for TYPE-TAG and IS-POINTER?.
The INFO argument is (must be) a valid *note %gi-type-tag::,
otherwise an exception is raised.
The IS-POINTER? argument, ‘#t’ or ‘#f’, to indicate whether or not
this is a pointer type.
-- Procedure: g-type-info-get-ffi-type info
Returns an (pointer to) ‘ffi-type’ corresponding to the platform
default C ABI for INFO.
The INFO argument is [must be] a pointer to a ‘GITypeInfo’.
-- Procedure: gi-type-info-extract-ffi-return-value type-info ffi-value
gi-argument
Returns nothing.
Extract the correct bits from FFI-VALUE into GI-ARGUMENT.
The TYPE-INFO is the ‘GITypeInfo’ of FFI-VALUE. The FFI-VALUE is a
pointer to a ‘GIFFIReturnValue’ union containing the value from the
‘ffi_call()’. The GI-ARGUMENT is a pointer to an allocated
‘GIArgument’.
-- Procedure: gi-type-tag-extract-ffi-return-value return-tag
interface-type ffi-value gi-argument
Returns nothing.
Extract the correct bits from FFI-VALUE into GI-ARGUMENT.
The RETURN-TAG is the *note %gi-type-tag:: of FFI-VALUE. The
INTERFACE-TYPE is the *note %gi-info-type:: of the underlying
interface. The FFI-VALUE is a pointer to a ‘GIFFIReturnValue’
union containing the value from the ‘ffi_call()’. The GI-ARGUMENT
is a pointer to an allocated ‘GIArgument’.
The INTERFACE-TYPE argument only applies if RETURN-TAG is
‘'interface’, otherwise it is ignored.
-- Procedure: g-callable-info-prepare-closure info ffi-cif
ffi-closure-callback user-data
Returns the native address of the closure or ‘#f’ on error.
The procedure has been deprecated since version 1.72 and should
not be used in newly-written code. Use
*note g-callable-info-create-closure:: instead.
The return value should be freed by calling
‘g-callable-info-free-closure’.
Utilities
---------
G-Golf GObject Introspetion Utilities low level API.
Procedures and Syntax
---------------------
‘*note gi-pointer-new::’
‘*note gi-pointer-inc::’
‘*note gi-attribute-iter-new::’
‘*note with-gerror::’
‘*note gi->scm::’
‘*note gi-boolean->scm::’
‘*note gi-string->scm::’
‘*note gi-n-string->scm::’
‘*note gi-strings->scm::’
‘*note gi-csv-string->scm::’
‘*note gi-pointer->scm::’
‘*note gi-n-pointer->scm::’
‘*note gi-pointers->scm::’
‘*note gi-n-gtype->scm::’
‘*note gi-glist->scm::’
‘*note gi-gslist->scm::’
‘*note scm->gi::’
‘*note scm->gi-boolean::’
‘*note scm->gi-string::’
‘*note scm->gi-n-string::’
‘*note scm->gi-strings::’
‘*note scm->gi-pointer::’
‘*note scm->gi-n-pointer::’
‘*note scm->gi-pointers::’
‘*note scm->gi-n-gtype::’
‘*note scm->gi-gslist::’
Types and Values
----------------
‘*note %gi-pointer-size::’
Description
-----------
G-Golf GObject Introspection utilities low level API.
Procedures and Syntax
---------------------
-- Procedure: gi-pointer-new
Returns a newly allocated (Glib) pointer.
-- Procedure: gi-pointer-inc pointer [#:offset %gi-pointer-size]
Returns a foreign pointer object pointing to the address of POINTER
increased by OFFSET.
-- Procedure: gi-attribute-iter-new
Returns a pointer.
Creates and returns a foreign pointer to a C struct for a
‘GIAttributeIter’ (a C struct containg four pointers, initialized
to ‘%null-pointer’).
-- Syntax: with-gerror var body
Returns the result of the execution of BODY, or raises an
exception.
VAR must be an identifier. Evaluate BODY in a lexical environment
where VAR is bound to a pointer to a newly allocated (and ‘empty’)
‘GError’. VAR will always be freed. If no exception is raised,
the result of the execution of BODY is returned.
-- Procedure: gi->scm value type [cmpl #f]
Returns the scheme representation of VALUE.
The TYPE, a symbol name (also called a ‘type tag’ or just a ‘tag’
in the ‘GI’ terminology) supported values are:
‘'boolean’
Calls *note gi-boolean->scm::.
‘'string’
‘'pointer’
Calls *note gi-string->scm:: or *note gi-pointer->scm::.
‘'n-string’
‘'n-pointer’
‘'n-gtype’
Calls *note gi-n-string->scm::, *note gi-n-pointer->scm::
or *note gi-n-gtype->scm::.
The optional CMPL (complement) argument must be passed
and set to the number of string(s), pointer(s) or
gtype(s) contained in VALUE, .
‘'strings’
‘'pointers’
Calls *note gi-strings->scm:: or *note
gi-pointers->scm::.
‘'csv-string’
Calls *note gi-csv-string->scm::.
‘'glist’
‘'gslist’
Calls *note gi-glist->scm:: or *note gi-gslist->scm::,
repsectively.
-- Procedure: gi-boolean->scm value
Returns ‘#t’ or ‘#f’.
The GType of VALUE must be a ‘gboolean’.
-- Procedure: gi-string->scm value
-- Procedure: gi-pointer->scm value
Returns a string, a pointer or ‘#f’ if VALUE is the
‘%null-pointer’.
The GType of VALUE must be a ‘gchar*’ or a ‘gpointer’.
-- Procedure: gi-n-string->scm value n-string
-- Procedure: gi-n-pointer->scm value n-pointer
-- Procedure: gi-n-gtype->scm value n-gtype
Returns a (possibly empty list) of string(s), pointer(s) or
GType(s).
The GType of VALUE must be a ‘gchar**’, a ‘gpointer[]’ or a
‘GType[]’. The N-STRING, N-POINTER and N-GTYPE argument must be
the length of the VALUE array.
-- Procedure: gi-strings->scm value
-- Procedure: gi-pointers->scm value
Returns a (possibly empty) list of strings or pointer.
The GType of VALUE must be a ‘gchar**’ or ‘gpointer[]’. The array
must be NULL terminated.
-- Procedure: gi-csv-string->scm value
Returns a list of string(s) or ‘#f’ if VALUE is the
‘%null-pointer’.
The GType of VALUE is ‘gchar*’. Unless ‘#f’, the list of string(s)
is obtained by splitting the (comma separated value) string pointed
to by VALUE using using ‘#\,’ as the ‘char-pred’.
-- Procedure: gi-glist->scm g-list
-- Procedure: gi-gslist->scm g-slist
Returns a (possibly empty) list.
Obtains and returns a (possibly empty) list of the pointers stored
in the ‘data’ field of each element of G-LIST or G-SLIST.
-- Procedure: scm->gi value type [cmpl #f]
Returns the GI representation of VALUE.
The TYPE, a symbol name (also called a ‘type tag’ or just a ‘tag’
in the ‘GI’ terminology) supported values are:
‘'boolean’
Calls *note scm->gi-boolean::.
‘'string’
‘'pointer’
Calls *note scm->gi-string:: or *note scm->gi-pointer::.
‘'n-string’
‘'n-pointer’
‘'n-gtype’
Calls *note scm->gi-n-string::, *note scm->gi-n-pointer::
or *note scm->gi-n-gtype::.
The optional CMPL (complement) argument may be passed and
set to the number of string(s), pointer(s) or gtype(s)
contained in VALUE.
‘'strings’
‘'pointers’
Calls *note scm->gi-strings:: or *note
scm->gi-pointers::.
‘'gslist’
Calls *note scm->gi-gslist::.
-- Procedure: scm->gi-boolean value
Returns ‘0’ if VALUE is ‘#f’, otherwise, it returns ‘1’.
-- Procedure: scm->gi-string value
-- Procedure: scm->gi-pointer value
Returns a pointer.
If VALUE is ‘#f’, it returns ‘%null-pointer’. Otherwise, it
returns a pointer to the string in VALUE or VALUE.
-- Procedure: scm->gi-n-string value [n-string #f]
-- Procedure: scm->gi-strings value
Returns two values.
If VALUE is the empty list, it returns ‘%null-pointer’ and an empty
list. Otherwise, it returns a pointer to an array of pointer(s) to
the string(s) in VALUE and a list of the ‘inner’ string pointer(s).
It is the caller's responsibility to maintain a reference to those
inner pointer(s), until the array ‘itself’ (the first returned
value) is no longer needed/used.
The array returned by *note scm->gi-strings:: is ‘NULL’ terminated,
where as the array returned by *note scm->gi-n-string:: is not.
-- Procedure: scm->gi-n-pointer value [n-pointer #f]
-- Procedure: scm->gi-n-gtype value [n-gtype #f]
Returns a pointer.
If VALUE is an empty list, it returns ‘%null-pointer’. Otherwise,
it returns a pointer to an array the pointer(s) or GType(s) in
VALUE.
The returned array is not ‘NULL’ nor ‘0-’ terminated.
-- Procedure: scm->gi-pointers value
Returns a pointer.
If VALUE is an empty list, it returns ‘%null-pointer’. Otherwise,
it returns a pointer to an array the pointer(s) in VALUE.
The returned array is ‘NULL’ terminated.
-- Procedure: scm->gi-gslist value
Returns a pointer.
If VALUE is an empty list, it returns ‘%null-pointer’. Otherwise,
it returns a pointer to a ‘GSList’, with its element's data being
(in order), the pointer(s) in VALUE.
Types and Values
----------------
-- Variable: %gi-pointer-size
The size (the number of bytes) that a (Glib) pointer occupies in
memory (which is architecture dependent).
Support
=======
G-Golf uses a series of support modules, each documented in the
following subsections. You may either import them all, like this
‘(use-modules (g-golf support))’, or individually, such as ‘(use-modules
(g-golf support modules))’, ‘(use-modules (g-golf support goops))’, ...
Module
------
G-Golf Module Utilities.
Syntax
------
‘*note re-export-public-interface::’
-- Syntax: re-export-public-interface mod1 mod2 ...
Re-export the public interface of a MOD1 MOD2 ...
Invoked like ‘use-modules’, where each MOD1 MOD2 ... is a module
name (a list of symbol(s)).
Goops
-----
Syntax, Procedures and Methods
------------------------------
‘*note class-direct-virtual-slots::’
‘*note class-virtual-slots::’
‘*note class-direct-g-property-slots::’
‘*note class-g-property-slots::’
‘*note class-direct-child-id-slots::’
‘*note class-child-id-slots::’
‘*note class-direct-g-param-slots::’
‘*note class-g-param-slots::’
‘*note mslot-set!::’
‘*note generic?::’
-- Method: class-direct-virtual-slots (self )
Returns a list.
Obtains and returns the list of the class direct slots for SELF
that satisfy the ‘(eq? (slot-definition-allocation slot)
#:virtual)’ predicate.
-- Method: class-virtual-slots (self )
Returns a list.
Obtains and returns the list of the class slots for SELF that
satisfy the ‘(eq? (slot-definition-allocation slot) #:virtual)’
predicate.
-- Method: class-direct-g-property-slots (self )
Returns a list.
Obtains and returns the list of the class direct slots for SELF
that satisfy the ‘(eq? (slot-definition-allocation slot)
#:g-property)’ predicate.
-- Method: class-g-property-slots (self )
Returns a list.
Obtains and returns the list of the class slots for SELF that
satisfy the ‘(eq? (slot-definition-allocation slot) #:g-property)’
predicate.
-- Method: class-direct-child-id-slots (self )
Returns a list.
Obtains and returns the list of the class direct slots for SELF
that contain a ‘#:child-id’ slot definition option.
-- Method: class-child-id-slots (self )
Returns a list.
Obtains and returns the list of the class slots for SELF that
contain a ‘#:child-id’ slot definition option.
-- Method: class-direct-g-param-slots (self )
Returns a list.
Obtains and returns the list of the class direct slots for SELF
that contain a ‘#:g-param’ slot definition option.
-- Method: class-g-param-slots (self )
Returns a list.
Obtains and returns the list of the class slots for SELF that
contain a ‘#:g-param’ slot definition option.
-- Procedure: mslot-set! inst s1 v1 s2 v2 s3 v3 ...
Returns nothing.
Performs a multiple ‘slot-set!’ for INST, setting its slot named S1
to the value V1, S2 to V2, S3 to V3 ...
-- Procedure: generic? value
Returns ‘#t’ if VALUE is a instance. Otherwise, it
returns ‘#f’.
Enum
----
G-Golf class, accessors, methods and procedures to deal with C enum
types.
Classes
-------
‘*note ::’
‘*note ::’
Procedures, Accessors and Methods
---------------------------------
‘*note !enum-set::’
‘*note enum->value::’
‘*note enum->values::’
‘*note enum->symbol::’
‘*note enum->symbols::’
‘*note enum->name::’
‘*note enum->names::’
‘*note !g-type_::’
‘*note !g-name::’
‘*note !name__::’
Description
-----------
G-Golf class, accessors, methods and procedures to deal with C enum
types.
Classes
-------
-- Class:
The ‘’ class is for enumerated values. Its (unique) slot is:
‘_enum-set_’
#:accessor !enum-set
#:init-keyword #:enum-set
Notes:
• the ‘enum-set’ can't be empty and so you must use the
‘#:enum-set’ (#:init-keyword) when creating new ‘’
instances;
• the ‘#:enum-set’ (#:init-keyword) accepts either a list of
symbols or a well-formed ‘enum-set’;
• a well-formed ‘enum-set’ is a list of ‘(symbol . id)’ pairs,
where ‘id’ is a positive integer.
• each ‘symbol’ and each ‘id’ of an ‘enum-set’ must be unique.
Instances of the ‘’ class are immutable (to be precise, there
are not meant to be mutated, see *note GOOPS Notes and
Conventions::, 'Slots are not Immutable').
-- Class:
The ‘’ class is a subclass of ‘’. Its
‘class-direct-slots’ are:
‘_g-type_’
#:accessor !g-type
#:init-keyword #:g-type
#:init-value #f
‘_g-name_’
#:accessor !g-name
#:init-keyword #:g-name
‘_name_’
#:accessor !name
The ‘name’ slot is automatically initialized.
Instances of the ‘’ class are immutable (to be precise,
there are not meant to be mutated, see *note GOOPS Notes and
Conventions::, 'Slots are not Immutable').
Procedures, Accessors and Methods
---------------------------------
-- Accessor: !enum-set (inst )
Returns the content of the enum-set slot for INST.
-- Method: enum->value (inst ) symbol
-- Method: enum->values (inst )
Returns the INST value for SYMBOL (or ‘#f’ if it does not exists),
or the list of all values for INST, respectively.
-- Method: enum->symbol (inst ) value
-- Method: enum->symbols (inst )
Returns the INST symbol for VALUE (or ‘#f’ if it does not exists),
or the list of all symbols for INST, respectively.
-- Method: enum->name (inst ) value
-- Method: enum->names (inst )
Returns the INST name (the string representation of the symbol) for
VALUE (or ‘#f’ if it does not exists), or the list of all names for
INST, respectively.
VALUE can either be a ‘symbol’ or an ‘id’.
-- Accessor: !g-type (inst )
-- Accessor: !g-name (inst )
-- Accessor: !name (inst )
Returns the content of the g-type, g-name or name slot for INST,
respectively.
Flags
-----
G-Golf class, accessors, methods and procedures to deal with C flags
types.
Classes
-------
‘*note ::’
‘*note ::’
Procedures, Accessors and Methods
---------------------------------
‘*note integer->flags::’
‘*note flags->integer::’
‘*note !g-type___::’
‘*note !g-name______::’
‘*note !name_____::’
Description
-----------
G-Golf class, accessors, methods and procedures to deal with C flags
types.
Classes
-------
-- Class:
The ‘’ class is a subclass of *note ::. It has no
direct slots.
-- Class: