GNOME.org
 

[gtk/matthiasc/for-master: 100/104] docs: Rearrange the introduction some more

commit 91f0fcde968cf2141e649040782041589ee66a7d
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue May 12 01:02:07 2020 -0400

    docs: Rearrange the introduction some more
    
    Fine-tune some wording, and move the Custom Drawing
    example earlier.

 docs/reference/gtk/getting_started.xml.in | 122 +++++++++++++++---------------
 1 file changed, 59 insertions(+), 63 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in
index d8e638f6e1..dba22cf0de 100644
--- a/docs/reference/gtk/getting_started.xml.in
+++ b/docs/reference/gtk/getting_started.xml.in
@@ -9,7 +9,7 @@
   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.
+  Widgets are organized in a hierarchy. The window widget is the main container.
   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
@@ -77,7 +77,7 @@
     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 #GApplicationFlags as input for your
+    Lastly gtk_application_new() takes GApplicationFlags as input for your
     application, if your application would have special needs.
     </para>
 
@@ -112,14 +112,14 @@
     <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_sizei()
+    <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>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
+    <para>When you close the window, by for example pressing the X, the
+    g_application_run() call returns with a number which is saved inside
+    an integer variable named <varname>status</varname>. Afterwards, the
     GtkApplication object is freed from memory with g_object_unref().
-    Finally the status integer is returned and the GTK application exits.</para>
+    Finally the status integer is returned and the application exits.</para>
 
     <para>While the program is running, GTK is receiving
     <firstterm>events</firstterm>. These are typically input events caused by
@@ -204,7 +204,7 @@
   <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
+  <para>The rest of the code in example-1.c is identical to example-0.c. The next
   section will elaborate further on how to add several GtkWidgets to your GTK
   application.</para>
   </section>
@@ -213,9 +213,8 @@
     <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,
-    it becomes important to control how each widget is positioned and sized.
-    This is where packing comes in.</para>
+    inside a window. When you do so, it becomes important to control how each widget
+    is positioned and sized. This is where packing comes in.</para>
 
     <para>GTK comes with a large variety of <firstterm>layout containers</firstterm>
     whose purpose it is to control the layout of the child widgets that are
@@ -245,16 +244,60 @@
     </para>
   </section>
 
+  <section>
+    <title>Custom Drawing</title>
+
+    <para>Many widgets, like buttons, do all their drawing themselves. You
+    just tell them the label you want to see, and they figure out what font
+    to use, draw the button outline and focus rectangle, etc. Sometimes, it
+    is necessary to do some custom drawing. In that case, a GtkDrawingArea
+    might be the right widget to use. It offers a canvas on which you can
+    draw by connecting to the ::draw signal.
+    </para>
+
+    <para>The contents of a widget often need to be partially or fully redrawn,
+    e.g. when another window is moved and uncovers part of the widget, or
+    when the window containing it is resized. It is also possible to explicitly
+    cause part or all of the widget to be redrawn, by calling
+    gtk_widget_queue_draw() or its variants. GTK takes care of most of the
+    details by providing a ready-to-use cairo context to the ::draw signal
+    handler.</para>
+
+    <para>The following example shows a ::draw signal handler. It is a bit
+    more complicated than the previous examples, since it also demonstrates
+    input event handling by means of event controllers.</para>
+
+    <informalfigure>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="drawing.png" format="PNG"/>
+        </imageobject>
+      </mediaobject>
+    </informalfigure>
+
+    <example id="gtk-getting-started-drawing">
+      <title>Drawing in response to input</title>
+      <para>Create a new file with the following content named example-4.c.</para>
+      <programlisting><xi:include href="@SRC_DIR@/examples/drawing.c" parse="text"><xi:fallback>MISSING 
XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
+    </example>
+    <para>
+      You can compile the program above with GCC using:
+      <literallayout>
+        <literal>gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`</literal>
+      </literallayout>
+    </para>
+  </section>
+
   <section>
     <title>Building user interfaces</title>
 
-    <para>When construcing a more complicated user interface, with dozens
+    <para>When constructing a more complicated user interface, with dozens
     or hundreds of widgets, doing all the setup work in C code is
     cumbersome, and making changes becomes next to impossible.</para>
 
     <para>Thankfully, GTK supports the separation of user interface
     layout from your business logic, by using UI descriptions in an
-    XML format that can be parsed by the #GtkBuilder class.</para>
+    XML format that can be parsed by the GtkBuilder class.</para>
 
     <example>
       <title>Packing buttons with GtkBuilder</title>
@@ -333,8 +376,8 @@
     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
+    <para>The full, buildable sources for these examples can be found in the
+    <filename>examples/</filename> directory of the GTK source distribution, or
     <ulink url="https://gitlab.gnome.org/GNOME/gtk/blob/master/examples";>online</ulink> in the GTK git 
repository.
     You can build each example separately by using make with the <filename>Makefile.example</filename>
     file. For more information, see the <filename>README</filename> included in the
@@ -887,10 +930,7 @@ example_app_window_init (ExampleAppWindow *win)
 
       <para>The code to populate the sidebar with buttons for the words
       found in each file is a little too involved to go into here. But we'll
-      look at the code to add the gears menu.</para>
-
-      <para>As expected by now, the gears menu is specified in a GtkBuilder
-      ui file.</para>
+      look at the code to add a checkbutton for the new feature to the menu.</para>
 
       <informalexample>
         <programlisting><xi:include href="@SRC_DIR@/examples/application8/gears-menu.ui" 
parse="text"><xi:fallback>MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
@@ -1005,48 +1045,4 @@ example_app_window_init (ExampleAppWindow *win)
     </section>
   </section>
 
-  <section>
-    <title>Custom Drawing</title>
-
-    <para>Many widgets, like buttons, do all their drawing themselves. You
-    just tell them the label you want to see, and they figure out what font
-    to use, draw the button outline and focus rectangle, etc. Sometimes, it
-    is necessary to do some custom drawing. In that case, a GtkDrawingArea
-    might be the right widget to use. It offers a canvas on which you can
-    draw by connecting to the ::draw signal.
-    </para>
-
-    <para>The contents of a widget often need to be partially or fully redrawn,
-    e.g. when another window is moved and uncovers part of the widget, or
-    when the window containing it is resized. It is also possible to explicitly
-    cause part or all of the widget to be redrawn, by calling
-    gtk_widget_queue_draw() or its variants. GTK takes care of most of the
-    details by providing a ready-to-use cairo context to the ::draw signal
-    handler.</para>
-
-    <para>The following example shows a ::draw signal handler. It is a bit
-    more complicated than the previous examples, since it also demonstrates
-    input event handling by means of event controllers.</para>
-
-    <informalfigure>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="drawing.png" format="PNG"/>
-        </imageobject>
-      </mediaobject>
-    </informalfigure>
-
-    <example id="gtk-getting-started-drawing">
-      <title>Drawing in response to input</title>
-      <para>Create a new file with the following content named example-4.c.</para>
-      <programlisting><xi:include href="@SRC_DIR@/examples/drawing.c" parse="text"><xi:fallback>MISSING 
XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
-    </example>
-    <para>
-      You can compile the program above with GCC using:
-      <literallayout>
-        <literal>gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`</literal>
-      </literallayout>
-    </para>
-  </section>
-
 </chapter>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]