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   gboolean            invert_boolean;
  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   PROP_INVERT_BOOLEAN
 124 };
 125
 126 static gboolean
 127 g_property_action_get_invert_boolean (GAction *action)
 128 {
 129   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 130
 131   return paction->invert_boolean;
 132 }
 133
 134 static const gchar *
 135 g_property_action_get_name (GAction *action)
 136 {
 137   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 138
 139   return paction->name;
 140 }
 141
 142 static const GVariantType *
 143 g_property_action_get_parameter_type (GAction *action)
 144 {
 145   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 146
 147   return paction->pspec->value_type == G_TYPE_BOOLEAN ? NULL : paction->state_type;
 148 }
 149
 150 static const GVariantType *
 151 g_property_action_get_state_type (GAction *action)
 152 {
 153   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 154
 155   return paction->state_type;
 156 }
 157
 158 static GVariant *
 159 g_property_action_get_state_hint (GAction *action)
 160 {
 161   return NULL;
 162 }
 163
 164 static gboolean
 165 g_property_action_get_enabled (GAction *action)
 166 {
 167   return TRUE;
 168 }
 169
 170 static void
 171 g_property_action_set_state (GPropertyAction *paction,
 172                              GVariant        *variant)
 173 {
 174   GValue value = G_VALUE_INIT;
 175
 176   g_value_init (&value, paction->pspec->value_type);
 177   g_settings_get_mapping (&value, variant, NULL);
 178
 179   if (paction->pspec->value_type == G_TYPE_BOOLEAN && paction->invert_boolean)
 180     g_value_set_boolean (&value, !g_value_get_boolean (&value));
 181
 182   g_object_set_property (paction->object, paction->pspec->name, &value);
 183   g_value_unset (&value);
 184 }
 185
 186 static void
 187 g_property_action_change_state (GAction  *action,
 188                                 GVariant *value)
 189 {
 190   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 191
 192   g_return_if_fail (g_variant_is_of_type (value, paction->state_type));
 193
 194   g_property_action_set_state (paction, value);
 195 }
 196
 197 static GVariant *
 198 g_property_action_get_state (GAction *action)
 199 {
 200   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 201   GValue value = G_VALUE_INIT;
 202   GVariant *result;
 203
 204   g_value_init (&value, paction->pspec->value_type);
 205   g_object_get_property (paction->object, paction->pspec->name, &value);
 206
 207   if (paction->pspec->value_type == G_TYPE_BOOLEAN && paction->invert_boolean)
 208     g_value_set_boolean (&value, !g_value_get_boolean (&value));
 209
 210   result = g_settings_set_mapping (&value, paction->state_type, NULL);
 211   g_value_unset (&value);
 212
 213   return g_variant_ref_sink (result);
 214 }
 215
 216 static void
 217 g_property_action_activate (GAction  *action,
 218                             GVariant *parameter)
 219 {
 220   GPropertyAction *paction = G_PROPERTY_ACTION (action);
 221
 222   if (paction->pspec->value_type == G_TYPE_BOOLEAN)
 223     {
 224       gboolean value;
 225
 226       g_return_if_fail (paction->pspec->value_type == G_TYPE_BOOLEAN && parameter == NULL);
 227
 228       g_object_get (paction->object, paction->pspec->name, &value, NULL);
 229       value = !value;
 230       g_object_set (paction->object, paction->pspec->name, value, NULL);
 231     }
 232   else
 233     {
 234       g_return_if_fail (parameter != NULL && g_variant_is_of_type (parameter, paction->state_type));
 235
 236       g_property_action_set_state (paction, parameter);
 237     }
 238 }
 239
 240 static const GVariantType *
 241 g_property_action_determine_type (GParamSpec *pspec)
 242 {
 243   if (G_TYPE_IS_ENUM (pspec->value_type))
 244     return G_VARIANT_TYPE_STRING;
 245
 246   switch (pspec->value_type)
 247     {
 248     case G_TYPE_BOOLEAN:
 249       return G_VARIANT_TYPE_BOOLEAN;
 250
 251     case G_TYPE_INT:
 252       return G_VARIANT_TYPE_INT32;
 253
 254     case G_TYPE_UINT:
 255       return G_VARIANT_TYPE_UINT32;
 256
 257     case G_TYPE_DOUBLE:
 258     case G_TYPE_FLOAT:
 259       return G_VARIANT_TYPE_DOUBLE;
 260
 261     case G_TYPE_STRING:
 262       return G_VARIANT_TYPE_STRING;
 263
 264     default:
 265       g_critical ("Unable to use GPropertyAction with property '%s::%s' of type '%s'",
 266                   g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->value_type));
 267       return NULL;
 268     }
 269 }
 270
 271 static void
 272 g_property_action_notify (GObject    *object,
 273                           GParamSpec *pspec,
 274                           gpointer    user_data)
 275 {
 276   GPropertyAction *paction = user_data;
 277
 278   g_assert (object == paction->object);
 279   g_assert (pspec == paction->pspec);
 280
 281   g_object_notify (G_OBJECT (paction), "state");
 282 }
 283
 284 static void
 285 g_property_action_set_property_name (GPropertyAction *paction,
 286                                      const gchar     *property_name)
 287 {
 288   GParamSpec *pspec;
 289   gchar *detailed;
 290
 291   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (paction->object), property_name);
 292
 293   if (pspec == NULL)
 294     {
 295       g_critical ("Attempted to use non-existent property '%s::%s' for GPropertyAction",
 296                   G_OBJECT_TYPE_NAME (paction->object), property_name);
 297       return;
 298     }
 299
 300   if (~pspec->flags & G_PARAM_READABLE || ~pspec->flags & G_PARAM_WRITABLE || pspec->flags & G_PARAM_CONSTRUCT_ONLY)
 301     {
 302       g_critical ("Property '%s::%s' used with GPropertyAction must be readable, writable, and not construct-only",
 303                   G_OBJECT_TYPE_NAME (paction->object), property_name);
 304       return;
 305     }
 306
 307   paction->pspec = pspec;
 308
 309   detailed = g_strconcat ("notify::", paction->pspec->name, NULL);
 310   paction->state_type = g_property_action_determine_type (paction->pspec);
 311   g_signal_connect (paction->object, detailed, G_CALLBACK (g_property_action_notify), paction);
 312   g_free (detailed);
 313 }
 314
 315 static void
 316 g_property_action_set_property (GObject      *object,
 317                                 guint         prop_id,
 318                                 const GValue *value,
 319                                 GParamSpec   *pspec)
 320 {
 321   GPropertyAction *paction = G_PROPERTY_ACTION (object);
 322
 323   switch (prop_id)
 324     {
 325     case PROP_NAME:
 326       paction->name = g_value_dup_string (value);
 327       break;
 328
 329     case PROP_OBJECT:
 330       paction->object = g_value_dup_object (value);
 331       break;
 332
 333     case PROP_PROPERTY_NAME:
 334       g_property_action_set_property_name (paction, g_value_get_string (value));
 335       break;
 336
 337     case PROP_INVERT_BOOLEAN:
 338       paction->invert_boolean = g_value_get_boolean (value);
 339       break;
 340
 341     default:
 342       g_assert_not_reached ();
 343     }
 344 }
 345
 346 static void
 347 g_property_action_get_property (GObject    *object,
 348                                 guint       prop_id,
 349                                 GValue     *value,
 350                                 GParamSpec *pspec)
 351 {
 352   GAction *action = G_ACTION (object);
 353
 354   switch (prop_id)
 355     {
 356     case PROP_NAME:
 357       g_value_set_string (value, g_property_action_get_name (action));
 358       break;
 359
 360     case PROP_PARAMETER_TYPE:
 361       g_value_set_boxed (value, g_property_action_get_parameter_type (action));
 362       break;
 363
 364     case PROP_ENABLED:
 365       g_value_set_boolean (value, g_property_action_get_enabled (action));
 366       break;
 367
 368     case PROP_STATE_TYPE:
 369       g_value_set_boxed (value, g_property_action_get_state_type (action));
 370       break;
 371
 372     case PROP_STATE:
 373       g_value_take_variant (value, g_property_action_get_state (action));
 374       break;
 375
 376     case PROP_INVERT_BOOLEAN:
 377       g_value_set_boolean (value, g_property_action_get_invert_boolean (action));
 378       break;
 379
 380     default:
 381       g_assert_not_reached ();
 382     }
 383 }
 384
 385 static void
 386 g_property_action_finalize (GObject *object)
 387 {
 388   GPropertyAction *paction = G_PROPERTY_ACTION (object);
 389
 390   g_signal_handlers_disconnect_by_func (paction->object, g_property_action_notify, paction);
 391   g_object_unref (paction->object);
 392   g_free (paction->name);
 393
 394   G_OBJECT_CLASS (g_property_action_parent_class)
 395     ->finalize (object);
 396 }
 397
 398 void
 399 g_property_action_init (GPropertyAction *property)
 400 {
 401 }
 402
 403 void
 404 g_property_action_iface_init (GActionInterface *iface)
 405 {
 406   iface->get_name = g_property_action_get_name;
 407   iface->get_parameter_type = g_property_action_get_parameter_type;
 408   iface->get_state_type = g_property_action_get_state_type;
 409   iface->get_state_hint = g_property_action_get_state_hint;
 410   iface->get_enabled = g_property_action_get_enabled;
 411   iface->get_state = g_property_action_get_state;
 412   iface->change_state = g_property_action_change_state;
 413   iface->activate = g_property_action_activate;
 414 }
 415
 416 void
 417 g_property_action_class_init (GPropertyActionClass *class)
 418 {
 419   GObjectClass *object_class = G_OBJECT_CLASS (class);
 420
 421   object_class->set_property = g_property_action_set_property;
 422   object_class->get_property = g_property_action_get_property;
 423   object_class->finalize = g_property_action_finalize;
 424
 425   /**
 426    * GPropertyAction:name:
 427    *
 428    * The name of the action.  This is mostly meaningful for identifying
 429    * the action once it has been added to a #GActionMap.
 430    *
 431    * Since: 2.38
 432    **/
 433   g_object_class_install_property (object_class, PROP_NAME,
 434                                    g_param_spec_string ("name",
 435                                                         P_("Action Name"),
 436                                                         P_("The name used to invoke the action"),
 437                                                         NULL,
 438                                                         G_PARAM_READWRITE |
 439                                                         G_PARAM_CONSTRUCT_ONLY |
 440                                                         G_PARAM_STATIC_STRINGS));
 441
 442   /**
 443    * GPropertyAction:parameter-type:
 444    *
 445    * The type of the parameter that must be given when activating the
 446    * action.
 447    *
 448    * Since: 2.38
 449    **/
 450   g_object_class_install_property (object_class, PROP_PARAMETER_TYPE,
 451                                    g_param_spec_boxed ("parameter-type",
 452                                                        P_("Parameter Type"),
 453                                                        P_("The type of GVariant passed to activate()"),
 454                                                        G_TYPE_VARIANT_TYPE,
 455                                                        G_PARAM_READABLE |
 456                                                        G_PARAM_STATIC_STRINGS));
 457
 458   /**
 459    * GPropertyAction:enabled:
 460    *
 461    * If @action is currently enabled.
 462    *
 463    * If the action is disabled then calls to g_action_activate() and
 464    * g_action_change_state() have no effect.
 465    *
 466    * Since: 2.38
 467    **/
 468   g_object_class_install_property (object_class, PROP_ENABLED,
 469                                    g_param_spec_boolean ("enabled",
 470                                                          P_("Enabled"),
 471                                                          P_("If the action can be activated"),
 472                                                          TRUE,
 473                                                          G_PARAM_READABLE |
 474                                                          G_PARAM_STATIC_STRINGS));
 475
 476   /**
 477    * GPropertyAction:state-type:
 478    *
 479    * The #GVariantType of the state that the action has, or %NULL if the
 480    * action is stateless.
 481    *
 482    * Since: 2.38
 483    **/
 484   g_object_class_install_property (object_class, PROP_STATE_TYPE,
 485                                    g_param_spec_boxed ("state-type",
 486                                                        P_("State Type"),
 487                                                        P_("The type of the state kept by the action"),
 488                                                        G_TYPE_VARIANT_TYPE,
 489                                                        G_PARAM_READABLE |
 490                                                        G_PARAM_STATIC_STRINGS));
 491
 492   /**
 493    * GPropertyAction:state:
 494    *
 495    * The state of the action, or %NULL if the action is stateless.
 496    *
 497    * Since: 2.38
 498    **/
 499   g_object_class_install_property (object_class, PROP_STATE,
 500                                    g_param_spec_variant ("state",
 501                                                          P_("State"),
 502                                                          P_("The state the action is in"),
 503                                                          G_VARIANT_TYPE_ANY,
 504                                                          NULL,
 505                                                          G_PARAM_READABLE |
 506                                                          G_PARAM_STATIC_STRINGS));
 507
 508   /**
 509    * GPropertyAction:object:
 510    *
 511    * The object to wrap a property on.
 512    *
 513    * The object must be a non-%NULL #GObject with properties.
 514    *
 515    * Since: 2.38
 516    **/
 517   g_object_class_install_property (object_class, PROP_OBJECT,
 518                                    g_param_spec_object ("object",
 519                                                         P_("Object"),
 520                                                         P_("The object with the property to wrap"),
 521                                                         G_TYPE_OBJECT,
 522                                                         G_PARAM_WRITABLE |
 523                                                         G_PARAM_CONSTRUCT_ONLY |
 524                                                         G_PARAM_STATIC_STRINGS));
 525
 526   /**
 527    * GPropertyAction:property-name:
 528    *
 529    * The name of the property to wrap on the object.
 530    *
 531    * The property must exist on the passed-in object and it must be
 532    * readable and writable (and not construct-only).
 533    *
 534    * Since: 2.38
 535    **/
 536   g_object_class_install_property (object_class, PROP_PROPERTY_NAME,
 537                                    g_param_spec_string ("property-name",
 538                                                         P_("Property name"),
 539                                                         P_("The name of the property to wrap"),
 540                                                         NULL,
 541                                                         G_PARAM_WRITABLE |
 542                                                         G_PARAM_CONSTRUCT_ONLY |
 543                                                         G_PARAM_STATIC_STRINGS));
 544
 545   /**
 546    * GPropertyAction:invert-boolean:
 547    *
 548    * If %TRUE, the state of the action will be the negation of the
 549    * property value, provided the property is boolean.
 550    *
 551    * Since: 2.46
 552    */
 553   g_object_class_install_property (object_class, PROP_INVERT_BOOLEAN,
 554                                    g_param_spec_boolean ("invert-boolean",
 555                                                          P_("Invert boolean"),
 556                                                          P_("Whether to invert the value of a boolean property"),
 557                                                          FALSE,
 558                                                          G_PARAM_READWRITE |
 559                                                          G_PARAM_CONSTRUCT_ONLY |
 560                                                          G_PARAM_STATIC_STRINGS));
 561 }
 562
 563 /**
 564  * g_property_action_new:
 565  * @name: the name of the action to create
 566  * @object: (type GObject.Object): the object that has the property
 567  *   to wrap
 568  * @property_name: the name of the property
 569  *
 570  * Creates a #GAction corresponding to the value of property
 571  * @property_name on @object.
 572  *
 573  * The property must be existent and readable and writable (and not
 574  * construct-only).
 575  *
 576  * This function takes a reference on @object and doesn't release it
 577  * until the action is destroyed.
 578  *
 579  * Returns: a new #GPropertyAction
 580  *
 581  * Since: 2.38
 582  **/
 583 GPropertyAction *
 584 g_property_action_new (const gchar *name,
 585                        gpointer     object,
 586                        const gchar *property_name)
 587 {
 588   g_return_val_if_fail (name != NULL, NULL);
 589   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
 590   g_return_val_if_fail (property_name != NULL, NULL);
 591
 592   return g_object_new (G_TYPE_PROPERTY_ACTION,
 593                        "name", name,
 594                        "object", object,
 595                        "property-name", property_name,
 596                        NULL);
 597 }