This file is indexed.

/usr/share/doc/libgtk-3-doc/gtk3/gtk-getting-started.html is in libgtk-3-doc 3.4.1-0ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Getting Started with GTK+</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
<link rel="up" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="prev" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="next" href="gtk-building.html" title="Compiling the GTK+ libraries">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="gtk.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="gtk.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ 3 Reference Manual</th>
<td><a accesskey="n" href="gtk-building.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="gtk-getting-started"></a>Getting Started with GTK+</h2></div></div></div>
<p>This chapter is contains some tutorial information to get you
  started with GTK+ programming. It assumes that you have GTK+, its
  dependencies and a C compiler installed and ready to use. If you
  need to build GTK+ itself first, refer to the
  <a class="link" href="gtk-compiling.html" title="Compiling GTK+ Applications">Compiling the GTK+ libraries</a>
  section in this reference.</p>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="idp6024816"></a>Basics</h2></div></div></div>
<p>To begin our introduction to GTK, we'll start with the simplest
    program possible. This program will create an empty 200x200 pixel
    window:</p>
<p>
      <img src="window-default.png">
    </p>
<div class="informalexample"><pre class="programlisting">
      FIXME: MISSING XINCLUDE CONTENT
    </pre></div>
<p>You can compile the program above with GCC using:</p>
<div class="literallayout"><p><br>
      <code class="literal">gcc `pkg-config --cflags gtk+-3.0` -o window-default window-default.c `pkg-config --libs gtk+-3.0`</code><br>
    </p></div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>For more information on how to compile a GTK+ application, please
    refer to the <a class="link" href="gtk-compiling.html" title="Compiling GTK+ Applications">Compiling GTK+ Applications</a>
    section in this reference.</p>
</div>
<p>All GTK+ applications will, of course, include
    <code class="filename">gtk/gtk.h</code>, which declares functions, types and
    macros required by GTK+ applications.</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>Even if GTK+ installs multiple header files, only the
    top-level <code class="filename">gtk/gtk.h</code> header can be directly included
    by third party code. The compiler will abort with an error if any other
    header is directly included.</p>
</div>
<p>We then proceed into the <code class="function">main</code>() function of the
    application, and we declare a <code class="varname">window</code> variable as a pointer
    of type <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a>.</p>
<p>The following line will call <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a>, which
    is the initialization function for GTK+; this function will set up GTK+,
    the type system, the connection to the windowing environment, etc. The
    <a class="link" href="gtk3-General.html#gtk-init" title="gtk_init ()"><code class="function">gtk_init()</code></a> takes as arguments the pointers to the command line arguments
    counter and 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.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>For more information on which command line arguments GTK+
    recognizes, please refer to the <a class="link" href="gtk-running.html" title="Running GTK+ Applications">Running GTK+
    Applications</a> section in this reference.</p>
</div>
<p>The call to <a class="link" href="GtkWindow.html#gtk-window-new" title="gtk_window_new ()"><code class="function">gtk_window_new()</code></a> will create a new <a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> and store
    it inside the <code class="varname">window</code> variable. The type of the window
    is <a class="link" href="gtk3-Standard-Enumerations.html#GTK-WINDOW-TOPLEVEL:CAPS"><code class="literal">GTK_WINDOW_TOPLEVEL</code></a>, which means that the <a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> will be managed
    by the windowing system: it will have a frame, a title bar and window
    controls, depending on the platform.</p>
<p>In order to terminate the application when the <a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> is
    destroyed, we connect the <a class="link" href="GtkWidget.html#GtkWidget-destroy" title='The "destroy" signal'><span class="type">"destroy"</span></a> signal to the <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a>
    function. This function will terminate the GTK+ main loop started by calling
    <a class="link" href="gtk3-General.html#gtk-main" title="gtk_main ()"><code class="function">gtk_main()</code></a> later. The <a class="link" href="GtkWidget.html#GtkWidget-destroy" title='The "destroy" signal'><span class="type">"destroy"</span></a> signal is emitted when a widget is
    destroyed, either by explicitly calling <a class="link" href="GtkWidget.html#gtk-widget-destroy" title="gtk_widget_destroy ()"><code class="function">gtk_widget_destroy()</code></a> or when the
    widget is unparented. Top-level <a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a>s are also destroyed when
    the Close window control button is clicked.</p>
<p><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a>s are hidden by default. By calling <a class="link" href="GtkWidget.html#gtk-widget-show" title="gtk_widget_show ()"><code class="function">gtk_widget_show()</code></a>
    on a <a class="link" href="GtkWidget.html" title="GtkWidget"><span class="type">GtkWidget</span></a> we are asking GTK+ to set the visibility attribute so that it
    can be displayed. All this work is done after the main loop has been
    started.</p>
<p>The last line of interest is the call to <a class="link" href="gtk3-General.html#gtk-main" title="gtk_main ()"><code class="function">gtk_main()</code></a>. This function will
    start the GTK+ main loop and will block the control flow of the
    <code class="function">main()</code> until the <a class="link" href="gtk3-General.html#gtk-main-quit" title="gtk_main_quit ()"><code class="function">gtk_main_quit()</code></a> function is called.</p>
<p>While the program is running, GTK+ is receiving
    <em class="firstterm">events</em>. These are typically input events caused by
    the user interacting with your program, but also things like messages from
    the window manager or other applications. GTK+ processes these and as a
    result, <em class="firstterm">signals</em> may be emitted on your widgets.
    Connecting handlers for these signals is how you normally make your
    program do something in response to user input.</p>
<p>The following example is slightly more complex, and tries to
    showcase some of the capabilities of GTK+.</p>
<p>In the long tradition of programming languages and libraries,
    it is called <span class="emphasis"><em>Hello, World</em></span>.</p>
<p>
      <img src="hello-world.png">
    </p>
<div class="example">
<a name="gtk-getting-started-hello-world"></a><p class="title"><b>Example 1. Hello World in GTK+</b></p>
<div class="example-contents"><pre class="programlisting">
        FIXME: MISSING XINCLUDE CONTENT
      </pre></div>
</div>
<br class="example-break">
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="idp10589144"></a>Packing</h2></div></div></div>
<p>When creating an application, you'll want to put more than one widget
    inside a window. Our first helloworld example only used one widget so we
    could simply use a <a class="link" href="GtkContainer.html#gtk-container-add" title="gtk_container_add ()"><code class="function">gtk_container_add()</code></a> call to "pack" the widget into the
    window. But when you want to put more than one widget into a window, it
    it becomes important to control how each widget is positioned and sized.
    This is where packing comes in.</p>
<p>GTK+ comes with a large variety of <em class="firstterm">layout containers</em>
    whose purpose it is to control the layout of the child widgets that are
    added to them. See <a class="xref" href="LayoutContainers.html" title="Layout Containers"><i>Layout Containers</i></a> for an overview.</p>
<p>The following example shows how the GtkGrid container lets you
    arrange several buttons:</p>
<p>
      <img src="grid-packing.png">
    </p>
<div class="example">
<a name="gtk-getting-started-grid-packing"></a><p class="title"><b>Example 2. Packing buttons</b></p>
<div class="example-contents"><pre class="programlisting">
        FIXME: MISSING XINCLUDE CONTENT
      </pre></div>
</div>
<br class="example-break">
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="idp10594504"></a>Drawing</h2></div></div></div>
<p>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 <a class="link" href="GtkDrawingArea.html" title="GtkDrawingArea"><span class="type">GtkDrawingArea</span></a>
    might be the right widget to use. It offers a canvas on which you can
    draw by connecting to the <a class="link" href="GtkWidget.html#GtkWidget-draw" title='The "draw" signal'><span class="type">"draw"</span></a> signal.
    </p>
<p>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 tie window containing it is resized. It is also possible to explicitly
    cause part or all of the widget to be redrawn, by calling
    <a class="link" href="GtkWidget.html#gtk-widget-queue-draw" title="gtk_widget_queue_draw ()"><code class="function">gtk_widget_queue_draw()</code></a> or its variants. GTK+ takes care of most of the
    details by providing a ready-to-use cairo context to the ::draw signal
    handler.</p>
<p>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 ::button-press and ::motion-notify
    handlers.</p>
<p>
      <img src="drawing.png">
    </p>
<div class="example">
<a name="gtk-getting-started-drawing"></a><p class="title"><b>Example 3. Drawing in response to input</b></p>
<div class="example-contents"><pre class="programlisting">
        FIXME: MISSING XINCLUDE CONTENT
      </pre></div>
</div>
<br class="example-break">
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="idp9271216"></a>Building interfaces</h2></div></div></div>
<p>When construcing 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.</p>
<p>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 <a class="link" href="GtkBuilder.html" title="GtkBuilder"><span class="type">GtkBuilder</span></a> class.</p>
<div class="example">
<a name="idp9272808"></a><p class="title"><b>Example 4. Packing buttons with GtkBuilder</b></p>
<div class="example-contents">
<pre class="programlisting">
        FIXME: MISSING XINCLUDE CONTENT
      </pre>
      The builder.ui file looks like this:
      <pre class="programlisting">
        FIXME: MISSING XINCLUDE CONTENT
      </pre>
</div>
</div>
<br class="example-break"><p>Note that GtkBuilder can also be used to construct objects
    that are not widgets, such as tree models, adjustments, etc.
    That is the reason the method we use here is called
    <a class="link" href="GtkBuilder.html#gtk-builder-get-object" title="gtk_builder_get_object ()"><code class="function">gtk_builder_get_object()</code></a> and returns a GObject* instead of a
    GtkWidget*.</p>
<p>Normally, you would pass a full path to
    <a class="link" href="GtkBuilder.html#gtk-builder-add-from-file" title="gtk_builder_add_from_file ()"><code class="function">gtk_builder_add_from_file()</code></a> to make the execution of your program
    independent of the current directory. A common location to install
    UI descriptions and similar data is
    <code class="filename">/usr/share/<em class="replaceable"><code>appname</code></em></code>.
    </p>
<p>It is also possible to embed the UI description in the source
    code as a string and use <a class="link" href="GtkBuilder.html#gtk-builder-add-from-string" title="gtk_builder_add_from_string ()"><code class="function">gtk_builder_add_from_string()</code></a> to load it.
    But keeping the UI description in a separate file has several
    advantages: It is then possible to make minor adjustments to the UI
    without recompiling your program, and, more importantly, graphical
    UI editors such as <a class="ulink" href="http://glade.gnome.org" target="_top">glade</a>
    can load the file and allow you to create and modify your UI by
    point-and-click.</p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>