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