"Fossies" - the Fresh Open Source Software Archive

Member "glibmm-2.74.0/gio/src/action.hg" (19 Sep 2022, 12917 Bytes) of package /linux/misc/glibmm-2.74.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "action.hg": 2.72.1_vs_2.74.0.

    1 /* Copyright (C) 2011 The giomm Development Team
    2  *
    3  * This library is free software; you can redistribute it and/or
    4  * modify it under the terms of the GNU Lesser General Public
    5  * License as published by the Free Software Foundation; either
    6  * version 2.1 of the License, or (at your option) any later version.
    7  *
    8  * This library is distributed in the hope that it will be useful,
    9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   11  * Lesser General Public License for more details.
   12  *
   13  * You should have received a copy of the GNU Lesser General Public
   14  * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
   15  */
   16 
   17 _CONFIGINCLUDE(giommconfig.h)
   18 
   19 #include <glibmm/interface.h>
   20 #include <glibmm/variant.h>
   21 #include <glibmm/varianttype.h>
   22 #include <gio/gio.h>
   23 
   24 _DEFS(giomm,gio)
   25 _PINCLUDE(glibmm/private/interface_p.h)
   26 _PINCLUDE(gio/gio.h)
   27 
   28 #ifndef DOXYGEN_SHOULD_SKIP_THIS
   29 typedef struct _GActionInterface GActionInterface;
   30 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
   31 
   32 namespace Gio
   33 {
   34 
   35 /** %Action - An action interface.
   36  * %Action represents a single named action.
   37  *
   38  * The main interface to an action is that it can be activated with activate().
   39  * This results in the signal_activate() signal being emitted. An activation
   40  * may optionally have a parameter, activate(const T_Value& parameter).
   41  * The correct type for the parameter is determined by a static parameter type
   42  * (which is given at construction time).
   43  *
   44  * An action may optionally have a state, in which case the state may be set
   45  * with change_state(). The correct type for the state is determined by a static
   46  * state type (which is given at construction time).
   47  *
   48  * An %Action can have a state, but no parameter, or vice versa. If it has both,
   49  * the parameter type can differ from the state type.
   50  *
   51  * The state may have a hint associated with it, specifying its valid range.
   52  *
   53  * %Action is merely the interface to the concept of an action, as described
   54  * above. Various implementations of actions exist, including SimpleAction.
   55  *
   56  * In all cases, the implementing class is responsible for storing the name of
   57  * the action, the parameter type, the enabled state, the optional state type
   58  * and the state and emitting the appropriate signals when these change. The
   59  * implementor is responsible for filtering calls to activate() and change_state()
   60  * for type safety and for the state being enabled.
   61  *
   62  * Probably the only useful thing to do with an %Action is to put it inside of a
   63  * SimpleActionGroup.
   64  *
   65  * @newin{2,32}
   66  */
   67 class GIOMM_API Action : public Glib::Interface
   68 {
   69   _CLASS_INTERFACE(Action, GAction, G_ACTION, GActionInterface, , , GIOMM_API)
   70 
   71 public:
   72   _WRAP_METHOD(Glib::ustring get_name() const, g_action_get_name)
   73   _WRAP_METHOD(Glib::VariantType get_parameter_type() const, g_action_get_parameter_type)
   74   _WRAP_METHOD(Glib::VariantType get_state_type() const, g_action_get_state_type)
   75 
   76   //TODO: Is there any specific type that can really be used with this? A std::list<>. We must test this.
   77   //  See also ActionGroup:::get_action_state_hint().
   78   /** Requests a hint about the valid range of values for the state of
   79    * the action.
   80    *
   81    * If a null Variant is returned it either means that the action is not stateful
   82    * or that there is no hint about the valid range of values for the
   83    * state of the action.
   84    *
   85    * If a Variant array is returned then each item in the array is a
   86    * possible value for the state.  If a Variant pair (ie: two-tuple) is
   87    * returned then the tuple specifies the inclusive lower and upper bound
   88    * of valid values for the state.
   89    *
   90    * In any case, the information is merely a hint.  It may be possible to
   91    * have a state value outside of the hinted range and setting a value
   92    * within the range may fail.
   93    *
   94    * @param value This will be set to the state range hint.
   95    */
   96   template <typename T_Value>
   97   void get_state_hint(T_Value& value) const;
   98 
   99   _WRAP_METHOD(Glib::VariantContainerBase get_state_hint_variant() const, g_action_get_state_hint)
  100 
  101   _WRAP_METHOD(bool get_enabled() const, g_action_get_enabled)
  102 
  103   /** Request for the state of @a action to be changed to @a value,
  104    * assuming that the action has the expected state type.
  105    *
  106    * See get_state_type().
  107    *
  108    * This call merely requests a change.  The action may refuse to change
  109    * its state or may change its state to something other than @a value.
  110    * See get_state_hint().
  111    *
  112    * @newin{2,38}
  113    *
  114    * @param value The new state.
  115    */
  116   template <typename T_Value>
  117   void change_state(const T_Value& value);
  118 
  119   //This is just here to maintain API compatibility,
  120   //by stopping the compiler from calling the
  121   //regular change_state() with a Variant,
  122   //if the application code previously called change_state(VariantBase).
  123   template <typename T_Value>
  124   void change_state(const Glib::Variant<T_Value>& value);
  125 
  126   _WRAP_METHOD(void change_state_variant(const Glib::VariantBase& value), g_action_change_state)
  127 
  128   /** Queries the current state of the action.
  129    *
  130    * If the action is not stateful then a null Variant will be returned.  If the
  131    * action is stateful then the type of the return value is the type
  132    * given by get_state_type().
  133    *
  134    * @param value This will be set to the current state of the action.
  135    */
  136   template <typename T_Value>
  137   void get_state(T_Value& value) const;
  138 
  139   _WRAP_METHOD(Glib::VariantBase get_state_variant() const, g_action_get_state)
  140 
  141   /** Activates the action without a parameter.
  142    */
  143   void activate();
  144 
  145   /** Activates the action with a parameter.
  146    *
  147    * The @a parameter must be the correct type of parameter for the action (ie:
  148    * the parameter type given at construction time).
  149    *
  150    * @param parameter The parameter to the activation
  151    */
  152   template <typename T_Value>
  153   void activate(const T_Value& parameter);
  154 
  155   //This is just here to maintain API compatibility,
  156   //by stopping the compiler from calling the
  157   //regular activate() with a Variant,
  158   //if the application code previously called activate(VariantBase).
  159   template <typename T_Value>
  160   void activate(const Glib::Variant<T_Value>& parameter);
  161 
  162   _WRAP_METHOD(void activate_variant(const Glib::VariantBase& parameter), g_action_activate)
  163 
  164   _WRAP_METHOD(static bool name_is_valid(const Glib::ustring& action_name), g_action_name_is_valid )
  165 
  166   /** Parses a detailed action name into its separate name and target components.
  167    *
  168    * Detailed action names can have three formats. See parse_detailed_name_variant().
  169    *
  170    * @newin{2,40}
  171    *
  172    * @param detailed_name A detailed action name.
  173    * @param[out] action_name The action name.
  174    * @param[out] target_value The target value.
  175    * @throw Glib::VariantParseError if @a detailed_name has an invalid format or a target of an unexpected type.
  176    */
  177   template <typename T_Value>
  178   static void parse_detailed_name(const Glib::ustring& detailed_name, Glib::ustring& action_name, T_Value& target_value);
  179 
  180   _WRAP_METHOD(static void parse_detailed_name_variant(const Glib::ustring& detailed_name,
  181     Glib::ustring& action_name{>>}, Glib::VariantBase& target_value{>>}), g_action_parse_detailed_name, errthrow "Glib::VariantParseError")
  182 
  183   /** Formats a detailed action name from the action's action_name and @a target_value.
  184    *
  185    * This function is the opposite of parse_detailed_action_name().
  186    * It will produce a string that can be parsed back to the @a action_name
  187    * and @a target_value by that function.
  188    *
  189    * See that function for the types of strings that will be printed by
  190    * this function.
  191    *
  192    * @param target_value A Variant target value.
  193    * @result A detailed format string.
  194    */
  195   template <typename T_Value>
  196   Glib::ustring print_detailed_name(const T_Value& target_value);
  197 
  198   _WRAP_METHOD(static Glib::ustring print_detailed_name_variant(const Glib::ustring& action_name, const Glib::VariantBase& target_value), g_action_print_detailed_name)
  199 
  200   _WRAP_PROPERTY("enabled", bool)
  201   _WRAP_PROPERTY("name", Glib::ustring)
  202   _WRAP_PROPERTY("parameter-type", Glib::VariantType)
  203   _WRAP_PROPERTY("state", Glib::VariantBase)
  204   _WRAP_PROPERTY("state-type", Glib::VariantType)
  205 
  206 protected:
  207 #m4 _CONVERSION(`Glib::ustring',`const gchar*',`$3.c_str()')
  208   _WRAP_VFUNC(Glib::ustring get_name() const, "get_name", keep_return)
  209 
  210 #m4 _CONVERSION(`Glib::VariantType',`const GVariantType*',`$3.gobj()')
  211 
  212   _WRAP_VFUNC(Glib::VariantType get_parameter_type() const, "get_parameter_type", keep_return)
  213   _WRAP_VFUNC(Glib::VariantType get_state_type() const, "get_state_type", keep_return)
  214 
  215   _WRAP_VFUNC(Glib::VariantBase get_state_hint() const, "get_state_hint", refreturn_ctype)
  216 
  217   _WRAP_VFUNC(bool get_enabled() const, "get_enabled")
  218 
  219   _WRAP_VFUNC(Glib::VariantBase get_state() const, "get_state", refreturn_ctype)
  220 
  221 #m4 _CONVERSION(`GVariant*',`const Glib::VariantBase&',`Glib::wrap($3, true)')
  222   _WRAP_VFUNC(void change_state(const Glib::VariantBase& value), "change_state")
  223   _WRAP_VFUNC(void activate(const Glib::VariantBase& parameter), "activate")
  224 };
  225 
  226 template <typename T_Value>
  227 void Action::get_state(T_Value& value) const
  228 {
  229   value = T_Value(); //Make sure that it is initialized.
  230 
  231   using type_glib_variant = Glib::Variant<T_Value>;
  232 
  233   g_return_if_fail(
  234     g_variant_type_equal(g_action_get_state_type(const_cast<GAction*>(gobj())), type_glib_variant::variant_type().gobj()));
  235 
  236   const auto variantBase = get_state_variant();
  237   const auto variantDerived = variantBase.cast_dynamic<type_glib_variant>(variantBase);
  238   value = variantDerived.get();
  239 }
  240 
  241 template <typename T_Value>
  242 void Action::get_state_hint(T_Value& value) const
  243 {
  244   value = T_Value(); //Make sure that it is initialized.
  245 
  246   using type_glib_variant = Glib::Variant<T_Value>;
  247 
  248   const auto variantBase = get_state_hint_variant();
  249 
  250   // We can't check the type (a range) that will be returned before getting the range hint.
  251   g_return_if_fail(
  252     variantBase.is_of_type(type_glib_variant::variant_type()) );
  253 
  254   const auto variantDerived = variantBase.cast_dynamic<type_glib_variant>(variantBase);
  255   value = variantDerived.get();
  256 }
  257 
  258 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  259 // Doxygen 1.8.4 does not understand that this is the static function previously declared.
  260 template <typename T_Value>
  261 //static
  262 void Action::parse_detailed_name(const Glib::ustring& detailed_name, Glib::ustring& action_name, T_Value& target_value)
  263 {
  264   action_name.clear(); //Make sure the output arguments are initialized.
  265   target_value = T_Value();
  266 
  267   using type_glib_variant = Glib::Variant<T_Value>;
  268 
  269   Glib::VariantBase target_value_variantBase;
  270   parse_detailed_name_variant(detailed_name, action_name, target_value_variantBase);
  271 
  272   if (!target_value_variantBase)
  273     throw Glib::VariantParseError(Glib::VariantParseError::TYPE_ERROR,
  274       "Detailed action name '" + detailed_name + "' has no target. Expected a target of type " +
  275       type_glib_variant::variant_type().get_string());
  276 
  277   if (!target_value_variantBase.is_of_type(type_glib_variant::variant_type()))
  278     throw Glib::VariantParseError(Glib::VariantParseError::TYPE_ERROR,
  279       "Detailed action name '" + detailed_name + "' has a target of type " +
  280       target_value_variantBase.get_type_string() + ". Expected " + type_glib_variant::variant_type().get_string());
  281 
  282   const type_glib_variant target_value_variantDerived =
  283     target_value_variantBase.cast_dynamic<type_glib_variant>(target_value_variantBase);
  284   target_value = target_value_variantDerived.get();
  285 }
  286 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  287 
  288 template <typename T_Value>
  289 Glib::ustring Action::print_detailed_name(const T_Value& target_value)
  290 {
  291   using type_glib_variant = Glib::Variant<T_Value>;
  292 
  293   g_return_val_if_fail(
  294     g_variant_type_equal(g_action_get_parameter_type(const_cast<GAction*>(gobj())), type_glib_variant::variant_type().gobj()),
  295     Glib::ustring());
  296   return print_detailed_name_variant(get_name(), type_glib_variant::create(target_value));
  297 }
  298 
  299 template <typename T_Value>
  300 void Action::change_state(const T_Value& value)
  301 {
  302   using type_glib_variant = Glib::Variant<T_Value>;
  303 
  304   g_return_if_fail(
  305     g_variant_type_equal(g_action_get_state_type(const_cast<GAction*>(gobj())), type_glib_variant::variant_type().gobj()));
  306 
  307   change_state_variant(type_glib_variant::create(value));
  308 }
  309 
  310 template <typename T_Value>
  311 void Action::change_state(const Glib::Variant<T_Value>& value)
  312 {
  313   change_state_variant(value);
  314 }
  315 
  316 template <typename T_Value>
  317 void Action::activate(const T_Value& parameter)
  318 {
  319   using type_glib_variant = Glib::Variant<T_Value>;
  320 
  321   g_return_if_fail(
  322     g_variant_type_equal(g_action_get_parameter_type(const_cast<GAction*>(gobj())), type_glib_variant::variant_type().gobj()));
  323 
  324   activate_variant(type_glib_variant::create(parameter));
  325 }
  326 
  327 
  328 template <typename T_Value>
  329 void Action::activate(const Glib::Variant<T_Value>& value)
  330 {
  331   activate_variant(value);
  332 }
  333 
  334 
  335 } // namespace Gio