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_INTERFACE (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_default_init (GActionGroupInterface *class)
  66 {
  67   /**
  68    * GActionGroup::action-added:
  69    * @action_group: the #GActionGroup that changed
  70    * @action_name: the name of the action in @action_group
  71    *
  72    * Signals that a new action was just added to the group.  This signal
  73    * is emitted after the action has been added and is now visible.
  74    *
  75    * Since: 2.26
  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.26
  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.26
 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                   _gio_marshal_VOID__STRING_BOOLEAN,
 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.26
 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 | G_SIGNAL_DETAILED,
 145                   G_STRUCT_OFFSET (GActionGroupInterface,
 146                                    action_state_changed),
 147                   NULL, NULL,
 148                   _gio_marshal_VOID__STRING_VARIANT,
 149                   G_TYPE_NONE, 2,
 150                   G_TYPE_STRING,
 151                   G_TYPE_VARIANT);
 152 }
 153
 154 /**
 155  * g_action_group_list_actions:
 156  * @action_group: a #GActionGroup
 157  *
 158  * Lists the actions contained within @action_group.
 159  *
 160  * The caller is responsible for freeing the list with g_strfreev() when
 161  * it is no longer required.
 162  *
 163  * Returns: (transfer full): a %NULL-terminated array of the names of the
 164  * actions in the groupb
 165  *
 166  * Since: 2.26
 167  **/
 168 gchar **
 169 g_action_group_list_actions (GActionGroup *action_group)
 170 {
 171   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 172
 173   return G_ACTION_GROUP_GET_IFACE (action_group)
 174     ->list_actions (action_group);
 175 }
 176
 177 /**
 178  * g_action_group_has_action:
 179  * @action_group: a #GActionGroup
 180  * @action_name: the name of the action to check for
 181  *
 182  * Checks if the named action exists within @action_group.
 183  *
 184  * Returns: whether the named action exists
 185  *
 186  * Since: 2.26
 187  **/
 188 gboolean
 189 g_action_group_has_action (GActionGroup *action_group,
 190                            const gchar  *action_name)
 191 {
 192   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 193
 194   return G_ACTION_GROUP_GET_IFACE (action_group)
 195     ->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_IFACE (action_group)
 228     ->get_parameter_type (action_group, action_name);
 229 }
 230
 231 /**
 232  * g_action_group_get_state_type:
 233  * @action_group: a #GActionGroup
 234  * @action_name: the name of the action to query
 235  *
 236  * Queries the type of the state of the named action within
 237  * @action_group.
 238  *
 239  * If the action is stateful then this function returns the
 240  * #GVariantType of the state.  All calls to g_action_group_set_state()
 241  * must give a #GVariant of this type and g_action_group_get_state()
 242  * will return a #GVariant of the same type.
 243  *
 244  * If the action is not stateful then this function will return %NULL.
 245  * In that case, g_action_group_get_state() will return %NULL and you
 246  * must not call g_action_group_set_state().
 247  *
 248  * The state type of a particular action will never change but it is
 249  * possible for an action to be removed and for a new action to be added
 250  * with the same name but a different state type.
 251  *
 252  * Returns: (transfer full): the state type, if the action is stateful
 253  *
 254  * Since: 2.26
 255  **/
 256 const GVariantType *
 257 g_action_group_get_state_type (GActionGroup *action_group,
 258                                const gchar  *action_name)
 259 {
 260   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 261
 262   return G_ACTION_GROUP_GET_IFACE (action_group)
 263     ->get_state_type (action_group, action_name);
 264 }
 265
 266 /**
 267  * g_action_group_get_state_hint:
 268  * @action_group: a #GActionGroup
 269  * @action_name: the name of the action to query
 270  *
 271  * Requests a hint about the valid range of values for the state of the
 272  * named action within @action_group.
 273  *
 274  * If %NULL is returned it either means that the action is not stateful
 275  * or that there is no hint about the valid range of values for the
 276  * state of the action.
 277  *
 278  * If a #GVariant array is returned then each item in the array is a
 279  * possible value for the state.  If a #GVariant pair (ie: two-tuple) is
 280  * returned then the tuple specifies the inclusive lower and upper bound
 281  * of valid values for the state.
 282  *
 283  * In any case, the information is merely a hint.  It may be possible to
 284  * have a state value outside of the hinted range and setting a value
 285  * within the range may fail.
 286  *
 287  * The return value (if non-%NULL) should be freed with
 288  * g_variant_unref() when it is no longer required.
 289  *
 290  * Return value: (transfer full): the state range hint
 291  *
 292  * Since: 2.26
 293  **/
 294 GVariant *
 295 g_action_group_get_state_hint (GActionGroup *action_group,
 296                                const gchar  *action_name)
 297 {
 298   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 299
 300   return G_ACTION_GROUP_GET_IFACE (action_group)
 301     ->get_state_hint (action_group, action_name);
 302 }
 303
 304 /**
 305  * g_action_group_get_enabled:
 306  * @action_group: a #GActionGroup
 307  * @action_name: the name of the action to query
 308  *
 309  * Checks if the named action within @action_group is currently enabled.
 310  *
 311  * An action must be enabled in order to be activated or in order to
 312  * have its state changed from outside callers.
 313  *
 314  * Return value: whether or not the action is currently enabled
 315  *
 316  * Since: 2.26
 317  **/
 318 gboolean
 319 g_action_group_get_enabled (GActionGroup *action_group,
 320                             const gchar  *action_name)
 321 {
 322   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), FALSE);
 323
 324   return G_ACTION_GROUP_GET_IFACE (action_group)
 325     ->get_enabled (action_group, action_name);
 326 }
 327
 328 /**
 329  * g_action_group_get_state:
 330  * @action_group: a #GActionGroup
 331  * @action_name: the name of the action to query
 332  *
 333  * Queries the current state of the named action within @action_group.
 334  *
 335  * If the action is not stateful then %NULL will be returned.  If the
 336  * action is stateful then the type of the return value is the type
 337  * given by g_action_group_get_state_type().
 338  *
 339  * The return value (if non-%NULL) should be freed with
 340  * g_variant_unref() when it is no longer required.
 341  *
 342  * Return value: (allow-none): the current state of the action
 343  *
 344  * Since: 2.26
 345  **/
 346 GVariant *
 347 g_action_group_get_state (GActionGroup *action_group,
 348                           const gchar  *action_name)
 349 {
 350   g_return_val_if_fail (G_IS_ACTION_GROUP (action_group), NULL);
 351
 352   return G_ACTION_GROUP_GET_IFACE (action_group)
 353     ->get_state (action_group, action_name);
 354 }
 355
 356 /**
 357  * g_action_group_set_state:
 358  * @action_group: a #GActionGroup
 359  * @action_name: the name of the action to request the change on
 360  * @value: the new state
 361  *
 362  * Request for the state of the named action within @action_group to be
 363  * changed to @value.
 364  *
 365  * The action must be stateful and @value must be of the correct type.
 366  * See g_action_group_get_state_type().
 367  *
 368  * This call merely requests a change.  The action may refuse to change
 369  * its state or may change its state to something other than @value.
 370  * See g_action_group_get_state_hint().
 371  *
 372  * If the @value GVariant is floating, it is consumed.
 373  *
 374  * Since: 2.26
 375  **/
 376 void
 377 g_action_group_set_state (GActionGroup *action_group,
 378                           const gchar  *action_name,
 379                           GVariant     *value)
 380 {
 381   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 382   g_return_if_fail (action_name != NULL);
 383   g_return_if_fail (value != NULL);
 384
 385   G_ACTION_GROUP_GET_IFACE (action_group)
 386     ->set_state (action_group, action_name, value);
 387 }
 388
 389 /**
 390  * g_action_group_activate:
 391  * @action_group: a #GActionGroup
 392  * @action_name: the name of the action to activate
 393  * @parameter: (allow-none): parameters to the activation
 394  *
 395  * Activate the named action within @action_group.
 396  *
 397  * If the action is expecting a parameter, then the correct type of
 398  * parameter must be given as @parameter.  If the action is expecting no
 399  * parameters then @parameter must be %NULL.  See
 400  * g_action_group_get_parameter_type().
 401  *
 402  * Since: 2.26
 403  **/
 404 void
 405 g_action_group_activate (GActionGroup *action_group,
 406                          const gchar  *action_name,
 407                          GVariant     *parameter)
 408 {
 409   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 410   g_return_if_fail (action_name != NULL);
 411
 412   G_ACTION_GROUP_GET_IFACE (action_group)
 413     ->activate (action_group, action_name, parameter);
 414 }
 415
 416 /**
 417  * g_action_group_action_added:
 418  * @action_group: a #GActionGroup
 419  * @action_name: the name of an action in the group
 420  *
 421  * Emits the #GActionGroup::action-added signal on @action_group.
 422  *
 423  * This function should only be called by #GActionGroup implementations.
 424  *
 425  * Since: 2.26
 426  **/
 427 void
 428 g_action_group_action_added (GActionGroup *action_group,
 429                              const gchar  *action_name)
 430 {
 431   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 432   g_return_if_fail (action_name != NULL);
 433
 434   g_signal_emit (action_group,
 435                  g_action_group_signals[SIGNAL_ACTION_ADDED],
 436                  g_quark_try_string (action_name),
 437                  action_name);
 438 }
 439
 440 /**
 441  * g_action_group_action_removed:
 442  * @action_group: a #GActionGroup
 443  * @action_name: the name of an action in the group
 444  *
 445  * Emits the #GActionGroup::action-removed signal on @action_group.
 446  *
 447  * This function should only be called by #GActionGroup implementations.
 448  *
 449  * Since: 2.26
 450  **/
 451 void
 452 g_action_group_action_removed (GActionGroup *action_group,
 453                                const gchar  *action_name)
 454 {
 455   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 456   g_return_if_fail (action_name != NULL);
 457
 458   g_signal_emit (action_group,
 459                  g_action_group_signals[SIGNAL_ACTION_REMOVED],
 460                  g_quark_try_string (action_name),
 461                  action_name);
 462 }
 463
 464 /**
 465  * g_action_group_action_enabled_changed:
 466  * @action_group: a #GActionGroup
 467  * @action_name: the name of an action in the group
 468  * @enabled: whether or not the action is now enabled
 469  *
 470  * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
 471  *
 472  * This function should only be called by #GActionGroup implementations.
 473  *
 474  * Since: 2.26
 475  **/
 476 void
 477 g_action_group_action_enabled_changed (GActionGroup *action_group,
 478                                        const gchar  *action_name,
 479                                        gboolean      enabled)
 480 {
 481   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 482   g_return_if_fail (action_name != NULL);
 483
 484   enabled = !!enabled;
 485
 486   g_signal_emit (action_group,
 487                  g_action_group_signals[SIGNAL_ACTION_ENABLED_CHANGED],
 488                  g_quark_try_string (action_name),
 489                  action_name,
 490                  enabled);
 491 }
 492
 493 /**
 494  * g_action_group_action_state_changed:
 495  * @action_group: a #GActionGroup
 496  * @action_name: the name of an action in the group
 497  * @state: the new state of the named action
 498  *
 499  * Emits the #GActionGroup::action-state-changed signal on @action_group.
 500  *
 501  * This function should only be called by #GActionGroup implementations.
 502  *
 503  * Since: 2.26
 504  **/
 505 void
 506 g_action_group_action_state_changed (GActionGroup *action_group,
 507                                      const gchar  *action_name,
 508                                      GVariant     *state)
 509 {
 510   g_return_if_fail (G_IS_ACTION_GROUP (action_group));
 511   g_return_if_fail (action_name != NULL);
 512
 513   g_signal_emit (action_group,
 514                  g_action_group_signals[SIGNAL_ACTION_STATE_CHANGED],
 515                  g_quark_try_string (action_name),
 516                  action_name,
 517                  state);
 518 }