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


@node Hello World!
@subsection Hello World!

Following the tradition, let's first see how the often seen @samp{Hello
World!} familiar, minimal, friendly greeting program looks like in
G-Golf:

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

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

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

Providing you successfully installed G-Golf, you may run the above code
in a Guile @abbr{REPL, Read Evaluate Print Loop}@footnote{If you haven't
done so, please read the @ref{Configuring Guile for G-Golf},
@emph{Merging Generics} and configure your repl as proposed, before to
run the example.}, which as described in its comments, starts the
application, resulting in opening a (small) window named @samp{Hello},
with one button named @samp{Hello, World!}, that will close the window
when clicked.

@float Example, exa:exa1
@ifnottex
@image{images/hello-world-1,,,hello-world-1,png}
@caption{Hello World! (1)}
@end ifnottex
@end float

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
@code{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:

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

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
@code{<gtk-application> / g-application-run} instance creation and run
mechanism in detail, for this, please consult and carefully read their
respective entries in the @uref{@value{UGTK4-APPLICATION}, Gtk} and
@uref{@value{UGIO-G-APPLICATION}, Gio} reference manuals.

The GNOME team also maintains a wiki called @uref{@value{UHDI}, HowDoI},
and two pages are dedicated to this subject:
@uref{@value{UHDI-GTKAPPLICATION}, HowDoI GtkApplication} and
@uref{@value{UHDI-GTKAPPLICATION-CMDLINE}, HowDoI
GtkApplication/CommandLine}.

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

@itemize

@item
as you can see, we do not need to call @code{gtk-init}, it is done
automatically (more on this in the @uref{@value{UGTK4-APPLICATION},
GtkApplication} section of the Gtk Reference Manual);@*@*

@item
the @code{#:application-id} init-keyworkd is optional, although
recommended, and when passed, the application ID must be valid (more
on this below).

@end itemize

@ @ @sup{_} @strong{Is your application ID valid?}

The set of rules that apply and determine if an @emph{Application
Identifier} is valid is fully described in the Gio Reference Manual,
@uref{@value{UGIO-G-APPLICATION-IS-VALID}, here}.

In G-Golf, you may check if your application ID is valid by calling
@code{g-application-id-is-valid}@footnote{After you at least import
either directly @code{(gi-import-by-name "Gio" "Application")}, or
@code{(gi-import-by-name "Gtk" "Application")}, which triggers the
appropriate Gio imports, as described in the next section}, for
example:

@lisp
(g-application-id-is-valid "com.example.GtkApplication")
@result{} #t

(g-application-id-is-valid "RedBear")
@result{} #f
@end lisp

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

@indentedblock
@emph{(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}
@end indentedblock


@ @ @sup{_} @strong{Great, but could we speed things up a little?}

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