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