@c -*-texinfo-*-

@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2021, 2024 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@c @defindex ei


@node Import
@subsection Import

G-Golf Import interfaces.@*
Importing GNOME libraries.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-import}
@item @ref{gi-import-by-name}
@end table
@end indentedblock


@subheading Description

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


@subheading Procedures


@anchor{gi-import}
@deffn Procedure gi-import namespace #:key (version #f)

Returns nothing.

Imports the @var{namespace} GIR Typelib and exports its interface. For
example:

@lisp
,use (g-golf
(gi-import "Clutter")
@end lisp

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

The optional @var{#:version} keyword argument may be used to require a
specific @var{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 @samp{feel it} if the number of
objects in @var{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 @ref{gi-import-by-name} here below.
@end deffn


@anchor{gi-import-by-name}
@deffn Procedure gi-import-by-name namespace name #:key (version  #f) @
       (force? #f) (with-method #t) (allow-constant? #f)

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

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

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

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

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

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