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