gtkactivatable.c 16.4 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* 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
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16
17
18
 */

/**
Matthias Clasen's avatar
Matthias Clasen committed
19
20
 * SECTION:gtkactivatable
 * @Short_Description: An interface for activatable widgets
21
 * @Title: GtkActivatable
22
23
 *
 * Activatable widgets can be connected to a #GtkAction and reflects
Matthias Clasen's avatar
Matthias Clasen committed
24
 * the state of its action. A #GtkActivatable can also provide feedback
25
 * through its action, as they are responsible for activating their
26
27
 * related actions.
 *
28
29
 * # Implementing GtkActivatable
 *
30
 * When extending a class that is already #GtkActivatable; it is only
31
32
33
 * necessary to implement the #GtkActivatable->sync_action_properties()
 * and #GtkActivatable->update() methods and chain up to the parent
 * implementation, however when introducing
34
35
 * a new #GtkActivatable class; the #GtkActivatable:related-action and
 * #GtkActivatable:use-action-appearance properties need to be handled by
36
37
38
39
 * 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_sync_action_properties() at the appropriate times.
40
41
42
 *
 * ## A class fragment implementing #GtkActivatable
 *
43
 * |[<!-- language="C" -->
44
45
46
 *
 * enum {
 * ...
47
 *
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 * PROP_ACTIVATABLE_RELATED_ACTION,
 * PROP_ACTIVATABLE_USE_ACTION_APPEARANCE
 * }
 * 
 * struct _FooBarPrivate
 * {
 * 
 *   ...
 * 
 *   GtkAction      *action;
 *   gboolean        use_action_appearance;
 * };
 * 
 * ...
 * 
63
64
65
66
67
68
 * 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_sync_action_properties (GtkActivatable       *activatable,
 * 						           GtkAction            *action);
69
 * ...
70
71
 *
 *
72
73
74
 * static void
 * foo_bar_class_init (FooBarClass *klass)
 * {
75
 *
76
 *   ...
77
 *
78
79
 *   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");
80
 *
81
82
 *   ...
 * }
83
84
85
 *
 *
 * static void
86
87
88
 * foo_bar_activatable_interface_init (GtkActivatableIface  *iface)
 * {
 *   iface->update = foo_bar_activatable_update;
89
 *   iface->sync_action_properties = foo_bar_activatable_sync_action_properties;
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 * }
 * 
 * ... 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);
 * }
 * 
William Jon McCann's avatar
William Jon McCann committed
110
 * ... Handle the “related-action” and “use-action-appearance” properties ...
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
 *
 * 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;
 *       
175
 *       gtk_activatable_sync_action_properties (GTK_ACTIVATABLE (bar), priv->action);
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 *     }
 * }
 * 
 * ... 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 ...
197
198
199
 * static void
 * gtk_button_activatable_sync_action_properties (GtkActivatable       *activatable,
 * 		                                  GtkAction            *action)
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
 * {
 *   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,
229
230
 * 			       GtkAction            *action,
 * 			       const gchar          *property_name)
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 * {
 *   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));
 * 
 *   ...
255
256
 * }
 * ]|
257
258
259
 */

#include "config.h"
260

261
#define GDK_DISABLE_DEPRECATION_WARNINGS
262

263
264
265
266
267
268
#include "gtkactivatable.h"
#include "gtkactiongroup.h"
#include "gtkprivate.h"
#include "gtkintl.h"


269
270
typedef GtkActivatableIface GtkActivatableInterface;
G_DEFINE_INTERFACE (GtkActivatable, gtk_activatable, G_TYPE_OBJECT)
271
272

static void
273
gtk_activatable_default_init (GtkActivatableInterface *iface)
274
275
276
{
  /**
   * GtkActivatable:related-action:
277
   *
278
279
280
   * The action that this activatable will activate and receive
   * updates from for various states and possibly appearance.
   *
281
282
   * > #GtkActivatable implementors need to handle the this property and
   * > call gtk_activatable_do_set_related_action() when it changes.
283
284
   *
   * Since: 2.16
285
286
   *
   * Deprecated: 3.10
287
   */
288
  g_object_interface_install_property (iface,
289
290
291
292
293
294
295
296
				       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:
297
   *
298
299
300
301
302
303
304
   * 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.
   *
305
306
307
   * > #GtkActivatable implementors need to handle this property
   * > and call gtk_activatable_sync_action_properties() on the activatable
   * > widget when it changes.
308
309
   *
   * Since: 2.16
310
311
   *
   * Deprecated: 3.10
312
   */
313
  g_object_interface_install_property (iface,
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
				       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)));
}

/**
341
 * gtk_activatable_sync_action_properties:
342
 * @activatable: a #GtkActivatable
Johan Dahlin's avatar
Johan Dahlin committed
343
 * @action: (allow-none): the related #GtkAction or %NULL
344
 *
345
 * This is called to update the activatable completely, this is called
346
 * internally when the #GtkActivatable:related-action property is set
347
 * or unset and by the implementing class when
348
 * #GtkActivatable:use-action-appearance changes.
349
350
 *
 * Since: 2.16
351
352
 *
 * Deprecated: 3.10
353
354
 **/
void
355
356
gtk_activatable_sync_action_properties (GtkActivatable *activatable,
		                        GtkAction      *action)
357
358
359
360
361
362
{
  GtkActivatableIface *iface;

  g_return_if_fail (GTK_IS_ACTIVATABLE (activatable));

  iface = GTK_ACTIVATABLE_GET_IFACE (activatable);
363
364
  if (iface->sync_action_properties)
    iface->sync_action_properties (activatable, action);
365
  else
366
    g_critical ("GtkActivatable->sync_action_properties() unimplemented for type %s", 
367
368
369
370
371
372
373
374
375
376
377
		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.
 *
378
379
 * > #GtkActivatable implementors need to handle the #GtkActivatable:related-action
 * > property and call gtk_activatable_do_set_related_action() when it changes.
380
381
 *
 * Since: 2.16
382
383
 *
 * Deprecated: 3.10
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
 **/
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
417
 * and registers to the action’s proxy list.
418
 *
419
420
421
422
 * > Be careful to call this before setting the local
 * > copy of the #GtkAction property, since this function uses 
 * > gtk_activatable_get_related_action() to retrieve the
 * > previous action.
Matthias Clasen's avatar
Matthias Clasen committed
423
424
 *
 * Since: 2.16
425
426
 *
 * Deprecated: 3.10
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
 */
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);
	  
442
443
444
          /* Check the type so that actions can be activatable too. */
          if (GTK_IS_WIDGET (activatable))
            _gtk_action_remove_from_proxy_list (prev_action, GTK_WIDGET (activatable));
445
446
447
448
	  
          /* Some apps are using the object data directly...
           * so continue to set it for a bit longer
           */
Benjamin Otte's avatar
Benjamin Otte committed
449
          g_object_set_data (G_OBJECT (activatable), "gtk-action", NULL);
450
451
452

          /*
           * We don't want prev_action to be activated
453
           * during the sync_action_properties() call when syncing "active".
454
455
           */ 
          gtk_action_block_activate (prev_action);
456
457
458
459
	}
      
      /* Some applications rely on their proxy UI to be set up
       * before they receive the ::connect-proxy signal, so we
460
       * need to call sync_action_properties() before add_to_proxy_list().
461
       */
462
      gtk_activatable_sync_action_properties (activatable, action);
463

464
465
466
467
468
469
      if (prev_action)
        {
          gtk_action_unblock_activate (prev_action);
	  g_object_unref (prev_action);
        }

470
471
472
      if (action)
	{
	  g_object_ref (action);
473

474
	  g_signal_connect (G_OBJECT (action), "notify", G_CALLBACK (gtk_activatable_action_notify), activatable);
475

476
477
          if (GTK_IS_WIDGET (activatable))
            _gtk_action_add_to_proxy_list (action, GTK_WIDGET (activatable));
478

Benjamin Otte's avatar
Benjamin Otte committed
479
          g_object_set_data (G_OBJECT (activatable), "gtk-action", action);
480
481
482
483
484
485
486
487
488
489
	}
    }
}

/**
 * gtk_activatable_get_related_action:
 * @activatable: a #GtkActivatable
 *
 * Gets the related #GtkAction for @activatable.
 *
Matthias Clasen's avatar
Matthias Clasen committed
490
 * Returns: (transfer none): the related #GtkAction if one is set.
491
492
 *
 * Since: 2.16
493
494
 *
 * Deprecated: 3.10
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
 **/
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
 *
517
518
 * Sets whether this activatable should reset its layout and appearance
 * when setting the related action or when the action changes appearance
519
 *
520
521
522
523
 * > #GtkActivatable implementors need to handle the
 * > #GtkActivatable:use-action-appearance property and call
 * > gtk_activatable_sync_action_properties() to update @activatable
 * > if needed.
524
525
 *
 * Since: 2.16
526
527
528
  *
 * Deprecated: 3.10
**/
529
void
530
531
gtk_activatable_set_use_action_appearance (GtkActivatable *activatable,
					   gboolean        use_appearance)
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
{
  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
547
548
549
  *
 * Deprecated: 3.10
**/
550
551
552
553
554
555
556
557
558
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;
}