glibmm: untracked/gio/giomm/actiongroup.h

"Fossies" - the Fresh Open Source Software Archive

Member "glibmm-2.76.0/untracked/gio/giomm/actiongroup.h" (12 Mar 2023, 23689 Bytes) of package /linux/misc/glibmm-2.76.0.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "actiongroup.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report:

2.74.1_vs_2.76.0.

1 // Generated by gmmproc 2.76.0 -- DO NOT MODIFY! 2 #ifndef _GIOMM_ACTIONGROUP_H 3 #define _GIOMM_ACTIONGROUP_H 4 5 #include <giommconfig.h> 6 7 8 #include <glibmm/ustring.h> 9 #include <sigc++/sigc++.h> 10 11 /* Copyright (C) 2010 The giomm Development Team 12 * 13 * This library is free software; you can redistribute it and/or 14 * modify it under the terms of the GNU Lesser General Public 15 * License as published by the Free Software Foundation; either 16 * version 2.1 of the License, or (at your option) any later version. 17 * 18 * This library is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 * Lesser General Public License for more details. 22 * 23 * You should have received a copy of the GNU Lesser General Public 24 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 25 */ 26 27 28 #include <glibmm/interface.h> 29 #include <glibmm/varianttype.h> 30 #include <gio/gio.h> //To declare g_action_group_get_action_state_type(). 31 32 33 #ifndef DOXYGEN_SHOULD_SKIP_THIS 34 typedef struct _GActionGroupInterface GActionGroupInterface; 35 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 36 37 #ifndef DOXYGEN_SHOULD_SKIP_THIS 38 using GActionGroup = struct _GActionGroup; 39 using GActionGroupClass = struct _GActionGroupClass; 40 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 41 42 43 #ifndef DOXYGEN_SHOULD_SKIP_THIS 44 namespace Gio 45 { class GIOMM_API ActionGroup_Class; } // namespace Gio 46 #endif // DOXYGEN_SHOULD_SKIP_THIS 47 48 namespace Glib 49 { 50 51 class GIOMM_API VariantBase; 52 class GIOMM_API VariantContainerBase; 53 class GIOMM_API VariantType; 54 55 } 56 57 namespace Gio 58 { 59 60 /** ActionGroup - a group of actions. 61 * ActionGroup represents a group of actions. 62 * 63 * Each action in the group has a unique name (which is a string). All method 64 * calls, except list_actions() take the name of an action as an argument. 65 * 66 * The GActionGroup API is meant to be the 'public' API to the action group. 67 * The calls here are exactly the interaction that 'external forces' (eg: UI, 68 * incoming D-Bus messages, etc.) are supposed to have with actions. 69 * 'Internal' APIs (ie: ones meant only to be accessed by the action group 70 * implementation) are found on subclasses. This is why you will find -- for 71 * example -- get_action_enabled() but not an equivalent @c set() call. 72 * 73 * Signals are emitted on the action group in response to state changes on 74 * individual actions. 75 */ 76 77 class GIOMM_API ActionGroup : public Glib::Interface 78 { 79 80 #ifndef DOXYGEN_SHOULD_SKIP_THIS 81 82 public: 83 using CppObjectType = ActionGroup; 84 using CppClassType = ActionGroup_Class; 85 using BaseObjectType = GActionGroup; 86 using BaseClassType = GActionGroupInterface; 87 88 // noncopyable 89 ActionGroup(const ActionGroup&) = delete; 90 ActionGroup& operator=(const ActionGroup&) = delete; 91 92 private: 93 friend class ActionGroup_Class; 94 static CppClassType actiongroup_class_; 95 96 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 97 protected: 98 /** 99 * You should derive from this class to use it. 100 */ 101 ActionGroup(); 102 103 #ifndef DOXYGEN_SHOULD_SKIP_THIS 104 /** Called by constructors of derived classes. Provide the result of 105 * the Class init() function to ensure that it is properly 106 * initialized. 107 * 108 * @param interface_class The Class object for the derived type. 109 */ 110 explicit ActionGroup(const Glib::Interface_Class& interface_class); 111 112 public: 113 // This is public so that C++ wrapper instances can be 114 // created for C instances of unwrapped types. 115 // For instance, if an unexpected C type implements the C interface. 116 explicit ActionGroup(GActionGroup* castitem); 117 118 protected: 119 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 120 121 public: 122 123 ActionGroup(ActionGroup&& src) noexcept; 124 ActionGroup& operator=(ActionGroup&& src) noexcept; 125 126 ~ActionGroup() noexcept override; 127 128 static void add_interface(GType gtype_implementer); 129 130 /** Get the GType for this class, for use with the underlying GObject type system. 131 */ 132 static GType get_type() G_GNUC_CONST; 133 134 #ifndef DOXYGEN_SHOULD_SKIP_THIS 135 static GType get_base_type() G_GNUC_CONST; 136 #endif 137 138 ///Provides access to the underlying C GObject. 139 GActionGroup* gobj() { return reinterpret_cast<GActionGroup*>(gobject_); } 140 141 ///Provides access to the underlying C GObject. 142 const GActionGroup* gobj() const { return reinterpret_cast<GActionGroup*>(gobject_); } 143 144 private: 145 146 147 public: 148 149 /** Checks if the named action exists within @a action_group. 150 * 151 * @newin{2,28} 152 * 153 * @param action_name The name of the action to check for. 154 * @return Whether the named action exists. 155 */ 156 bool has_action(const Glib::ustring& action_name) const; 157 158 159 /** Lists the actions contained within @a action_group. 160 * 161 * @newin{2,28} 162 * 163 * @return A <tt>nullptr</tt>-terminated array of the names of the 164 * actions in the group. 165 */ 166 std::vector<Glib::ustring> list_actions() const; 167 168 //TODO: Add templated method, renaming this to query_action_variant). 169 170 /** Queries all aspects of the named action within an @a action_group. 171 * 172 * This function acquires the information available from 173 * g_action_group_has_action(), g_action_group_get_action_enabled(), 174 * g_action_group_get_action_parameter_type(), 175 * g_action_group_get_action_state_type(), 176 * g_action_group_get_action_state_hint() and 177 * g_action_group_get_action_state() with a single function call. 178 * 179 * This provides two main benefits. 180 * 181 * The first is the improvement in efficiency that comes with not having 182 * to perform repeated lookups of the action in order to discover 183 * different things about it. The second is that implementing 184 * ActionGroup can now be done by only overriding this one virtual 185 * function. 186 * 187 * The interface provides a default implementation of this function that 188 * calls the individual functions, as required, to fetch the 189 * information. The interface also provides default implementations of 190 * those functions that call this function. All implementations, 191 * therefore, must override either this function or all of the others. 192 * 193 * If the action exists, <tt>true</tt> is returned and any of the requested 194 * fields (as indicated by having a non-<tt>nullptr</tt> reference passed in) are 195 * filled. If the action doesn't exist, <tt>false</tt> is returned and the 196 * fields may or may not have been modified. 197 * 198 * @newin{2,32} 199 * 200 * @param action_name The name of an action in the group. 201 * @param enabled If the action is presently enabled. 202 * @param parameter_type The parameter type, or <tt>nullptr</tt> if none needed. 203 * @param state_type The state type, or <tt>nullptr</tt> if stateless. 204 * @param state_hint The state hint, or <tt>nullptr</tt> if none. 205 * @param state The current state, or <tt>nullptr</tt> if stateless. 206 * @return <tt>true</tt> if the action exists, else <tt>false</tt>. 207 */ 208 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantType& parameter_type, Glib::VariantBase& state_hint, Glib::VariantType& state_type, Glib::VariantBase& state); 209 210 /// A query_action() convenience overload. 211 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantType& parameter_type, Glib::VariantBase& state_hint, Glib::VariantType& state_type); 212 213 /// A query_action() convenience overload. 214 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantType& parameter_type, Glib::VariantBase& state_hint, Glib::VariantBase& state); 215 216 /// A query_action() convenience overload. 217 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantType& parameter_type, Glib::VariantBase& state_hint); 218 219 /// A query_action() convenience overload. 220 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantBase& state_hint, Glib::VariantType& state_type, Glib::VariantBase& state); 221 222 /// A query_action() convenience overload. 223 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantBase& state_hint, Glib::VariantType& state_type); 224 225 /// A query_action() convenience overload. 226 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantBase& state_hint, Glib::VariantBase& state); 227 228 /// A query_action() convenience overload. 229 bool query_action(const Glib::ustring& action_name, bool& enabled, Glib::VariantBase& state_hint); 230 231 232 /** Checks if the named action within @a action_group is currently enabled. 233 * 234 * An action must be enabled in order to be activated or in order to 235 * have its state changed from outside callers. 236 * 237 * @newin{2,28} 238 * 239 * @param action_name The name of the action to query. 240 * @return Whether or not the action is currently enabled. 241 */ 242 bool get_action_enabled(const Glib::ustring& action_name) const; 243 244 245 /** Queries the type of the parameter that must be given when activating 246 * the named action within @a action_group. 247 * 248 * When activating the action using g_action_group_activate_action(), 249 * the Variant given to that function must be of the type returned 250 * by this function. 251 * 252 * In the case that this function returns <tt>nullptr</tt>, you must not give any 253 * Variant, but <tt>nullptr</tt> instead. 254 * 255 * The parameter type of a particular action will never change but it is 256 * possible for an action to be removed and for a new action to be added 257 * with the same name but a different parameter type. 258 * 259 * @newin{2,28} 260 * 261 * @param action_name The name of the action to query. 262 * @return The parameter type. 263 */ 264 Glib::VariantType get_action_parameter_type(const Glib::ustring& action_name) const; 265 266 /** Queries the type of the state of the named action within 267 * @a action_group. 268 * 269 * If the action is stateful then this function returns the 270 * VariantType of the state. All calls to 271 * g_action_group_change_action_state() must give a Variant of this 272 * type and g_action_group_get_action_state() will return a Variant 273 * of the same type. 274 * 275 * If the action is not stateful then this function will return <tt>nullptr</tt>. 276 * In that case, g_action_group_get_action_state() will return <tt>nullptr</tt> 277 * and you must not call g_action_group_change_action_state(). 278 * 279 * The state type of a particular action will never change but it is 280 * possible for an action to be removed and for a new action to be added 281 * with the same name but a different state type. 282 * 283 * @newin{2,28} 284 * 285 * @param action_name The name of the action to query. 286 * @return The state type, if the action is stateful. 287 */ 288 Glib::VariantType get_action_state_type(const Glib::ustring& action_name) const; 289 290 //TODO: How do we check for a nullptr Variant? 291 /** 292 * Requests a hint about the valid range of values for the state of the 293 * named action within the action group 294 * 295 * If a null Variant is returned it either means that the action is not stateful 296 * or that there is no hint about the valid range of values for the 297 * state of the action. 298 * 299 * If a ariant array is returned then each item in the array is a 300 * possible value for the state. If Variant pair (ie: two-tuple) is 301 * returned then the tuple specifies the inclusive lower and upper bound 302 * of valid values for the state. 303 * 304 * In any case, the information is merely a hint. It may be possible to 305 * have a state value outside of the hinted range and setting a value 306 * within the range may fail. 307 * 308 * @param action_name The name of the action to query. 309 * @param value This will be set to the state range hint. 310 */ 311 template <typename T_Value> 312 void get_action_state_hint(const Glib::ustring& action_name, T_Value& value) const; 313 314 315 /** Requests a hint about the valid range of values for the state of the 316 * named action within @a action_group. 317 * 318 * If <tt>nullptr</tt> is returned it either means that the action is not stateful 319 * or that there is no hint about the valid range of values for the 320 * state of the action. 321 * 322 * If a Variant array is returned then each item in the array is a 323 * possible value for the state. If a Variant pair (ie: two-tuple) is 324 * returned then the tuple specifies the inclusive lower and upper bound 325 * of valid values for the state. 326 * 327 * In any case, the information is merely a hint. It may be possible to 328 * have a state value outside of the hinted range and setting a value 329 * within the range may fail. 330 * 331 * The return value (if non-<tt>nullptr</tt>) should be freed with 332 * Glib::variant_unref() when it is no longer required. 333 * 334 * @newin{2,28} 335 * 336 * @param action_name The name of the action to query. 337 * @return The state range hint. 338 */ 339 Glib::VariantContainerBase get_action_state_hint_variant(const Glib::ustring& action_name) const; 340 341 //TODO: How do we check for a nullptr Variant? 342 /** Queries the current state of the named action within the action group. 343 * 344 * If the action is not stateful then a null Variant will be returned. If the 345 * action is stateful then the type of the return value is the type 346 * given by get_action_state_type(). 347 * 348 * @param action_name The name of the action to query. 349 * @param value This will be set to the current state of the action. 350 */ 351 template <typename T_Value> 352 void get_action_state(const Glib::ustring& action_name, T_Value& value) const; 353 354 355 /** Queries the current state of the named action within @a action_group. 356 * 357 * If the action is not stateful then <tt>nullptr</tt> will be returned. If the 358 * action is stateful then the type of the return value is the type 359 * given by g_action_group_get_action_state_type(). 360 * 361 * The return value (if non-<tt>nullptr</tt>) should be freed with 362 * Glib::variant_unref() when it is no longer required. 363 * 364 * @newin{2,28} 365 * 366 * @param action_name The name of the action to query. 367 * @return The current state of the action. 368 */ 369 Glib::VariantBase get_action_state_variant(const Glib::ustring& action_name) const; 370 371 //TODO: Add templated method, renaming this to change_action_state_variant(). 372 373 /** Request for the state of the named action within @a action_group to be 374 * changed to @a value. 375 * 376 * The action must be stateful and @a value must be of the correct type. 377 * See g_action_group_get_action_state_type(). 378 * 379 * This call merely requests a change. The action may refuse to change 380 * its state or may change its state to something other than @a value. 381 * See g_action_group_get_action_state_hint(). 382 * 383 * If the @a value GVariant is floating, it is consumed. 384 * 385 * @newin{2,28} 386 * 387 * @param action_name The name of the action to request the change on. 388 * @param value The new state. 389 */ 390 void change_action_state(const Glib::ustring& action_name, const Glib::VariantBase& value); 391 392 //TODO: Add templated method, renaming this to activate_action_variant(). 393 394 /** Activate the named action within @a action_group. 395 * 396 * If the action is expecting a parameter, then the correct type of 397 * parameter must be given as @a parameter. If the action is expecting no 398 * parameters then @a parameter must be <tt>nullptr</tt>. See 399 * g_action_group_get_action_parameter_type(). 400 * 401 * If the ActionGroup implementation supports asynchronous remote 402 * activation over D-Bus, this call may return before the relevant 403 * D-Bus traffic has been sent, or any replies have been received. In 404 * order to block on such asynchronous activation calls, 405 * g_dbus_connection_flush() should be called prior to the code, which 406 * depends on the result of the action activation. Without flushing 407 * the D-Bus connection, there is no guarantee that the action would 408 * have been activated. 409 * 410 * The following code which runs in a remote app instance, shows an 411 * example of a "quit" action being activated on the primary app 412 * instance over D-Bus. Here g_dbus_connection_flush() is called 413 * before `exit()`. Without g_dbus_connection_flush(), the "quit" action 414 * may fail to be activated on the primary instance. 415 * 416 * 417 * [C example ellipted] 418 * 419 * @newin{2,28} 420 * 421 * @param action_name The name of the action to activate. 422 * @param parameter Parameters to the activation. 423 */ 424 void activate_action(const Glib::ustring& action_name, const Glib::VariantBase& parameter); 425 426 /// A activate_action() convenience overload. 427 void activate_action(const Glib::ustring& action_name); 428 429 430 /** Emits the ActionGroup::signal_action_added() signal on @a action_group. 431 * 432 * This function should only be called by ActionGroup implementations. 433 * 434 * @newin{2,28} 435 * 436 * @param action_name The name of an action in the group. 437 */ 438 void action_added(const Glib::ustring& action_name); 439 440 /** Emits the ActionGroup::signal_action_removed() signal on @a action_group. 441 * 442 * This function should only be called by ActionGroup implementations. 443 * 444 * @newin{2,28} 445 * 446 * @param action_name The name of an action in the group. 447 */ 448 void action_removed(const Glib::ustring& action_name); 449 450 /** Emits the ActionGroup::signal_action_enabled_changed() signal on @a action_group. 451 * 452 * This function should only be called by ActionGroup implementations. 453 * 454 * @newin{2,28} 455 * 456 * @param action_name The name of an action in the group. 457 * @param enabled Whether or not the action is now enabled. 458 */ 459 void action_enabled_changed(const Glib::ustring& action_name, bool enabled); 460 461 //TODO: Add templated method, renaming this to action_state_changed_variant). 462 463 /** Emits the ActionGroup::signal_action_state_changed() signal on @a action_group. 464 * 465 * This function should only be called by ActionGroup implementations. 466 * 467 * @newin{2,28} 468 * 469 * @param action_name The name of an action in the group. 470 * @param state The new state of the named action. 471 */ 472 void action_state_changed(const Glib::ustring& action_name, const Glib::VariantBase& state); 473 474 475 /** 476 * @par Slot Prototype: 477 * <tt>void on_my_%action_added(const Glib::ustring& action_name)</tt> 478 * 479 * Flags: Run Last 480 * 481 * Signals that a new action was just added to the group. 482 * This signal is emitted after the action has been added 483 * and is now visible. 484 * 485 * @newin{2,28} 486 * 487 * @param action_name The name of the action in @a action_group. 488 */ 489 490 Glib::SignalProxyDetailed<void(const Glib::ustring&)> signal_action_added(const Glib::ustring& action_name = {}); 491 492 493 /** 494 * @par Slot Prototype: 495 * <tt>void on_my_%action_enabled_changed(const Glib::ustring& action_name, bool enabled)</tt> 496 * 497 * Flags: Run Last 498 * 499 * Signals that the enabled status of the named action has changed. 500 * 501 * @newin{2,28} 502 * 503 * @param action_name The name of the action in @a action_group. 504 * @param enabled Whether the action is enabled or not. 505 */ 506 507 Glib::SignalProxyDetailed<void(const Glib::ustring&, bool)> signal_action_enabled_changed(const Glib::ustring& action_name = {}); 508 509 510 /** 511 * @par Slot Prototype: 512 * <tt>void on_my_%action_removed(const Glib::ustring& action_name)</tt> 513 * 514 * Flags: Run Last 515 * 516 * Signals that an action is just about to be removed from the group. 517 * This signal is emitted before the action is removed, so the action 518 * is still visible and can be queried from the signal handler. 519 * 520 * @newin{2,28} 521 * 522 * @param action_name The name of the action in @a action_group. 523 */ 524 525 Glib::SignalProxyDetailed<void(const Glib::ustring&)> signal_action_removed(const Glib::ustring& action_name = {}); 526 527 528 /** 529 * @par Slot Prototype: 530 * <tt>void on_my_%action_state_changed(const Glib::ustring& action_name, const Glib::VariantBase& value)</tt> 531 * 532 * Flags: Run Last, Must Collect 533 * 534 * Signals that the state of the named action has changed. 535 * 536 * @newin{2,28} 537 * 538 * @param action_name The name of the action in @a action_group. 539 * @param value The new value of the state. 540 */ 541 542 Glib::SignalProxyDetailed<void(const Glib::ustring&, const Glib::VariantBase&)> signal_action_state_changed(const Glib::ustring& action_name = {}); 543 544 545 protected: 546 virtual bool has_action_vfunc(const Glib::ustring& name) const; 547 548 549 virtual std::vector<Glib::ustring> list_actions_vfunc() const; 550 551 552 virtual bool get_action_enabled_vfunc(const Glib::ustring& name) const; 553 554 555 virtual Glib::VariantType get_action_parameter_type_vfunc(const Glib::ustring& name) const; 556 557 virtual Glib::VariantType get_action_state_type_vfunc(const Glib::ustring& name) const; 558 559 560 virtual Glib::VariantBase get_action_state_hint_vfunc(const Glib::ustring& name) const; 561 562 virtual Glib::VariantBase get_action_state_vfunc(const Glib::ustring& name) const; 563 564 565 virtual void change_action_state_vfunc(const Glib::ustring& name, const Glib::VariantBase& value); 566 567 virtual void activate_action_vfunc(const Glib::ustring& name, const Glib::VariantBase& parameter); 568 569 570 public: 571 572 public: 573 //C++ methods used to invoke GTK+ virtual functions: 574 575 protected: 576 //GTK+ Virtual Functions (override these to change behaviour): 577 578 //Default Signal Handlers:: 579 /// This is a default handler for the signal signal_action_added(). 580 virtual void on_action_added(const Glib::ustring& action_name); 581 /// This is a default handler for the signal signal_action_enabled_changed(). 582 virtual void on_action_enabled_changed(const Glib::ustring& action_name, bool enabled); 583 /// This is a default handler for the signal signal_action_removed(). 584 virtual void on_action_removed(const Glib::ustring& action_name); 585 /// This is a default handler for the signal signal_action_state_changed(). 586 virtual void on_action_state_changed(const Glib::ustring& action_name, const Glib::VariantBase& value); 587 588 589 }; 590 591 template <typename T_Value> 592 void ActionGroup::get_action_state(const Glib::ustring& action_name, T_Value& value) const 593 { 594 value = T_Value(); //Make sure that it is initialized. 595 596 using type_glib_variant = Glib::Variant<T_Value>; 597 598 g_return_if_fail( 599 g_variant_type_equal(g_action_group_get_action_state_type(const_cast<GActionGroup*>(gobj()), action_name.c_str()), type_glib_variant::variant_type().gobj())); 600 601 const auto variantBase = get_action_state_variant(action_name); 602 603 //TODO: Add a bool return instead of letting a std::bad_cast from the cast_dynamic() be thrown up to the caller? 604 const auto variantDerived = variantBase.cast_dynamic<type_glib_variant>(variantBase); 605 value = variantDerived.get(); 606 } 607 608 template <typename T_Value> 609 void ActionGroup::get_action_state_hint(const Glib::ustring& action_name, T_Value& value) const 610 { 611 value = T_Value(); //Make sure that it is initialized. 612 613 using type_glib_variant = Glib::Variant<T_Value>; 614 615 const auto variantBase = get_action_state_hint_variant(action_name); 616 617 // We can't check the type (a range) that will be returned before getting the range hint. 618 g_return_if_fail( 619 variantBase.is_of_type(type_glib_variant::variant_type()) ); 620 621 const auto variantDerived = variantBase.cast_dynamic<type_glib_variant>(variantBase); 622 value = variantDerived.get(); 623 } 624 625 } // namespace Gio 626 627 628 namespace Glib 629 { 630 /** A Glib::wrap() method for this object. 631 * 632 * @param object The C instance. 633 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. 634 * @result A C++ instance that wraps this C instance. 635 * 636 * @relates Gio::ActionGroup 637 */ 638 GIOMM_API 639 Glib::RefPtr<Gio::ActionGroup> wrap(GActionGroup* object, bool take_copy = false); 640 641 } // namespace Glib 642 643 644 #endif /* _GIOMM_ACTIONGROUP_H */ 645