gio/gpropertyaction.c

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