gio/gactiongroup.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation; either version 2 of the licence or (at
   7  * your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23 #include "gactiongroup.h"
  24 #include "gaction.h"
  25 #include "glibintl.h"
  26
  27 /**
  28  * SECTION:gactiongroup
  29  * @title: GActionGroup
  30  * @short_description: A group of actions
  31  *
  32  * #GActionGroup represents a group of actions.
  33  *
  34  * Each action in the group has a unique name (which is a string).  All
  35  * method calls, except g_action_group_list_actions() take the name of
  36  * an action as an argument.
  37  *
  38  * The #GActionGroup API is meant to be the 'public' API to the action
  39  * group.  The calls here are exactly the interaction that 'external
  40  * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
  41  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
  42  * the action group implementation) are found on subclasses.  This is
  43  * why you will find -- for example -- g_action_group_get_action_enabled()
  44  * but not an equivalent <function>set()</function> call.
  45  *
  46  * Signals are emitted on the action group in response to state changes
  47  * on individual actions.
  48  **/
  49
  50 G_DEFINE_INTERFACE (GActionGroup, g_action_group, G_TYPE_OBJECT)
  51
  52 enum
  53 {
  54   SIGNAL_ACTION_ADDED,
  55   SIGNAL_ACTION_REMOVED,
  56   SIGNAL_ACTION_ENABLED_CHANGED,
  57   SIGNAL_ACTION_STATE_CHANGED,
  58   NR_SIGNALS
  59 };
  60
  61 static guint g_action_group_signals[NR_SIGNALS];
  62
  63 static void
  64 g_action_group_default_init (GActionGroupInterface *class)
  65 {
  66   /**
  67    * GActionGroup::action-added:
  68    * @action_group: the #GActionGroup that changed
  69    * @action_name: the name of the action in @action_group
  70    *
  71    * Signals that a new action was just added to the group.
  72    * This signal is emitted after the action has been added
  73    * and is now visible.
  74    *
  75    * Since: 2.28
  76    **/
  77   g_action_group_signals[SIGNAL_ACTION_ADDED] =
  78     g_signal_new (I_("action-added"),
  79                   G_TYPE_ACTION_GROUP,
  80                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
  81                   G_STRUCT_OFFSET (GActionGroupInterface, action_added),
  82                   NULL, NULL,
  83                   g_cclosure_marshal_VOID__STRING,
  84                   G_TYPE_NONE, 1,
  85                   G_TYPE_STRING);
  86
  87   /**
  88    * GActionGroup::action-removed:
  89    * @action_group: the #GActionGroup that changed
  90    * @action_name: the name of the action in @action_group
  91    *
  92    * Signals that an action is just about to be removed from the group.
  93    * This signal is emitted before the action is removed, so the action
  94    * is still visible and can be queried from the signal handler.
  95    *
  96    * Since: 2.28
  97    **/
  98   g_action_group_signals[SIGNAL_ACTION_REMOVED] =
  99     g_signal_new (I_("action-removed"),
 100                   G_TYPE_ACTION_GROUP,
 101                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 102                   G_STRUCT_OFFSET (GActionGroupInterface, action_removed),
 103                   NULL, NULL,
 104                   g_cclosure_marshal_VOID__STRING,
 105                   G_TYPE_NONE, 1,
 106                   G_TYPE_STRING);
 107
 108
 109   /**
 110    * GActionGroup::action-enabled-changed:
 111    * @action_group: the #GActionGroup that changed
 112    * @action_name: the name of the action in @action_group
 113    * @enabled: whether the action is enabled or not
 114    *
 115    * Signals that the enabled status of the named action has changed.
 116    *
 117    * Since: 2.28
 118    **/
 119   g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED] =
 120     g_signal_new (I_("action-enabled-changed"),
 121                   G_TYPE_ACTION_GROUP,
 122                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 123                   G_STRUCT_OFFSET (GActionGroupInterface,
 124                                    action_enabled_changed),
 125                   NULL, NULL,
 126                   NULL,
 127                   G_TYPE_NONE, 2,
 128                   G_TYPE_STRING,
 129                   G_TYPE_BOOLEAN);
 130
 131   /**
 132    * GActionGroup::action-state-changed:
 133    * @action_group: the #GActionGroup that changed
 134    * @action_name: the name of the action in @action_group
 135    * @value: the new value of the state
 136    *
 137    * Signals that the state of the named action has changed.
 138    *
 139    * Since: 2.28
 140    **/
 141   g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED] =
 142     g_signal_new (I_("action-state-changed"),
 143                   G_TYPE_ACTION_GROUP,
 144                   G_SIGNAL_RUN_LAST |
 145                   G_SIGNAL_DETAILED |
 146                   G_SIGNAL_MUST_COLLECT,
 147                   G_STRUCT_OFFSET (GActionGroupInterface,
 148                                    action_state_changed),
 149                   NULL, NULL,
 150                   NULL,
 151                   G_TYPE_NONE, 2,
 152                   G_TYPE_STRING,
 153                   G_TYPE_VARIANT);
 154 }
 155
 156 /**
 157  * g_action_group_list_actions:
 158  * @action_group: a #GActionGroup
 159  *
 160  * Lists the actions contained within @action_group.
 161  *
 162  * The caller is responsible for freeing the list with g_strfreev() when
 163  * it is no longer required.
 164  *
 165  * Returns: (transfer full): a %NULL-terminated array of the names of the
 166  * actions in the groupb
 167  *
 168  * Since: 2.28
 169  **/
 170 gchar **
 171 g_action_group_list_actions (GActionGroup *action_group)
 172 {
 173   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 174
 175   return G_ACTION_GROUP_GET_IFACE (action_group)
 176     ->list_actions (action_group);
 177 }
 178
 179 /**
 180  * g_action_group_has_action:
 181  * @action_group: a #GActionGroup
 182  * @action_name: the name of the action to check for
 183  *
 184  * Checks if the named action exists within @action_group.
 185  *
 186  * Returns: whether the named action exists
 187  *
 188  * Since: 2.28
 189  **/
 190 gboolean
 191 g_action_group_has_action (GActionGroup *action_group,
 192                            const gchar  *action_name)
 193 {
 194   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 195
 196   return G_ACTION_GROUP_GET_IFACE (action_group)
 197     ->has_action (action_group, action_name);
 198 }
 199
 200 /**
 201  * g_action_group_get_action_parameter_type:
 202  * @action_group: a #GActionGroup
 203  * @action_name: the name of the action to query
 204  *
 205  * Queries the type of the parameter that must be given when activating
 206  * the named action within @action_group.
 207  *
 208  * When activating the action using g_action_group_activate_action(),
 209  * the #GVariant given to that function must be of the type returned
 210  * by this function.
 211  *
 212  * In the case that this function returns %NULL, you must not give any
 213  * #GVariant, but %NULL instead.
 214  *
 215  * The parameter type of a particular action will never change but it is
 216  * possible for an action to be removed and for a new action to be added
 217  * with the same name but a different parameter type.
 218  *
 219  * Return value: the parameter type
 220  *
 221  * Since: 2.28
 222  **/
 223 const GVariantType *
 224 g_action_group_get_action_parameter_type (GActionGroup *action_group,
 225                                           const gchar  *action_name)
 226 {
 227   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 228
 229   return G_ACTION_GROUP_GET_IFACE (action_group)
 230     ->get_action_parameter_type (action_group, action_name);
 231 }
 232
 233 /**
 234  * g_action_group_get_action_state_type:
 235  * @action_group: a #GActionGroup
 236  * @action_name: the name of the action to query
 237  *
 238  * Queries the type of the state of the named action within
 239  * @action_group.
 240  *
 241  * If the action is stateful then this function returns the
 242  * #GVariantType of the state.  All calls to
 243  * g_action_group_change_action_state() must give a #GVariant of this
 244  * type and g_action_group_get_action_state() will return a #GVariant
 245  * of the same type.
 246  *
 247  * If the action is not stateful then this function will return %NULL.
 248  * In that case, g_action_group_get_action_state() will return %NULL
 249  * and you must not call g_action_group_change_action_state().
 250  *
 251  * The state type of a particular action will never change but it is
 252  * possible for an action to be removed and for a new action to be added
 253  * with the same name but a different state type.
 254  *
 255  * Returns: (transfer full): the state type, if the action is stateful
 256  *
 257  * Since: 2.28
 258  **/
 259 const GVariantType *
 260 g_action_group_get_action_state_type (GActionGroup *action_group,
 261                                       const gchar  *action_name)
 262 {
 263   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 264
 265   return G_ACTION_GROUP_GET_IFACE (action_group)
 266     ->get_action_state_type (action_group, action_name);
 267 }
 268
 269 /**
 270  * g_action_group_get_action_state_hint:
 271  * @action_group: a #GActionGroup
 272  * @action_name: the name of the action to query
 273  *
 274  * Requests a hint about the valid range of values for the state of the
 275  * named action within @action_group.
 276  *
 277  * If %NULL is returned it either means that the action is not stateful
 278  * or that there is no hint about the valid range of values for the
 279  * state of the action.
 280  *
 281  * If a #GVariant array is returned then each item in the array is a
 282  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 283  * returned then the tuple specifies the inclusive lower and upper bound
 284  * of valid values for the state.
 285  *
 286  * In any case, the information is merely a hint.  It may be possible to
 287  * have a state value outside of the hinted range and setting a value
 288  * within the range may fail.
 289  *
 290  * The return value (if non-%NULL) should be freed with
 291  * g_variant_unref() when it is no longer required.
 292  *
 293  * Return value: (transfer full): the state range hint
 294  *
 295  * Since: 2.28
 296  **/
 297 GVariant *
 298 g_action_group_get_action_state_hint (GActionGroup *action_group,
 299                                       const gchar  *action_name)
 300 {
 301   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 302
 303   return G_ACTION_GROUP_GET_IFACE (action_group)
 304     ->get_action_state_hint (action_group, action_name);
 305 }
 306
 307 /**
 308  * g_action_group_get_action_enabled:
 309  * @action_group: a #GActionGroup
 310  * @action_name: the name of the action to query
 311  *
 312  * Checks if the named action within @action_group is currently enabled.
 313  *
 314  * An action must be enabled in order to be activated or in order to
 315  * have its state changed from outside callers.
 316  *
 317  * Return value: whether or not the action is currently enabled
 318  *
 319  * Since: 2.28
 320  **/
 321 gboolean
 322 g_action_group_get_action_enabled (GActionGroup *action_group,
 323                                    const gchar  *action_name)
 324 {
 325   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 326
 327   return G_ACTION_GROUP_GET_IFACE (action_group)
 328     ->get_action_enabled (action_group, action_name);
 329 }
 330
 331 /**
 332  * g_action_group_get_action_state:
 333  * @action_group: a #GActionGroup
 334  * @action_name: the name of the action to query
 335  *
 336  * Queries the current state of the named action within @action_group.
 337  *
 338  * If the action is not stateful then %NULL will be returned.  If the
 339  * action is stateful then the type of the return value is the type
 340  * given by g_action_group_get_action_state_type().
 341  *
 342  * The return value (if non-%NULL) should be freed with
 343  * g_variant_unref() when it is no longer required.
 344  *
 345  * Return value: (allow-none): the current state of the action
 346  *
 347  * Since: 2.28
 348  **/
 349 GVariant *
 350 g_action_group_get_action_state (GActionGroup *action_group,
 351                                  const gchar  *action_name)
 352 {
 353   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 354
 355   return G_ACTION_GROUP_GET_IFACE (action_group)
 356     ->get_action_state (action_group, action_name);
 357 }
 358
 359 /**
 360  * g_action_group_change_action_state:
 361  * @action_group: a #GActionGroup
 362  * @action_name: the name of the action to request the change on
 363  * @value: the new state
 364  *
 365  * Request for the state of the named action within @action_group to be
 366  * changed to @value.
 367  *
 368  * The action must be stateful and @value must be of the correct type.
 369  * See g_action_group_get_action_state_type().
 370  *
 371  * This call merely requests a change.  The action may refuse to change
 372  * its state or may change its state to something other than @value.
 373  * See g_action_group_get_action_state_hint().
 374  *
 375  * If the @value GVariant is floating, it is consumed.
 376  *
 377  * Since: 2.28
 378  **/
 379 void
 380 g_action_group_change_action_state (GActionGroup *action_group,
 381                                     const gchar  *action_name,
 382                                     GVariant     *value)
 383 {
 384   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 385   g_return_if_fail (action_name != NULL);
 386   g_return_if_fail (value != NULL);
 387
 388   G_ACTION_GROUP_GET_IFACE (action_group)
 389     ->change_action_state (action_group, action_name, value);
 390 }
 391
 392 /**
 393  * g_action_group_activate_action:
 394  * @action_group: a #GActionGroup
 395  * @action_name: the name of the action to activate
 396  * @parameter: (allow-none): parameters to the activation
 397  *
 398  * Activate the named action within @action_group.
 399  *
 400  * If the action is expecting a parameter, then the correct type of
 401  * parameter must be given as @parameter.  If the action is expecting no
 402  * parameters then @parameter must be %NULL.  See
 403  * g_action_group_get_action_parameter_type().
 404  *
 405  * Since: 2.28
 406  **/
 407 void
 408 g_action_group_activate_action (GActionGroup *action_group,
 409                                 const gchar  *action_name,
 410                                 GVariant     *parameter)
 411 {
 412   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 413   g_return_if_fail (action_name != NULL);
 414
 415   G_ACTION_GROUP_GET_IFACE (action_group)
 416     ->activate_action (action_group, action_name, parameter);
 417 }
 418
 419 /**
 420  * g_action_group_action_added:
 421  * @action_group: a #GActionGroup
 422  * @action_name: the name of an action in the group
 423  *
 424  * Emits the #GActionGroup::action-added signal on @action_group.
 425  *
 426  * This function should only be called by #GActionGroup implementations.
 427  *
 428  * Since: 2.28
 429  **/
 430 void
 431 g_action_group_action_added (GActionGroup *action_group,
 432                              const gchar  *action_name)
 433 {
 434   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 435   g_return_if_fail (action_name != NULL);
 436
 437   g_signal_emit (action_group,
 438                  g_action_group_signals[SIGNAL_ACTION_ADDED],
 439                  g_quark_try_string (action_name),
 440                  action_name);
 441 }
 442
 443 /**
 444  * g_action_group_action_removed:
 445  * @action_group: a #GActionGroup
 446  * @action_name: the name of an action in the group
 447  *
 448  * Emits the #GActionGroup::action-removed signal on @action_group.
 449  *
 450  * This function should only be called by #GActionGroup implementations.
 451  *
 452  * Since: 2.28
 453  **/
 454 void
 455 g_action_group_action_removed (GActionGroup *action_group,
 456                                const gchar  *action_name)
 457 {
 458   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 459   g_return_if_fail (action_name != NULL);
 460
 461   g_signal_emit (action_group,
 462                  g_action_group_signals[SIGNAL_ACTION_REMOVED],
 463                  g_quark_try_string (action_name),
 464                  action_name);
 465 }
 466
 467 /**
 468  * g_action_group_action_enabled_changed:
 469  * @action_group: a #GActionGroup
 470  * @action_name: the name of an action in the group
 471  * @enabled: whether or not the action is now enabled
 472  *
 473  * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
 474  *
 475  * This function should only be called by #GActionGroup implementations.
 476  *
 477  * Since: 2.28
 478  **/
 479 void
 480 g_action_group_action_enabled_changed (GActionGroup *action_group,
 481                                        const gchar  *action_name,
 482                                        gboolean      enabled)
 483 {
 484   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 485   g_return_if_fail (action_name != NULL);
 486
 487   enabled = !!enabled;
 488
 489   g_signal_emit (action_group,
 490                  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
 491                  g_quark_try_string (action_name),
 492                  action_name,
 493                  enabled);
 494 }
 495
 496 /**
 497  * g_action_group_action_state_changed:
 498  * @action_group: a #GActionGroup
 499  * @action_name: the name of an action in the group
 500  * @state: the new state of the named action
 501  *
 502  * Emits the #GActionGroup::action-state-changed signal on @action_group.
 503  *
 504  * This function should only be called by #GActionGroup implementations.
 505  *
 506  * Since: 2.28
 507  **/
 508 void
 509 g_action_group_action_state_changed (GActionGroup *action_group,
 510                                      const gchar  *action_name,
 511                                      GVariant     *state)
 512 {
 513   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 514   g_return_if_fail (action_name != NULL);
 515
 516   g_signal_emit (action_group,
 517                  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
 518                  g_quark_try_string (action_name),
 519                  action_name,
 520                  state);
 521 }