1/* Copyright (C) 2012 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#include <glibmm/interface.h> 18#include <giomm/simpleaction.h> 19 20_DEFS(giomm,gio) 21_PINCLUDE(glibmm/private/interface_p.h) 22_PINCLUDE(gio/gio.h) 23 24#ifndef DOXYGEN_SHOULD_SKIP_THIS 25typedef struct _GActionMapInterface GActionMapInterface; 26#endif /* DOXYGEN_SHOULD_SKIP_THIS */ 27 28namespace Gio 29{ 30 31class GIOMM_API Action; 32 33//TODO: Instead derive from ActionGroup, when we can break ABI, 34//because the GActionMap interface requires the GActionGroup interface. 35//LoadableIcon does a similar thing correctly, for instance. 36 37/** ActionMap - Interface for action containers. 38 * The ActionMap interface is implemented by ActionGroup implementations that 39 * operate by containing a number of named Action instances, such as 40 * SimpleActionGroup. 41 * 42 * One useful application of this interface is to map the names of actions from 43 * various action groups to unique, prefixed names (e.g. by prepending "app." 44 * or "win."). This is the motivation for the 'Map' part of the interface name. 45 * @newin{2,32} 46 */ 47class GIOMM_API ActionMap : public Glib::Interface 48{ 49 _CLASS_INTERFACE(ActionMap, GActionMap, G_ACTION_MAP, GActionMapInterface, , , GIOMM_API) 50 51 // The various add_action...() methods are our equivalent for g_action_map_add_action_entries(). 52 _IGNORE(g_action_map_add_action_entries) 53 54public: 55 _WRAP_METHOD(void add_action(const Glib::RefPtr<Action>& action), g_action_map_add_action) 56 _WRAP_METHOD(void remove_action(const Glib::ustring& action_name), g_action_map_remove_action) 57 58 _WRAP_METHOD(Glib::RefPtr<Action> lookup_action(const Glib::ustring& action_name), g_action_map_lookup_action, refreturn) 59 _WRAP_METHOD(Glib::RefPtr<const Action> lookup_action(const Glib::ustring& action_name) const, g_action_map_lookup_action, constversion, refreturn) 60 61 /** A convenience method for creating a SimpleAction instance 62 * and adding it to the ActionMap. 63 * 64 * @param name The name of the Action. 65 * @return The Action. 66 */ 67 Glib::RefPtr<SimpleAction> add_action(const Glib::ustring& name); 68 69 /** A Slot to be called when an action has been activated, 70 * without passing a parameter to the slot. 71 * See add_action() and add_action_bool(). 72 * 73 * For instance, 74 * void on_slot_activated(); 75 */ 76 using ActivateSlot = sigc::slot<void>; 77 78 /** A convenience method for creating a SimpleAction instance 79 * and adding it to the ActionMap. 80 * 81 * @param name The name of the Action. 82 * @param slot The callback method to be called when the action is activated. 83 * @return The Action. 84 */ 85 Glib::RefPtr<SimpleAction> add_action(const Glib::ustring& name, const ActivateSlot& slot); 86 87 88 /** A Slot to be called when an action has been activated, 89 * passing a parameter of a specified type. 90 * See add_action_with_parameter(). 91 * 92 * For instance, 93 * void on_slot_activated(const Glib::VariantBase& parameter); 94 */ 95 using ActivateWithParameterSlot = sigc::slot<void, const Glib::VariantBase&>; 96 97_DEPRECATE_IFDEF_START 98 /** A convenience method for creating a SimpleAction instance 99 * and adding it to the ActionMap. 100 * 101 * @param name The name of the Action. 102 * @param slot The callback method to be called when the action is activated. 103 * @return The Action. 104 * 105 * @deprecated This overload does not work as it does not set a parameter 106 * type on the Action, so activating it with a parameter cannot work. Use the 107 * other add_action_with_parameter() overload, which takes a parameter type. 108 */ 109 Glib::RefPtr<SimpleAction> add_action_with_parameter(const Glib::ustring& name, const ActivateWithParameterSlot& slot); 110_DEPRECATE_IFDEF_END 111 112 /** A convenience method for creating a SimpleAction instance, which when 113 * activated will call a slot receiving a given type of parameter, and adding 114 * that SimpleAction to the ActionMap. 115 * 116 * @param name The name of the Action. 117 * @param parameter_type The type of parameter to be passed to the slot. 118 * @param slot The callback method to be called when the action is activated. 119 * @return The Action. 120 */ 121 Glib::RefPtr<SimpleAction> add_action_with_parameter(const Glib::ustring& name, const Glib::VariantType& parameter_type, const ActivateWithParameterSlot& slot); 122 123 124 /** A convenience method for creating a boolean-stateful SimpleAction instance 125 * and adding it to the ActionMap. 126 * 127 * @param name The name of the Action. 128 * @param state The initial state. 129 * @return The Action. 130 */ 131 Glib::RefPtr<SimpleAction> add_action_bool(const Glib::ustring& name, bool state = false); 132 133 /** A convenience method for creating a boolean-stateful (toggle) SimpleAction instance 134 * and adding it to the ActionMap. 135 * 136 * @param name The name of the Action. 137 * @param slot The callback method to be called when the action is activated. 138 * @param state The initial state. 139 * @return The Action. 140 */ 141 Glib::RefPtr<SimpleAction> add_action_bool(const Glib::ustring& name, const ActivateSlot& slot, bool state = false); 142 143 144//TODO: Docs: Add hints about how to specify the various possible states in the GtkBuilder XML. 145 /** A convenience method for creating a string-based radio SimpleAction instance 146 * and adding it to the ActionMap. 147 * 148 * @param name The name of the Action. 149 * @param state The initial state. 150 * @return The Action. 151 */ 152 Glib::RefPtr<SimpleAction> add_action_radio_string(const Glib::ustring& name, const Glib::ustring& state); 153 154 /** A Slot to be called when an action has been activated. 155 * See add_action_radio_string(). 156 * 157 * For instance, 158 * void on_slot_activated(const Glib::ustring& parameter); 159 */ 160 using ActivateWithStringParameterSlot = sigc::slot<void, const Glib::ustring&>; 161 162//TODO: Docs: Add hints about how to specify the various possible states in the GtkBuilder XML. 163 /** A convenience method for creating a string-based radio SimpleAction instance 164 * and adding it to the ActionMap. 165 * 166 * @param name The name of the Action. 167 * @param slot The callback method to be called when the action is activated. 168 * @param state The initial state. 169 * @return The Action. 170 */ 171 Glib::RefPtr<SimpleAction> add_action_radio_string(const Glib::ustring& name, const ActivateWithStringParameterSlot& slot, const Glib::ustring& state); 172 173 174//TODO: Docs: Add hints about how to specify the various possible states in the GtkBuilder XML. 175 /** A convenience method for creating an integer-based radio SimpleAction instance 176 * and adding it to the ActionMap. 177 * 178 * @param name The name of the Action. 179 * @param state The initial state. 180 * @return The Action. 181 */ 182 Glib::RefPtr<SimpleAction> add_action_radio_integer(const Glib::ustring& name, gint32 state); 183 184 /** A Slot to be called when an action has been activated. 185 * See add_action_radio_integer(). 186 * 187 * For instance, 188 * void on_slot_activated(int parameter); 189 */ 190 using ActivateWithIntParameterSlot = sigc::slot<void, int>; 191 192//TODO: Docs: Add hints about how to specify the various possible states in the GtkBuilder XML. 193 /** A convenience method for creating an integer-based radio SimpleAction instance 194 * and adding it to the ActionMap. 195 * 196 * @param name The name of the Action. 197 * @param slot The callback method to be called when the action is activated. 198 * @param state The initial state. 199 * @return The Action. 200 */ 201 Glib::RefPtr<SimpleAction> add_action_radio_integer(const Glib::ustring& name, const ActivateWithIntParameterSlot& slot, gint32 state); 202 203 204#m4 _CONVERSION(`Glib::RefPtr<Action>', `GAction*', `Glib::unwrap($3)') 205 _WRAP_VFUNC(Glib::RefPtr<Action> lookup_action(const Glib::ustring& name) const, "lookup_action", refreturn) 206 207 //TODO: Change this to use const & when we can break ABI. 208 // ( Changing it causes a symbol lookup error when trying to run already-built applications. ) 209#m4 _CONVERSION(`GAction*', `Glib::RefPtr<Action>', `Glib::wrap($3, true)') 210 _WRAP_VFUNC(void add_action(Glib::RefPtr<Action> action) const, "add_action") 211 _WRAP_VFUNC(void remove_action(const Glib::ustring& name), "remove_action") 212}; 213 214} // namespace Gio 215