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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
|
/* gtkactivatable.c
* Copyright (C) 2008 Tristan Van Berkom <tristan.van.berkom@gmail.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:gtkactivatable
* @Short_Description: An interface for activatable widgets
*
* Activatable widgets can be connected to a #GtkAction and reflects
* the state of its action. A #GtkActivatable can also provide feedback
* through its action, as they are responsible for activating their
* related actions.
*
* <refsect2>
* <title>Implementing GtkActivatable</title>
* <para>
* When extending a class that is already #GtkActivatable; it is only
* necessary to implement the #GtkActivatable->reset() and #GtkActivatable->update()
* methods and chain up to the parent implementation, however when introducing
* a new #GtkActivatable class; the #GtkActivatable:related-action and
* #GtkActivatable:use-action-appearance properties need to be handled by
* the implementor. Handling these properties is mostly a matter of installing
* the action pointer and boolean flag on your instance, and calling
* gtk_activatable_do_set_related_action() and gtk_activatable_reset() at the
* appropriate times.
* </para>
* <example>
* <title>A class fragment implementing #GtkActivatable</title>
* <programlisting><![CDATA[
*
* enum {
* ...
*
* PROP_ACTIVATABLE_RELATED_ACTION,
* PROP_ACTIVATABLE_USE_ACTION_APPEARANCE
* }
*
* struct _FooBarPrivate
* {
*
* ...
*
* GtkAction *action;
* gboolean use_action_appearance;
* };
*
* ...
*
* static void foo_bar_activatable_interface_init (GtkActivatableIface *iface);
* static void foo_bar_activatable_update (GtkActivatable *activatable,
* GtkAction *action,
* const gchar *property_name);
* static void foo_bar_activatable_reset (GtkActivatable *activatable,
* GtkAction *action);
* ...
*
*
* static void
* foo_bar_class_init (FooBarClass *klass)
* {
*
* ...
*
* g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_RELATED_ACTION, "related-action");
* g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE, "use-action-appearance");
*
* ...
* }
*
*
* static void
* foo_bar_activatable_interface_init (GtkActivatableIface *iface)
* {
* iface->update = foo_bar_activatable_update;
* iface->reset = foo_bar_activatable_reset;
* }
*
* ... Break the reference using gtk_activatable_do_set_related_action()...
*
* static void
* foo_bar_dispose (GObject *object)
* {
* FooBar *bar = FOO_BAR (object);
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);
*
* ...
*
* if (priv->action)
* {
* gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), NULL);
* priv->action = NULL;
* }
* G_OBJECT_CLASS (foo_bar_parent_class)->dispose (object);
* }
*
* ... Handle the "related-action" and "use-action-appearance" properties ...
*
* static void
* foo_bar_set_property (GObject *object,
* guint prop_id,
* const GValue *value,
* GParamSpec *pspec)
* {
* FooBar *bar = FOO_BAR (object);
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);
*
* switch (prop_id)
* {
*
* ...
*
* case PROP_ACTIVATABLE_RELATED_ACTION:
* foo_bar_set_related_action (bar, g_value_get_object (value));
* break;
* case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
* foo_bar_set_use_action_appearance (bar, g_value_get_boolean (value));
* break;
* default:
* G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
* break;
* }
* }
*
* static void
* foo_bar_get_property (GObject *object,
* guint prop_id,
* GValue *value,
* GParamSpec *pspec)
* {
* FooBar *bar = FOO_BAR (object);
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);
*
* switch (prop_id)
* {
*
* ...
*
* case PROP_ACTIVATABLE_RELATED_ACTION:
* g_value_set_object (value, priv->action);
* break;
* case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
* g_value_set_boolean (value, priv->use_action_appearance);
* break;
* default:
* G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
* break;
* }
* }
*
*
* static void
* foo_bar_set_use_action_appearance (FooBar *bar,
* gboolean use_appearance)
* {
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);
*
* if (priv->use_action_appearance != use_appearance)
* {
* priv->use_action_appearance = use_appearance;
*
* gtk_activatable_reset (GTK_ACTIVATABLE (bar), priv->action);
* }
* }
*
* ... call gtk_activatable_do_set_related_action() and then assign the action pointer,
* no need to reference the action here since gtk_activatable_do_set_related_action() already
* holds a reference here for you...
* static void
* foo_bar_set_related_action (FooBar *bar,
* GtkAction *action)
* {
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);
*
* if (priv->action == action)
* return;
*
* gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action);
*
* priv->action = action;
* }
*
* ... Selectively reset and update activatable depending on the use-action-appearance property ...
* static void
* gtk_button_activatable_reset (GtkActivatable *activatable,
* GtkAction *action)
* {
* GtkButtonPrivate *priv = GTK_BUTTON_GET_PRIVATE (activatable);
*
* if (!action)
* return;
*
* if (gtk_action_is_visible (action))
* gtk_widget_show (GTK_WIDGET (activatable));
* else
* gtk_widget_hide (GTK_WIDGET (activatable));
*
* gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));
*
* ...
*
* if (priv->use_action_appearance)
* {
* if (gtk_action_get_stock_id (action))
* foo_bar_set_stock (button, gtk_action_get_stock_id (action));
* else if (gtk_action_get_label (action))
* foo_bar_set_label (button, gtk_action_get_label (action));
*
* ...
*
* }
* }
*
* static void
* foo_bar_activatable_update (GtkActivatable *activatable,
* GtkAction *action,
* const gchar *property_name)
* {
* FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (activatable);
*
* if (strcmp (property_name, "visible") == 0)
* {
* if (gtk_action_is_visible (action))
* gtk_widget_show (GTK_WIDGET (activatable));
* else
* gtk_widget_hide (GTK_WIDGET (activatable));
* }
* else if (strcmp (property_name, "sensitive") == 0)
* gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));
*
* ...
*
* if (!priv->use_action_appearance)
* return;
*
* if (strcmp (property_name, "stock-id") == 0)
* foo_bar_set_stock (button, gtk_action_get_stock_id (action));
* else if (strcmp (property_name, "label") == 0)
* foo_bar_set_label (button, gtk_action_get_label (action));
*
* ...
* }]]></programlisting>
* </example>
* </refsect2>
*/
#include "config.h"
#include "gtkactivatable.h"
#include "gtkactiongroup.h"
#include "gtktypeutils.h"
#include "gtkprivate.h"
#include "gtkintl.h"
#include "gtkalias.h"
static void gtk_activatable_class_init (gpointer g_iface);
GType
gtk_activatable_get_type (void)
{
static GType activatable_type = 0;
if (!activatable_type)
activatable_type =
g_type_register_static_simple (G_TYPE_INTERFACE, I_("GtkActivatable"),
sizeof (GtkActivatableIface),
(GClassInitFunc) gtk_activatable_class_init,
0, NULL, 0);
return activatable_type;
}
static void
gtk_activatable_class_init (gpointer g_iface)
{
/**
* GtkActivatable:related-action:
*
* The action that this activatable will activate and receive
* updates from for various states and possibly appearance.
*
* <note><para>#GtkActivatable implementors need to handle the this property and
* call gtk_activatable_do_set_related_action() when it changes.</para></note>
*
* Since: 2.16
*/
g_object_interface_install_property (g_iface,
g_param_spec_object ("related-action",
P_("Related Action"),
P_("The action this activatable will activate and receive updates from"),
GTK_TYPE_ACTION,
GTK_PARAM_READWRITE));
/**
* GtkActivatable:use-action-appearance:
*
* Whether this activatable should reset its layout
* and appearance when setting the related action or when
* the action changes appearance.
*
* See the #GtkAction documentation directly to find which properties
* should be ignored by the #GtkActivatable when this property is %FALSE.
*
* <note><para>#GtkActivatable implementors need to handle this property
* and call gtk_activatable_reset() on the activatable widget when it changes.</para></note>
*
* Since: 2.16
*/
g_object_interface_install_property (g_iface,
g_param_spec_boolean ("use-action-appearance",
P_("Use Action Appearance"),
P_("Whether to use the related actions appearance properties"),
TRUE,
GTK_PARAM_READWRITE));
}
static void
gtk_activatable_update (GtkActivatable *activatable,
GtkAction *action,
const gchar *property_name)
{
GtkActivatableIface *iface;
g_return_if_fail (GTK_IS_ACTIVATABLE (activatable));
iface = GTK_ACTIVATABLE_GET_IFACE (activatable);
if (iface->update)
iface->update (activatable, action, property_name);
else
g_critical ("GtkActivatable->update() unimplemented for type %s",
g_type_name (G_OBJECT_TYPE (activatable)));
}
/**
* gtk_activatable_reset:
* @activatable: a #GtkActivatable
* @action: the related #GtkAction or %NULL
*
* This is called to update the activatable completely, this is called internally when
* the #GtkActivatable::related-action property is set or unset and by the implementing
* class when #GtkActivatable::use-action-appearance changes.
*
* Since: 2.16
**/
void
gtk_activatable_reset (GtkActivatable *activatable,
GtkAction *action)
{
GtkActivatableIface *iface;
g_return_if_fail (GTK_IS_ACTIVATABLE (activatable));
iface = GTK_ACTIVATABLE_GET_IFACE (activatable);
if (iface->reset)
iface->reset (activatable, action);
else
g_critical ("GtkActivatable->reset() unimplemented for type %s",
g_type_name (G_OBJECT_TYPE (activatable)));
}
/**
* gtk_activatable_set_related_action:
* @activatable: a #GtkActivatable
* @action: the #GtkAction to set
*
* Sets the related action on the @activatable object.
*
* <note><para>#GtkActivatable implementors need to handle the #GtkActivatable:related-action
* property and call gtk_activatable_do_set_related_action() when it changes.</para></note>
*
* Since: 2.16
**/
void
gtk_activatable_set_related_action (GtkActivatable *activatable,
GtkAction *action)
{
g_return_if_fail (GTK_IS_ACTIVATABLE (activatable));
g_return_if_fail (action == NULL || GTK_IS_ACTION (action));
g_object_set (activatable, "related-action", action, NULL);
}
static void
gtk_activatable_action_notify (GtkAction *action,
GParamSpec *pspec,
GtkActivatable *activatable)
{
gtk_activatable_update (activatable, action, pspec->name);
}
/**
* gtk_activatable_do_set_related_action:
* @activatable: a #GtkActivatable
* @action: the #GtkAction to set
*
* This is a utility function for #GtkActivatable implementors.
*
* When implementing #GtkActivatable you must call this when
* handling changes of the #GtkActivatable:related-action, and
* you must also use this to break references in #GObject->dispose().
*
* This function adds a reference to the currently set related
* action for you, it also makes sure the #GtkActivatable->update()
* method is called when the related #GtkAction properties change
* and registers to the action's proxy list.
*
* <note><para>Be careful to call this before setting the local
* copy of the #GtkAction property, since this function uses
* gtk_activatable_get_action() to retrieve the previous action</para></note>
*
* Since: 2.16
*/
void
gtk_activatable_do_set_related_action (GtkActivatable *activatable,
GtkAction *action)
{
GtkAction *prev_action;
prev_action = gtk_activatable_get_related_action (activatable);
if (prev_action != action)
{
if (prev_action)
{
g_signal_handlers_disconnect_by_func (prev_action, gtk_activatable_action_notify, activatable);
_gtk_action_remove_from_proxy_list (prev_action, GTK_WIDGET (activatable));
/* Some apps are using the object data directly...
* so continue to set it for a bit longer
*/
g_object_set_data (activatable, "gtk-action", NULL);
/*
* We don't want prev_action to be activated
* during the reset() call when syncing "active".
*/
gtk_action_block_activate (prev_action);
}
/* Some applications rely on their proxy UI to be set up
* before they receive the ::connect-proxy signal, so we
* need to call reset() before add_to_proxy_list().
*/
gtk_activatable_reset (activatable, action);
if (prev_action)
{
gtk_action_unblock_activate (prev_action);
g_object_unref (prev_action);
}
if (action)
{
g_object_ref (action);
g_signal_connect (G_OBJECT (action), "notify", G_CALLBACK (gtk_activatable_action_notify), activatable);
_gtk_action_add_to_proxy_list (action, GTK_WIDGET (activatable));
g_object_set_data (activatable, "gtk-action", action);
}
}
}
/**
* gtk_activatable_get_related_action:
* @activatable: a #GtkActivatable
*
* Gets the related #GtkAction for @activatable.
*
* Returns: the related #GtkAction if one is set.
*
* Since: 2.16
**/
GtkAction *
gtk_activatable_get_related_action (GtkActivatable *activatable)
{
GtkAction *action;
g_return_val_if_fail (GTK_IS_ACTIVATABLE (activatable), NULL);
g_object_get (activatable, "related-action", &action, NULL);
/* g_object_get() gives us a ref... */
if (action)
g_object_unref (action);
return action;
}
/**
* gtk_activatable_set_use_action_appearance:
* @activatable: a #GtkActivatable
* @use_appearance: whether to use the actions appearance
*
* Sets whether this activatable should reset its layout and appearance
* when setting the related action or when the action changes appearance
*
* <note><para>#GtkActivatable implementors need to handle the #GtkActivatable:use-action-appearance
* property and call gtk_activatable_reset() to update @activatable if needed.</para></note>
*
* Since: 2.16
**/
void
gtk_activatable_set_use_action_appearance (GtkActivatable *activatable,
gboolean use_appearance)
{
g_object_set (activatable, "use-action-appearance", use_appearance, NULL);
}
/**
* gtk_activatable_get_use_action_appearance:
* @activatable: a #GtkActivatable
*
* Gets whether this activatable should reset its layout
* and appearance when setting the related action or when
* the action changes appearance.
*
* Returns: whether @activatable uses its actions appearance.
*
* Since: 2.16
**/
gboolean
gtk_activatable_get_use_action_appearance (GtkActivatable *activatable)
{
gboolean use_appearance;
g_object_get (activatable, "use-action-appearance", &use_appearance, NULL);
return use_appearance;
}
#define __GTK_ACTIVATABLE_C__
#include "gtkaliasdef.c"
|