This file is indexed.

/usr/share/gtk-doc/html/libwnck-3.0/getting-started.html is in libwnck-3-dev 3.20.1-3.

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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Part II. Getting Started with libwnck: Libwnck Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Libwnck Reference Manual">
<link rel="up" href="index.html" title="Libwnck Reference Manual">
<link rel="prev" href="overview.html" title="Part I. Libwnck Overview">
<link rel="next" href="core.html" title="Part III. Libwnck Core Window Management Support">
<meta name="generator" content="GTK-Doc V1.25 (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="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="overview.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="core.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="part">
<div class="titlepage"><div><div><h1 class="title">
<a name="getting-started"></a>Part II. Getting Started with libwnck</h1></div></div></div>
<div class="refsect1">
<a name="getting-started.use-cases"></a><h2>Use Cases</h2>
<p>
     Most users of libwnck should be tools that deal heavily with window management in one way or another: tasklists and pagers are obvious examples, but tools to automatically organize windows, to track resources of windows, or to inspect what is happening on a display can also be built with this library.
    </p>
<p>
     Applications that just need to do some management on their own windows (like positioning one of their windows on a specific workspace) should likely not use libwnck, as the use of this library is relatively expensive in terms of resources. The internals of libwnck make sure that the library always tracks everything that is occurring on the display, mirroring various information from the X server and actively using resources to update the cached information as it changes. In concrete terms, every time something changes on the display, every application using libwnck will wake up. An application that is not dealing specifically with window management should not do this. While <a class="link" href="libwnck-Miscellaneous-Functions.html#wnck-shutdown" title="wnck_shutdown ()"><code class="function">wnck_shutdown()</code></a> can be used to mitigate the expensiveness of libwnck, it is generally not considered a proper solution.
    </p>
<div class="note"><p>
     When considering the use of libwnck, it makes sense to keep in mind the cost of the library. For example, it is possible to share this cost between various tools all dealing in one way or another with window management, by grouping them in the same process, even if from a UI perspective they all look like different applications.
    </p></div>
</div>
<div class="refsect1">
<a name="getting-started.pitfalls"></a><h2>Common Pitfalls</h2>
<p>
     While the API provided by libwnck should be mostly straight-forward in general, a few pitfalls are often hit by users of the library.
    </p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="getting-started.pitfalls.force-update"></a>Explicit fetching of information</h3></div></div></div>
<p>
      At its creation, a <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object will not have fetched information from the X server. If queried immediately after its creation (via <a class="link" href="WnckScreen.html#wnck-screen-get-windows" title="wnck_screen_get_windows ()"><code class="function">wnck_screen_get_windows()</code></a> or <a class="link" href="WnckScreen.html#wnck-screen-get-workspaces" title="wnck_screen_get_workspaces ()"><code class="function">wnck_screen_get_workspaces()</code></a>, for example), the <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object will look like there are no workspaces nor windows on the screen. This information is fetched in the main event loop with an idle source, to avoid an expensive synchronous operation on startup. If no main event loop is used, or if the information is needed as soon as possible after the creation of the object, <a class="link" href="WnckScreen.html#wnck-screen-force-update" title="wnck_screen_force_update ()"><code class="function">wnck_screen_force_update()</code></a> can be used to explicitly fetch the information.
     </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="getting-started.pitfalls.lazy-initialization"></a>Lazy initialization of WnckScreen objects and signals</h3></div></div></div>
<p>
      As mentioned above, a <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object will have no information at its creation: it is lazily initialized during a main event loop. This lazy initialization will lead to the emission of many signals by the <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object: for instance, the <a class="link" href="WnckScreen.html#WnckScreen-window-opened" title="The “window-opened” signal"><code class="function">"window-opened"</code></a> signal will be emitted for all <a class="link" href="WnckWindow.html" title="WnckWindow"><span class="type">WnckWindow</span></a> objects representing existing windows during the lazy initialization. This is actually a feature that enables you to easily initialize the state of your application, with the same code you will use to update its state when new windows get opened; there is an <a class="link" href="getting-started.html#getting-started.examples.lazy-initialization">example</a> showing this.
     </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="getting-started.pitfalls.memory-management"></a>Memory management</h3></div></div></div>
<p>
      All objects provided by the <a class="link" href="core.html" title="Part III. Libwnck Core Window Management Support">Core Window Management Support</a> are owned by libwnck and should not be referenced or unreferenced by the user. Those objects are tied to X resources, and it makes no sense to keep the objects alive when the X resources are gone; doing so could lead to errors. Therefore it is important that, when keeping in memory a pointer to such an object, the life of this object is tracked to make sure the pointer is always valid.
     </p>
<p>
      This memory management model is important to keep in mind for users of <a class="link" href="libwnck-Miscellaneous-Functions.html#wnck-shutdown" title="wnck_shutdown ()"><code class="function">wnck_shutdown()</code></a>, and especially for users of libwnck through introspection. With introspection, all variables pointing to objects owned by libwnck must be cleared before <a class="link" href="libwnck-Miscellaneous-Functions.html#wnck-shutdown" title="wnck_shutdown ()"><code class="function">wnck_shutdown()</code></a> as the introspection support can add some references to the objects.
     </p>
<p>
      For instance, the following would work in Python:
      </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6</pre></td>
        <td class="listing_code"><pre class="programlisting">from gi<span class="gtkdoc opt">.</span>repository import Wnck

screen <span class="gtkdoc opt">=</span> Wnck<span class="gtkdoc opt">.</span>Screen<span class="gtkdoc opt">.</span><span class="function">get_default</span><span class="gtkdoc opt">()</span>
<span class="gtkdoc opt">[...]</span>
screen <span class="gtkdoc opt">=</span> None
Wnck<span class="gtkdoc opt">.</span><span class="function">Shutdown</span><span class="gtkdoc opt">()</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
     </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="getting-started.pitfalls.client-type"></a>Source indication</h3></div></div></div>
<p>
      Window management actions that are performed with libwnck are generally implemented as requests to the window manager. In order to not disturb the workflow of the user, the window manager may choose to put restrictions on various requests sent from applications. However, if those requests represent direct actions from the user, then the window manager will obey them. To indicate that the requests are the result of actions from the user, the application should set the <a class="ulink" href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#sourceindication" target="_top">source indication</a> in the requests, as defined in the EWMH. The <a class="link" href="libwnck-Miscellaneous-Functions.html#wnck-set-client-type" title="wnck_set_client_type ()"><code class="function">wnck_set_client_type()</code></a> can be used to define the source indication.
     </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="getting-started.pitfalls.gdk-init"></a>GDK initialization</h3></div></div></div>
<p>
      Internally, libwnck uses GDK. This means that before any call to libwnck API, GDK needs to be initialized. This can be achieved with <code class="function">gdk_init()</code>, or indirectly via <code class="function">gtk_init()</code>.
     </p>
</div>
</div>
<div class="refsect1">
<a name="getting-started.examples"></a><h2>Examples</h2>
<p><a name="getting-started.examples.force-update"></a>
     This first example is a small utility listing all windows on the current screen. As this is all done synchronously, without using a main event loop, we use <a class="link" href="WnckScreen.html#wnck-screen-force-update" title="wnck_screen_force_update ()"><code class="function">wnck_screen_force_update()</code></a> to explicitly fetch the information needed for the <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object.

     </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>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</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc ppc">#include &lt;libwnck/libwnck.h&gt;</span>

<span class="gtkdoc kwb">int</span>
<span class="function">main</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">int</span>    argc<span class="gtkdoc opt">,</span>
      <span class="gtkdoc kwb">char</span> <span class="gtkdoc opt">**</span>argv<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">{</span>
  WnckScreen <span class="gtkdoc opt">*</span>screen<span class="gtkdoc opt">;</span>
  WnckWindow <span class="gtkdoc opt">*</span>active_window<span class="gtkdoc opt">;</span>
  GList <span class="gtkdoc opt">*</span>window_l<span class="gtkdoc opt">;</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/gdk3/gdk3-General.html#gdk-init">gdk_init</a></span> <span class="gtkdoc opt">(&amp;</span>argc<span class="gtkdoc opt">, &amp;</span>argv<span class="gtkdoc opt">);</span>

  screen <span class="gtkdoc opt">=</span> <span class="function"><a href="WnckScreen.html#wnck-screen-get-default">wnck_screen_get_default</a></span> <span class="gtkdoc opt">();</span>

  <span class="function"><a href="WnckScreen.html#wnck-screen-force-update">wnck_screen_force_update</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">);</span>

  active_window <span class="gtkdoc opt">=</span> <span class="function"><a href="WnckScreen.html#wnck-screen-get-active-window">wnck_screen_get_active_window</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">);</span>

  <span class="keyword">for</span> <span class="gtkdoc opt">(</span>window_l <span class="gtkdoc opt">=</span> <span class="function"><a href="WnckScreen.html#wnck-screen-get-windows">wnck_screen_get_windows</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">);</span> window_l <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">;</span> window_l <span class="gtkdoc opt">=</span> window_l<span class="gtkdoc opt">-&gt;</span>next<span class="gtkdoc opt">)</span>
    <span class="gtkdoc opt">{</span>
      WnckWindow <span class="gtkdoc opt">*</span>window <span class="gtkdoc opt">=</span> <span class="function">WNCK_WINDOW</span> <span class="gtkdoc opt">(</span>window_l<span class="gtkdoc opt">-&gt;</span>data<span class="gtkdoc opt">);</span>
      <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html#g-print">g_print</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;%s%s</span><span class="gtkdoc esc">\n</span><span class="string">&quot;</span><span class="gtkdoc opt">,</span> <span class="function"><a href="WnckWindow.html#wnck-window-get-name">wnck_window_get_name</a></span> <span class="gtkdoc opt">(</span>window<span class="gtkdoc opt">),</span>
                  window <span class="gtkdoc opt">==</span> active_window ? <span class="string">&quot; (active)&quot;</span> <span class="gtkdoc opt">:</span> <span class="string">&quot;&quot;</span><span class="gtkdoc opt">);</span>
    <span class="gtkdoc opt">}</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    </p>
<p><a name="getting-started.examples.lazy-initialization"></a>
     The second example is similar, except that we use a main event loop. We connect to the <a class="link" href="WnckScreen.html#WnckScreen-window-opened" title="The “window-opened” signal"><code class="function">"window-opened"</code></a> signal to print information about new <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> objects. Here, we use the fact that the <a class="link" href="WnckScreen.html#WnckScreen-window-opened" title="The “window-opened” signal"><code class="function">"window-opened"</code></a> signal is emitted for all existing windows during the lazy initialization of the <a class="link" href="WnckScreen.html" title="WnckScreen"><span class="type">WnckScreen</span></a> object, in order to achieve an output similar to the previous example. However, during the lazy initialization, the active window is not necessarily known yet and we cannot tell whether the opened window is the currently active one. We connect to the <a class="link" href="WnckScreen.html#WnckScreen-active-window-changed" title="The “active-window-changed” signal"><code class="function">"active-window-changed"</code></a> signal to determine the active window when this information becomes available.

     </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>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</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc ppc">#include &lt;libwnck/libwnck.h&gt;</span>

<span class="gtkdoc kwb">static void</span>
<span class="function">on_window_opened</span> <span class="gtkdoc opt">(</span>WnckScreen <span class="gtkdoc opt">*</span>screen<span class="gtkdoc opt">,</span>
           WnckWindow <span class="gtkdoc opt">*</span>window<span class="gtkdoc opt">,</span>
           gpointer    data<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">{</span>
  <span class="comment">/* Note: when this event is emitted while screen is initialized, there is no</span>
<span class="comment">   * active window yet. */</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html#g-print">g_print</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;%s</span><span class="gtkdoc esc">\n</span><span class="string">&quot;</span><span class="gtkdoc opt">,</span> <span class="function"><a href="WnckWindow.html#wnck-window-get-name">wnck_window_get_name</a></span> <span class="gtkdoc opt">(</span>window<span class="gtkdoc opt">));</span>
<span class="gtkdoc opt">}</span>

<span class="gtkdoc kwb">static void</span>
<span class="function">on_active_window_changed</span> <span class="gtkdoc opt">(</span>WnckScreen <span class="gtkdoc opt">*</span>screen<span class="gtkdoc opt">,</span>
                   WnckWindow <span class="gtkdoc opt">*</span>previously_active_window<span class="gtkdoc opt">,</span>
                   gpointer    data<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">{</span>
  WnckWindow <span class="gtkdoc opt">*</span>active_window<span class="gtkdoc opt">;</span>

  active_window <span class="gtkdoc opt">=</span> <span class="function"><a href="WnckScreen.html#wnck-screen-get-active-window">wnck_screen_get_active_window</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">);</span>

  <span class="keyword">if</span> <span class="gtkdoc opt">(</span>active_window<span class="gtkdoc opt">)</span>
    <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html#g-print">g_print</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;active: %s</span><span class="gtkdoc esc">\n</span><span class="string">&quot;</span><span class="gtkdoc opt">,</span> <span class="function"><a href="WnckWindow.html#wnck-window-get-name">wnck_window_get_name</a></span> <span class="gtkdoc opt">(</span>active_window<span class="gtkdoc opt">));</span>
  <span class="keyword">else</span>
    <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html#g-print">g_print</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;no active window</span><span class="gtkdoc esc">\n</span><span class="string">&quot;</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>

<span class="gtkdoc kwb">int</span>
<span class="function">main</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">int</span>    argc<span class="gtkdoc opt">,</span>
      <span class="gtkdoc kwb">char</span> <span class="gtkdoc opt">**</span>argv<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">{</span>
  GMainLoop <span class="gtkdoc opt">*</span>loop<span class="gtkdoc opt">;</span>
  WnckScreen <span class="gtkdoc opt">*</span>screen<span class="gtkdoc opt">;</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/gdk3/gdk3-General.html#gdk-init">gdk_init</a></span> <span class="gtkdoc opt">(&amp;</span>argc<span class="gtkdoc opt">, &amp;</span>argv<span class="gtkdoc opt">);</span>

  loop <span class="gtkdoc opt">=</span> <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-main-loop-new">g_main_loop_new</a></span> <span class="gtkdoc opt">(</span>NULL<span class="gtkdoc opt">,</span> FALSE<span class="gtkdoc opt">);</span>
  screen <span class="gtkdoc opt">=</span> <span class="function"><a href="WnckScreen.html#wnck-screen-get-default">wnck_screen_get_default</a></span> <span class="gtkdoc opt">();</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/gobject/gobject-Signals.html#g-signal-connect">g_signal_connect</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">,</span> <span class="string">&quot;window-opened&quot;</span><span class="gtkdoc opt">,</span>
             <span class="function"><a href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span> <span class="gtkdoc opt">(</span>on_window_opened<span class="gtkdoc opt">),</span> NULL<span class="gtkdoc opt">);</span>
  <span class="function"><a href="/usr/share/gtk-doc/html/gobject/gobject-Signals.html#g-signal-connect">g_signal_connect</a></span> <span class="gtkdoc opt">(</span>screen<span class="gtkdoc opt">,</span> <span class="string">&quot;active-window-changed&quot;</span><span class="gtkdoc opt">,</span>
             <span class="function"><a href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span> <span class="gtkdoc opt">(</span>on_active_window_changed<span class="gtkdoc opt">),</span> NULL<span class="gtkdoc opt">);</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-main-loop-run">g_main_loop_run</a></span> <span class="gtkdoc opt">(</span>loop<span class="gtkdoc opt">);</span>

  <span class="function"><a href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-main-loop-unref">g_main_loop_unref</a></span> <span class="gtkdoc opt">(</span>loop<span class="gtkdoc opt">);</span>

  <span class="keyword">return</span> <span class="number">0</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25</div>
</body>
</html>