gio/gpropertyaction.c

   1 /*
   2  * Copyright © 2013 Canonical 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, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors: Ryan Lortie <desrt@desrt.ca>
  18  */
  19
  20 #include "config.h"
  21
  22 #include "gpropertyaction.h"
  23
  24 #include "gsettings-mapping.h"
  25 #include "gaction.h"
  26 #include "glibintl.h"
  27
  28 /**
  29  * SECTION:gpropertyaction
  30  * @title: GPropertyAction
  31  * @short_description: A GAction reflecting a GObject property
  32  * @include: gio/gio.h
  33  *
  34  * A #GPropertyAction is a way to get a #GAction with a state value
  35  * reflecting and controlling the value of a #GObject property.
  36  *
  37  * The state of the action will correspond to the value of the property.
  38  * Changing it will change the property (assuming the requested value
  39  * matches the requirements as specified in the #GParamSpec).
  40  *
  41  * Only the most common types are presently supported.  Booleans are
  42  * mapped to booleans, strings to strings, signed/unsigned integers to
  43  * int32/uint32 and floats and doubles to doubles.
  44  *
  45  * If the property is an enum then the state will be string-typed and
  46  * conversion will automatically be performed between the enum value and
  47  * "nick" string as per the #GEnumValue table.
  48  *
  49  * Flags types are not currently supported.
  50  *
  51  * Properties of object types, boxed types and pointer types are not
  52  * supported and probably never will be.
  53  *
  54  * Properties of #GVariant types are not currently supported.
  55  *
  56  * If the property is boolean-valued then the action will have a NULL
  57  * parameter type, and activating the action (with no parameter) will
  58  * toggle the value of the property.
  59  *
  60  * In all other cases, the parameter type will correspond to the type of
  61  * the property.
  62  *
  63  * The general idea here is to reduce the number of locations where a
  64  * particular piece of state is kept (and therefore has to be synchronised
  65  * between). #GPropertyAction does not have a separate state that is kept
  66  * in sync with the property value -- its state is the property value.
  67  *
  68  * For example, it might be useful to create a #GAction corresponding to
  69  * the "visible-child-name" property of a #GtkStack so that the current
  70  * page can be switched from a menu.  The active radio indication in the
  71  * menu is then directly determined from the active page of the
  72  * #GtkStack.
  73  *
  74  * An anti-example would be binding the "active-id" property on a
  75  * #GtkComboBox.  This is because the state of the combobox itself is
  76  * probably uninteresting and is actually being used to control
  77  * something else.
  78  *
  79  * Another anti-example would be to bind to the "visible-child-name"
  80  * property of a #GtkStack if this value is actually stored in
  81  * #GSettings.  In that case, the real source of the value is
  82  * #GSettings.  If you want a #GAction to control a setting stored in
  83  * #GSettings, see g_settings_create_action() instead, and possibly
  84  * combine its use with g_settings_bind().
  85  *
  86  * Since: 2.38
  87  **/
  88 struct _GPropertyAction
  89 {
  90   GObject     parent_instance;
  91
  92   gchar              *name;
  93   gpointer            object;
  94   GParamSpec         *pspec;
  95   const GVariantType *state_type;
  96 };
  97
  98 /**
  99  * GPropertyAction:
 100  *
 101  * This type is opaque.
 102  *
 103  * Since: 2.38
 104  **/
 105
 106 typedef GObjectClass GPropertyActionClass;
 107
 108 static void g_property_action_iface_init (GActionInterface *iface);
 109 G_DEFINE_TYPE_WITH_CODE (GPropertyAction, g_property_action, G_TYPE_OBJECT,
 110   G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_property_action_iface_init))
 111
 112 enum
 113 {
 114   PROP_NONE,
 115   PROP_NAME,
 116   PROP_PARAMETER_TYPE,
 117   PROP_ENABLED,
 118   PROP_STATE_TYPE,
 119   PROP_STATE,
 120   PROP_OBJECT,
 121   PROP_PROPERTY_NAME
 122 };
 123
 124 static const gchar *
 125 g_property_action_get_name (GAction *action)
 126 {
 127   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 128
 129   return paction->name;
 130 }
 131
 132 static const GVariantType *
 133 g_property_action_get_parameter_type (GAction *action)
 134 {
 135   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 136
 137   return paction->pspec->value_type == G_TYPE_BOOLEAN ? NULL : paction->state_type;
 138 }
 139
 140 static const GVariantType *
 141 g_property_action_get_state_type (GAction *action)
 142 {
 143   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 144
 145   return paction->state_type;
 146 }
 147
 148 static GVariant *
 149 g_property_action_get_state_hint (GAction *action)
 150 {
 151   return NULL;
 152 }
 153
 154 static gboolean
 155 g_property_action_get_enabled (GAction *action)
 156 {
 157   return TRUE;
 158 }
 159
 160 static void
 161 g_property_action_set_state (GPropertyAction *paction,
 162                              GVariant        *variant)
 163 {
 164   GValue value = G_VALUE_INIT;
 165
 166   g_value_init (&value, paction->pspec->value_type);
 167   g_settings_get_mapping (&value, variant, NULL);
 168   g_object_set_property (paction->object, paction->pspec->name, &value);
 169   g_value_unset (&value);
 170 }
 171
 172 static void
 173 g_property_action_change_state (GAction  *action,
 174                                 GVariant *value)
 175 {
 176   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 177
 178   g_return_if_fail (g_variant_is_of_type (value, paction->state_type));
 179
 180   g_property_action_set_state (paction, value);
 181 }
 182
 183 static GVariant *
 184 g_property_action_get_state (GAction *action)
 185 {
 186   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 187   GValue value = G_VALUE_INIT;
 188   GVariant *result;
 189
 190   g_value_init (&value, paction->pspec->value_type);
 191   g_object_get_property (paction->object, paction->pspec->name, &value);
 192   result = g_settings_set_mapping (&value, paction->state_type, NULL);
 193   g_value_unset (&value);
 194
 195   return g_variant_ref_sink (result);
 196 }
 197
 198 static void
 199 g_property_action_activate (GAction  *action,
 200                             GVariant *parameter)
 201 {
 202   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 203
 204   if (paction->pspec->value_type == G_TYPE_BOOLEAN)
 205     {
 206       gboolean value;
 207
 208       g_return_if_fail (paction->pspec->value_type == G_TYPE_BOOLEAN && parameter == NULL);
 209
 210       g_object_get (paction->object, paction->pspec->name, &value, NULL);
 211       value = !value;
 212       g_object_set (paction->object, paction->pspec->name, value, NULL);
 213     }
 214   else
 215     {
 216       g_return_if_fail (parameter != NULL && g_variant_is_of_type (parameter, paction->state_type));
 217
 218       g_property_action_set_state (paction, parameter);
 219     }
 220 }
 221
 222 static const GVariantType *
 223 g_property_action_determine_type (GParamSpec *pspec)
 224 {
 225   if (G_TYPE_IS_ENUM (pspec->value_type))
 226     return G_VARIANT_TYPE_STRING;
 227
 228   switch (pspec->value_type)
 229     {
 230     case G_TYPE_BOOLEAN:
 231       return G_VARIANT_TYPE_BOOLEAN;
 232
 233     case G_TYPE_INT:
 234       return G_VARIANT_TYPE_INT32;
 235
 236     case G_TYPE_UINT:
 237       return G_VARIANT_TYPE_UINT32;
 238
 239     case G_TYPE_DOUBLE:
 240     case G_TYPE_FLOAT:
 241       return G_VARIANT_TYPE_DOUBLE;
 242
 243     case G_TYPE_STRING:
 244       return G_VARIANT_TYPE_STRING;
 245
 246     default:
 247       g_critical ("Unable to use GPropertyAction with property '%s::%s' of type '%s'",
 248                   g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->value_type));
 249       return NULL;
 250     }
 251 }
 252
 253 static void
 254 g_property_action_notify (GObject    *object,
 255                           GParamSpec *pspec,
 256                           gpointer    user_data)
 257 {
 258   GPropertyAction *paction = user_data;
 259
 260   g_assert (object == paction->object);
 261   g_assert (pspec == paction->pspec);
 262
 263   g_object_notify (G_OBJECT (paction), "state");
 264 }
 265
 266 static void
 267 g_property_action_set_property_name (GPropertyAction *paction,
 268                                      const gchar     *property_name)
 269 {
 270   GParamSpec *pspec;
 271   gchar *detailed;
 272
 273   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (paction->object), property_name);
 274
 275   if (pspec == NULL)
 276     {
 277       g_critical ("Attempted to use non-existent property '%s::%s' for GPropertyAction",
 278                   G_OBJECT_TYPE_NAME (paction->object), property_name);
 279       return;
 280     }
 281
 282   if (~pspec->flags & G_PARAM_READABLE || ~pspec->flags & G_PARAM_WRITABLE || pspec->flags & G_PARAM_CONSTRUCT_ONLY)
 283     {
 284       g_critical ("Property '%s::%s' used with GPropertyAction must be readable, writable, and not construct-only",
 285                   G_OBJECT_TYPE_NAME (paction->object), property_name);
 286       return;
 287     }
 288
 289   paction->pspec = pspec;
 290
 291   detailed = g_strconcat ("notify::", paction->pspec->name, NULL);
 292   paction->state_type = g_property_action_determine_type (paction->pspec);
 293   g_signal_connect (paction->object, detailed, G_CALLBACK (g_property_action_notify), paction);
 294   g_free (detailed);
 295 }
 296
 297 static void
 298 g_property_action_set_property (GObject      *object,
 299                                 guint         prop_id,
 300                                 const GValue *value,
 301                                 GParamSpec   *pspec)
 302 {
 303   GPropertyAction *paction = G_PROPERTY_ACTION (object);
 304
 305   switch (prop_id)
 306     {
 307     case PROP_NAME:
 308       paction->name = g_value_dup_string (value);
 309       break;
 310
 311     case PROP_OBJECT:
 312       paction->object = g_value_dup_object (value);
 313       break;
 314
 315     case PROP_PROPERTY_NAME:
 316       g_property_action_set_property_name (paction, g_value_get_string (value));
 317       break;
 318
 319     default:
 320       g_assert_not_reached ();
 321     }
 322 }
 323
 324 static void
 325 g_property_action_get_property (GObject    *object,
 326                                 guint       prop_id,
 327                                 GValue     *value,
 328                                 GParamSpec *pspec)
 329 {
 330   GAction *action = G_ACTION (object);
 331
 332   switch (prop_id)
 333     {
 334     case PROP_NAME:
 335       g_value_set_string (value, g_property_action_get_name (action));
 336       break;
 337
 338     case PROP_PARAMETER_TYPE:
 339       g_value_set_boxed (value, g_property_action_get_parameter_type (action));
 340       break;
 341
 342     case PROP_ENABLED:
 343       g_value_set_boolean (value, g_property_action_get_enabled (action));
 344       break;
 345
 346     case PROP_STATE_TYPE:
 347       g_value_set_boxed (value, g_property_action_get_state_type (action));
 348       break;
 349
 350     case PROP_STATE:
 351       g_value_take_variant (value, g_property_action_get_state (action));
 352       break;
 353
 354     default:
 355       g_assert_not_reached ();
 356     }
 357 }
 358
 359 static void
 360 g_property_action_finalize (GObject *object)
 361 {
 362   GPropertyAction *paction = G_PROPERTY_ACTION (object);
 363
 364   g_signal_handlers_disconnect_by_func (paction->object, g_property_action_notify, paction);
 365   g_object_unref (paction->object);
 366   g_free (paction->name);
 367
 368   G_OBJECT_CLASS (g_property_action_parent_class)
 369     ->finalize (object);
 370 }
 371
 372 void
 373 g_property_action_init (GPropertyAction *property)
 374 {
 375 }
 376
 377 void
 378 g_property_action_iface_init (GActionInterface *iface)
 379 {
 380   iface->get_name = g_property_action_get_name;
 381   iface->get_parameter_type = g_property_action_get_parameter_type;
 382   iface->get_state_type = g_property_action_get_state_type;
 383   iface->get_state_hint = g_property_action_get_state_hint;
 384   iface->get_enabled = g_property_action_get_enabled;
 385   iface->get_state = g_property_action_get_state;
 386   iface->change_state = g_property_action_change_state;
 387   iface->activate = g_property_action_activate;
 388 }
 389
 390 void
 391 g_property_action_class_init (GPropertyActionClass *class)
 392 {
 393   GObjectClass *object_class = G_OBJECT_CLASS (class);
 394
 395   object_class->set_property = g_property_action_set_property;
 396   object_class->get_property = g_property_action_get_property;
 397   object_class->finalize = g_property_action_finalize;
 398
 399   /**
 400    * GPropertyAction:name:
 401    *
 402    * The name of the action.  This is mostly meaningful for identifying
 403    * the action once it has been added to a #GActionMap.
 404    *
 405    * Since: 2.38
 406    **/
 407   g_object_class_install_property (object_class, PROP_NAME,
 408                                    g_param_spec_string ("name",
 409                                                         P_("Action Name"),
 410                                                         P_("The name used to invoke the action"),
 411                                                         NULL,
 412                                                         G_PARAM_READWRITE |
 413                                                         G_PARAM_CONSTRUCT_ONLY |
 414                                                         G_PARAM_STATIC_STRINGS));
 415
 416   /**
 417    * GPropertyAction:parameter-type:
 418    *
 419    * The type of the parameter that must be given when activating the
 420    * action.
 421    *
 422    * Since: 2.38
 423    **/
 424   g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
 425                                    g_param_spec_boxed ("parameter-type",
 426                                                        P_("Parameter Type"),
 427                                                        P_("The type of GVariant passed to activate()"),
 428                                                        G_TYPE_VARIANT_TYPE,
 429                                                        G_PARAM_READABLE |
 430                                                        G_PARAM_STATIC_STRINGS));
 431
 432   /**
 433    * GPropertyAction:enabled:
 434    *
 435    * If @action is currently enabled.
 436    *
 437    * If the action is disabled then calls to g_action_activate() and
 438    * g_action_change_state() have no effect.
 439    *
 440    * Since: 2.38
 441    **/
 442   g_object_class_install_property (object_class, PROP_ENABLED,
 443                                    g_param_spec_boolean ("enabled",
 444                                                          P_("Enabled"),
 445                                                          P_("If the action can be activated"),
 446                                                          TRUE,
 447                                                          G_PARAM_READABLE |
 448                                                          G_PARAM_STATIC_STRINGS));
 449
 450   /**
 451    * GPropertyAction:state-type:
 452    *
 453    * The #GVariantType of the state that the action has, or %NULL if the
 454    * action is stateless.
 455    *
 456    * Since: 2.38
 457    **/
 458   g_object_class_install_property (object_class, PROP_STATE_TYPE,
 459                                    g_param_spec_boxed ("state-type",
 460                                                        P_("State Type"),
 461                                                        P_("The type of the state kept by the action"),
 462                                                        G_TYPE_VARIANT_TYPE,
 463                                                        G_PARAM_READABLE |
 464                                                        G_PARAM_STATIC_STRINGS));
 465
 466   /**
 467    * GPropertyAction:state:
 468    *
 469    * The state of the action, or %NULL if the action is stateless.
 470    *
 471    * Since: 2.38
 472    **/
 473   g_object_class_install_property (object_class, PROP_STATE,
 474                                    g_param_spec_variant ("state",
 475                                                          P_("State"),
 476                                                          P_("The state the action is in"),
 477                                                          G_VARIANT_TYPE_ANY,
 478                                                          NULL,
 479                                                          G_PARAM_READABLE |
 480                                                          G_PARAM_STATIC_STRINGS));
 481
 482   /**
 483    * GPropertyAction:object:
 484    *
 485    * The object to wrap a property on.
 486    *
 487    * The object must be a non-%NULL #GObject with properties.
 488    *
 489    * Since: 2.38
 490    **/
 491   g_object_class_install_property (object_class, PROP_OBJECT,
 492                                    g_param_spec_object ("object",
 493                                                         P_("Object"),
 494                                                         P_("The object with the property to wrap"),
 495                                                         G_TYPE_OBJECT,
 496                                                         G_PARAM_WRITABLE |
 497                                                         G_PARAM_CONSTRUCT_ONLY |
 498                                                         G_PARAM_STATIC_STRINGS));
 499
 500   /**
 501    * GPropertyAction:property-name:
 502    *
 503    * The name of the property to wrap on the object.
 504    *
 505    * The property must exist on the passed-in object and it must be
 506    * readable and writable (and not construct-only).
 507    *
 508    * Since: 2.38
 509    **/
 510   g_object_class_install_property (object_class, PROP_PROPERTY_NAME,
 511                                    g_param_spec_string ("property-name",
 512                                                         P_("Property name"),
 513                                                         P_("The name of the property to wrap"),
 514                                                         NULL,
 515                                                         G_PARAM_WRITABLE |
 516                                                         G_PARAM_CONSTRUCT_ONLY |
 517                                                         G_PARAM_STATIC_STRINGS));
 518 }
 519
 520 /**
 521  * g_property_action_new:
 522  * @name: the name of the action to create
 523  * @object: the object that has the property to wrap
 524  * @property_name: the name of the property
 525  *
 526  * Creates a #GAction corresponding to the value of property
 527  * @property_name on @object.
 528  *
 529  * The property must be existent and readable and writable (and not
 530  * construct-only).
 531  *
 532  * This function takes a reference on @object and doesn't release it
 533  * until the action is destroyed.
 534  *
 535  * Returns: a new #GPropertyAction
 536  *
 537  * Since: 2.38
 538  **/
 539 GPropertyAction *
 540 g_property_action_new (const gchar *name,
 541                        gpointer     object,
 542                        const gchar *property_name)
 543 {
 544   g_return_val_if_fail (name != NULL, NULL);
 545   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 546   g_return_val_if_fail (property_name != NULL, NULL);
 547
 548   return g_object_new (G_TYPE_PROPERTY_ACTION,
 549                        "name", name,
 550                        "object", object,
 551                        "property-name", property_name,
 552                        NULL);
 553 }