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