diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/reference/gtk/getting_started.xml.in | 312 | ||||
| -rw-r--r-- | docs/reference/gtk/gtk4-sections.txt | 2 | ||||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app1.png | bin | 3004 -> 4764 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app2.png | bin | 5718 -> 7246 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app3.png | bin | 37590 -> 39268 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app4.png | bin | 211105 -> 50510 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app6.png | bin | 223488 -> 153201 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app7.png | bin | 38964 -> 48914 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app8.png | bin | 58744 -> 80142 bytes | |||
| -rw-r--r-- | docs/reference/gtk/images/getting-started-app9.png | bin | 46932 -> 71600 bytes |
10 files changed, 143 insertions, 171 deletions
diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in index 3f2405caa4..758b4f0d9d 100644 --- a/docs/reference/gtk/getting_started.xml.in +++ b/docs/reference/gtk/getting_started.xml.in @@ -6,17 +6,17 @@ <title>Getting Started with GTK</title> <para>GTK is a <ulink url="http://en.wikipedia.org/wiki/Widget_toolkit"> - widget toolkit</ulink>. Each user interface created by - GTK consists of widgets. This is implemented in C using + widget toolkit</ulink>. Each user interface created by + GTK consists of widgets. This is implemented in C using <link linkend="gobject">GObject</link>, an object-oriented framework for C. 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. 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 editor, like <ulink url="https://glade.gnome.org/">Glade</ulink>.</para> - + <para>GTK is event-driven. The toolkit listens for events such as a click on a button, and passes the event to your application.</para> @@ -30,8 +30,8 @@ <section> <title>Basics</title> - <para>To begin our introduction to GTK, we'll start with a simple - signal-based Gtk application. This program will create an empty 200 × 200 pixel + <para>To begin our introduction to GTK, we'll start with a very simple + application. This program will create an empty 200 × 200 pixel window.</para> <informalfigure> @@ -64,68 +64,61 @@ <warning><para>Even if GTK installs multiple header files, only the top-level <filename>gtk/gtk.h</filename> header can be directly included - 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> - <para>In a GTK application, the purpose of the main() function is to - create a #GtkApplication object and run it. In this example a - #GtkApplication pointer named <varname>app</varname> is called and then - initialized using gtk_application_new().</para> + <para>In a GTK application, the purpose of the main() function is + to create a GtkApplication object and run it. In this example a + GtkApplication pointer named <varname>app</varname> is declared + and then initialized using gtk_application_new().</para> - <para>When creating a #GtkApplication - you need to pick an application identifier (a name) - and input to gtk_application_new() as parameter. - For this example <varname>org.gtk.example</varname> is used - but for choosing an identifier for your application see + <para>When creating a GtkApplication, you need to pick an application + identifier (a name) and pass it to gtk_application_new() as parameter. + For this example <varname>org.gtk.example</varname> is used. 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 + Lastly gtk_application_new() takes #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 g_application_run() also takes as arguments the command line arguments counter - and the pointer to string array; this allows GTK to parse specific command line - arguments that control the behavior of GTK itself. The parsed arguments - will be removed from the array, leaving the unrecognized ones for your - application to parse. + is connected to the activate() function above the main() function. + The <varname>activate</varname> signal will be emitted when your application + is launched with g_application_run() on the line below. The g_application_run() + call also takes as arguments the command line arguments (the + <varname>argc</varname> count and the <varname>argv</varname> string array). + Your application can override the command line handling, e.g. to open + files passed on the commandline. </para> - <para>Within g_application_run the activate() signal is sent and - we then proceed into the <function>activate</function>() function of the - application. Inside the activate() function we want to construct - our GTK window, so that a window is shown when the application - is launched. The call to gtk_application_window_new() will - create a new #GtkWindow and store it inside the - <varname>window</varname> pointer. The window will have a frame, - a title bar, and window controls depending on the platform.</para> + <para>Within g_application_run() the activate signal is sent and we then + proceed into the activate() function of the application. This is where we + construct our GTK window, so that a window is shown when the application + is launched. The call to gtk_application_window_new() will create a new + GtkWindow and store it inside the <varname>window</varname> pointer. The + window will have a frame, a title bar, and window controls depending on + the platform.</para> <para>A window title is set using gtk_window_set_title(). This function takes a GtkWindow* pointer and a string as input. As our - <varname>window</varname> pointer is a GtkWidget pointer, we need to cast it - to GtkWindow*. - But instead of casting <varname>window</varname> via - <varname>(GtkWindow*)</varname>, - <varname>window</varname> can be cast using the macro - <varname>GTK_WINDOW()</varname>. - <varname>GTK_WINDOW()</varname> will check if the - pointer is an instance of the GtkWindow class, before casting, and emit a - warning if the check fails. More information about this convention - can be found + <varname>window</varname> pointer is a GtkWidget pointer, we need to cast + it to GtkWindow*. But instead of casting <varname>window</varname> via + <varname>(GtkWindow*)</varname>, <varname>window</varname> can be cast + using the macro <varname>GTK_WINDOW()</varname>. <varname>GTK_WINDOW()</varname> + will check if the pointer is an instance of the GtkWindow class, before + casting, and emit a warning if the check fails. More information about + this convention can be found <ulink url="https://developer.gnome.org/gobject/stable/gtype-conventions.html"> here</ulink>.</para> - <para>Finally the window size is set using gtk_window_set_default_size and - the window is then shown by GTK via gtk_widget_show().</para> + <para>Finally the window size is set using gtk_window_set_default_sizei() + and the window is then shown by GTK via gtk_widget_show().</para> <para>When you exit the window, by for example pressing the X, the g_application_run() in the main loop returns with a number which is saved inside an integer named "status". Afterwards, the - #GtkApplication object is freed from memory with g_object_unref(). + GtkApplication object is freed from memory with g_object_unref(). Finally the status integer is returned and the GTK application exits.</para> <para>While the program is running, GTK is receiving @@ -139,8 +132,12 @@ <para>The following example is slightly more complex, and tries to showcase some of the capabilities of GTK.</para> + </section> + <section> + <title>Hello, World</title> + <para>In the long tradition of programming languages and libraries, - it is called <emphasis>Hello, World</emphasis>.</para> + this example is called <emphasis>Hello, World</emphasis>.</para> <informalfigure> <mediaobject> @@ -163,55 +160,59 @@ <literal>gcc `pkg-config --cflags gtk4` -o example-1 example-1.c `pkg-config --libs gtk4`</literal> </literallayout> </para> - </section> <para>As seen above, example-1.c builds further upon example-0.c by adding a button to our window, with the label "Hello World". Two new GtkWidget pointers are declared to accomplish this, <varname>button</varname> and - <varname>button_box</varname>. The button_box variable is created to store a - #GtkBox which is GTK's way of controlling the size and layout of buttons. - The #GtkBox is created and assigned to gtk_box_new() which takes a - #GtkOrientation enum as parameter. The buttons which this box will contain can - either be stored horizontally or vertically but this does not matter in this - particular case as we are dealing with only one button. After initializing - button_box with horizontal orientation, the code adds the button_box widget to the - window widget using gtk_container_add().</para> + <varname>box</varname>. The box variable is created to store a GtkBox, which + is GTK's way of controlling the size and layout of buttons. + </para> + + <para>The GtkBox is created with gtk_box_new() which takes a GtkOrientation + enum as parameter. The buttons which this box will contain can either be layed + out horizontally or vertically. This does not matter in this particular case, + as we are dealing with only one button. After initializing box with the newly + created GtkBox, the code adds the box widget to the window widget using + gtk_window_set_child().</para> <para>Next the <varname>button</varname> variable is initialized in similar manner. - gtk_button_new_with_label() is called which returns a GtkButton to be stored inside + gtk_button_new_with_label() is called which returns a GtkButton to be stored in <varname>button</varname>. Afterwards <varname>button</varname> is added to - our <varname>button_box</varname>. - Using g_signal_connect the button is connected to a function in our app called + our <varname>box</varname>. + </para> + + <para> + Using g_signal_connect(), the button is connected to a function in our app called print_hello(), so that when the button is clicked, GTK will call this function. As the print_hello() function does not use any data as input, NULL is passed to it. print_hello() calls g_print() with the string "Hello World" which will print Hello World in a terminal if the GTK application was started from one.</para> - <para>After connecting print_hello(), another signal is connected to the "clicked" state - of the button using g_signal_connect_swapped(). This functions is similar to + <para>After connecting print_hello(), another signal is connected to the "clicked" + state of the button using g_signal_connect_swapped(). This functions is similar to a g_signal_connect() with the difference lying in how the callback function is - treated. g_signal_connect_swapped() allow you to specify what the callback + treated. g_signal_connect_swapped() allows you to specify what the callback function should take as parameter by letting you pass it as data. In this case - the function being called back is gtk_widget_destroy() and the <varname>window</varname> - pointer is passed to it. This has the effect that when the button is clicked, - the whole GTK window is destroyed. In contrast if a normal g_signal_connect() were used - to connect the "clicked" signal with gtk_widget_destroy(), then the <varname>button</varname> - itself would have been destroyed, not the window. - More information about creating buttons can be found + the function being called back is gtk_widget_destroy() and the + <varname>window</varname> pointer is passed to it. This has the effect that when + the button is clicked, the whole GTK window is destroyed. In contrast, if a normal + g_signal_connect() were used to connect the "clicked" signal with + gtk_widget_destroy(), then the <varname>button</varname> itself would have been + destroyed, not the window. More information about creating buttons can be found <ulink url="https://wiki.gnome.org/HowDoI/Buttons">here</ulink>. </para> <para>The rest of the code in example-1.c is identical to example-0.c. Next section will elaborate further on how to add several GtkWidgets to your GTK application.</para> + </section> <section> <title>Packing</title> <para>When creating an application, you'll want to put more than one widget - inside a window. - When you want to put more than one widget into a window, + inside a window. When you want to put more than one widget into a window, it becomes important to control how each widget is positioned and sized. This is where packing comes in.</para> @@ -325,11 +326,11 @@ </para> <para>GTK includes application support that is built on top of - #GApplication. In this tutorial we'll build a simple application by + GApplication. In this tutorial we'll build a simple application by starting from scratch, adding more and more pieces over time. Along - the way, we'll learn about #GtkApplication, templates, resources, - application menus, settings, #GtkHeaderBar, #GtkStack, #GtkSearchBar, - #GtkListBox, and more.</para> + the way, we'll learn about GtkApplication, templates, resources, + application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar, + GtkListBox, and more.</para> <para>The full, buildable sources for these examples can be found in the examples/ directory of the GTK source distribution, or @@ -341,7 +342,7 @@ <section> <title>A trivial application</title> - <para>When using #GtkApplication, the main() function can be very + <para>When using GtkApplication, the main() function can be very simple. We just call g_application_run() and give it an instance of our application class.</para> @@ -350,7 +351,7 @@ </informalexample> <para>All the application logic is in the application class, which - is a subclass of #GtkApplication. Our example does not yet have any + is a subclass of GtkApplication. Our example does not yet have any interesting functionality. All it does is open a window when it is activated without arguments, and open the files it is given, if it is started with arguments.</para> @@ -368,7 +369,7 @@ </informalexample> <para>Another important class that is part of the application support - in GTK is #GtkApplicationWindow. It is typically subclassed as well. + in GTK is GtkApplicationWindow. It is typically subclassed as well. Our subclass does not do anything yet, so we will just get an empty window.</para> @@ -412,11 +413,10 @@ <section> <title>Populating the window</title> - <para>In this step, we use a #GtkBuilder template to associate a - #GtkBuilder ui file with our application window class.</para> - <para>Our simple ui file puts a #GtkHeaderBar on top of a #GtkStack - widget. The header bar contains a #GtkStackSwitcher, which is a - standalone widget to show a row of 'tabs' for the pages of a #GtkStack. + <para>In this step, we use a GtkBuilder template to associate a + GtkBuilder ui file with our application window class.</para> + <para>Our simple ui file gives the window a title, and puts a GtkStack + widget as the main content. </para> <informalexample> @@ -424,7 +424,7 @@ </informalexample> <para>To make use of this file in our application, we revisit - our #GtkApplicationWindow subclass, and call + our GtkApplicationWindow subclass, and call gtk_widget_class_set_template_from_resource() from the class init function to set the ui file as template for this class. We also add a call to gtk_widget_init_template() in the instance init @@ -453,8 +453,9 @@ example_app_window_class_init (ExampleAppWindowClass *class) <para>(<ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application2/exampleappwin.c">full source</ulink>)</para> </informalexample> - <para>You may have noticed that we used the <literal>_from_resource(<!-- -->)</literal> variant - of the function that sets a template. Now we need to use <ulink url="https://developer.gnome.org/gio/stable/GResource.html">GLib's resource functionality</ulink> + <para>You may have noticed that we used the <literal>_from_resource()</literal> + variant of the function that sets a template. Now we need to use + <ulink url="https://developer.gnome.org/gio/stable/GResource.html">GLib's resource functionality</ulink> to include the ui file in the binary. This is commonly done by listing all resources in a .gresource.xml file, such as this: </para> @@ -488,15 +489,14 @@ example_app_window_class_init (ExampleAppWindowClass *class) <para>In this step, we make our application show the content of all the files that it is given on the commandline.</para> - <para>To this end, we add a member to the struct in application - window subclass and keep a reference to the #GtkStack there. - The first member of the struct should be the parent type from - which the class is derived. Here, ExampleAppWindow is derived - from GtkApplicationWindow. - The gtk_widget_class_bind_template_child() function - arranges things so that after instantiating the template, the - @stack member of the struct will point to the widget of - the same name from the template.</para> + <para>To this end, we add a member to the struct of our application + window subclass and keep a reference to the GtkStack there. The first + member of the struct should be the parent type from which the class is + derived. Here, ExampleAppWindow is derived from GtkApplicationWindow. + The gtk_widget_class_bind_template_child() function arranges things so + that after instantiating the template, the <varname>stack</varname> + member of the struct will point to the widget of the same name from + the template.</para> <informalexample> <programlisting><
