callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Getting started: BIG update of basics section

Browse Source 
https://bugzilla.gnome.org/show_bug.cgi?id=743680
This commit is contained in:
Bastian Ilsø 2015-01-28 18:43:45 +00:00 committed by Matthias Clasen
parent ff256956b2
commit a1f8ffce4e
1 changed files with 45 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
docs/reference/gtk/getting_started.xml
View File

@ -12,7 +12,7 @@
Widgets are organized in a hierachy. The window widget is the main container. Widgets are organized in a hierachy. The window widget is the main container.
The user interface is then built by adding buttons, drop-down menus, input The user interface is then built by adding buttons, drop-down menus, input
fields, and other widgets to the window. fields, and other widgets to the window.
If you are creating advanced or complex user interfaces it is recommended to If you are creating complex user interfaces it is recommended to
use #GtkBuilder and its GTK-specific markup description language, instead of use #GtkBuilder and its GTK-specific markup description language, instead of
assembling the interface manually. You can also use a visual user interface assembling the interface manually. You can also use a visual user interface
editor, like <ulink url="https://glade.gnome.org/">Glade</ulink>.</para> editor, like <ulink url="https://glade.gnome.org/">Glade</ulink>.</para>
@ -30,8 +30,8 @@
<section> <section>
<title>Basics</title> <title>Basics</title>
<para>To begin our introduction to GTK, we'll start with the simplest <para>To begin our introduction to GTK, we'll start with a simple
program possible. This program will create an empty 200 × 200 pixel signal-based Gtk application. This program will create an empty 200 × 200 pixel
window.</para> window.</para>
<informalfigure> <informalfigure>
@ -43,7 +43,7 @@
</informalfigure> </informalfigure>
<informalexample> <informalexample>
<para>Create a new file with the following content named example-0.c.</para> <para>Create a new file with the following content named <filename>example-0.c.</filename></para>
<programlisting><xi:include href="../../../../examples/window-default.c" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting> <programlisting><xi:include href="../../../../examples/window-default.c" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
</informalexample> </informalexample>
@ -67,28 +67,42 @@
by third party code. The compiler will abort with an error if any other by third party code. The compiler will abort with an error if any other
header is directly included.</para></warning> header is directly included.</para></warning>
<para>We then proceed into the <function>main</function>() function of the <para>In a GTK+ application, the purpose of the main() function is to
application, and we declare a <varname>window</varname> variable as a pointer create a #GtkApplication object and run it. In this example a
of type #GtkWidget.</para> #GtkApplication pointer named <varname>app</varname> is called and then
initialized using gtk_application_new().</para>
<para>The following line will call gtk_init(), which <para>When creating a #GtkApplication
is the initialization function for GTK+; this function will set up GTK+, you need to pick an application identifier (a name)
the type system, the connection to the windowing environment, etc. The and input to gtk_application_new() as parameter.
gtk_init() takes as arguments the pointers to the command line arguments For this example <varname>org.gtk.example</varname> is used
but for choosing an identifier for your application see
<ulink url="https://wiki.gnome.org/HowDoI/ChooseApplicationID">this guide</ulink>.
Lastly gtk_application_new() takes a GApplicationFlags as input for your
application, if your application would have special needs.
</para>
<para>Next the
<ulink url="https://wiki.gnome.org/HowDoI/GtkApplication">activate signal</ulink>
is connected to the activate() function above the main() functions.
The <varname>activate</varname> signal will be sent
when your application is launched with
g_application_run() on the line below.
The gtk_application_run() also takes as arguments the pointers to the command line arguments
counter and string array; this allows GTK+ to parse specific command line counter and string array; this allows GTK+ to parse specific command line
arguments that control the behavior of GTK+ itself. The parsed arguments arguments that control the behavior of GTK+ itself. The parsed arguments
will be removed from the array, leaving the unrecognized ones for your will be removed from the array, leaving the unrecognized ones for your
application to parse.</para> application to parse.
</para>
<note><para>For more information on which command line arguments GTK+ <para>Within g_application_run the activate() signal is sent and
recognizes, please refer to the <link linkend="gtk-running">Running GTK+ we then proceed into the <function>activate</function>() function of the
Applications</link> section in this reference.</para></note> application. Inside the activate() function we want to construct
our GTK window, so that a window is shown when the application
<para>The call to gtk_window_new() will create a new #GtkWindow and store is launched. The call to gtk_application_window_new() will
it inside the <varname>window</varname> variable. The type of the window createa a new #GtkWindow and store it inside the
is %GTK_WINDOW_TOPLEVEL, which means that the #GtkWindow will be managed <varname>window</varname> pointer. The window will have a frame,
by the windowing system: it will have a frame, a title bar and window a title bar, and window controls depending on the platform.</para>
controls, depending on the platform.</para>
<para>A window title is set using gtk_window_set_title(). This function <para>A window title is set using gtk_window_set_title(). This function
takes a GtkWindow* pointer and a string as input. As our takes a GtkWindow* pointer and a string as input. As our
@ -105,22 +119,14 @@
<ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html"> <ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html">
here</ulink>.</para> here</ulink>.</para>
<para>In order to terminate the application when the #GtkWindow is <para>Finally the window size is set using gtk_window_set_default_size and
destroyed, we connect the #GtkWidget::destroy signal to the gtk_main_quit() the window is then shown by GTK via gtk_widget_show_all().</para>
function. This function will terminate the GTK+ main loop started by calling
gtk_main() later. The #GtkWidget::destroy signal is emitted when a widget is
destroyed, either by explicitly calling gtk_widget_destroy() or when the
widget is unparented. Top-level #GtkWindow<!-- -->s are also destroyed when
the Close window control button is clicked.</para>
<para>#GtkWidget<!-- -->s are hidden by default. By calling gtk_widget_show() <para>When you exit the window, by for example pressing the X,
on a #GtkWidget we are asking GTK+ to set the visibility attribute so that it the g_application_run() in the main loop returns with a number
can be displayed. All this work is done after the main loop has been which is saved inside an integer named "status". Afterwards, the
started.</para> #GtkApplication object is freed from memory with g_object_unref().
Finally the status integer is returned and the GTK application exits.</para>
<para>The last line of interest is the call to gtk_main(). This function will
start the GTK+ main loop and will block the control flow of the
main() until the gtk_main_quit() function is called.</para>
<para>While the program is running, GTK+ is receiving <para>While the program is running, GTK+ is receiving
<firstterm>events</firstterm>. These are typically input events caused by <firstterm>events</firstterm>. These are typically input events caused by