KiCad PCB EDA Suite
Loading...
Searching...
No Matches
tool_action.h
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 2013-2023 CERN
5 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
6 *
7 * @author Tomasz Wlostowski <[email protected]>
8 * @author Maciej Suminski <[email protected]>
9 *
10 * This program is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU General Public License
12 * as published by the Free Software Foundation; either version 2
13 * of the License, or (at your option) any later version.
14 *
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, you may find one here:
22 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
23 * or you may search the http://www.gnu.org website for the version 2 license,
24 * or you may write to the Free Software Foundation, Inc.,
25 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
26 */
27
28#ifndef __TOOL_ACTION_H
29#define __TOOL_ACTION_H
30
31#include <bitset>
32#include <cassert>
33#include <optional>
34#include <string>
35#include <string_view>
36
37#include <ki_any.h>
38#include <wx/string.h>
39
40class TOOL_EVENT;
41
42enum class BITMAPS : unsigned int;
43
51
59
61enum class TOOLBAR_STATE
62{
63 HIDDEN = 0,
64 TOGGLE = 1,
65 CANCEL = 2,
66
68};
69
70// The length of the TOOLBAR_STATE enum as a size_t (used for bitset creation)
71const size_t gToolbarStateNumber = static_cast<size_t>( TOOLBAR_STATE::ENUM_LENGTH );
72
73typedef std::bitset<gToolbarStateNumber> TOOLBAR_STATE_FLAGS;
74
79{
80public:
81 TOOL_ACTION_GROUP( std::string aName ) :
82 m_name( aName )
83 {
84 // Assign a unique group ID to each group
85 static int groupIDs = 0;
86 m_groupID = ++groupIDs;
87 };
88
90 {
91 // Ensure a copy of a group is exactly the same as this one to get
92 // proper comparisons
93 m_name = aOther.GetName();
94 m_groupID = aOther.GetGroupID();
95 }
96
97 int GetGroupID() const { return m_groupID; }
98 const std::string& GetName() const { return m_name; }
99
100 bool operator==( const TOOL_ACTION_GROUP& aOther ) const
101 {
102 return m_groupID == aOther.m_groupID;
103 }
104
105private:
107 std::string m_name;
108};
109
118{
119public:
120 TOOL_ACTION_ARGS() = default;
121
127 TOOL_ACTION_ARGS& Name( const std::string_view& aName )
128 {
129 m_name = aName;
130 return *this;
131 }
132
133 TOOL_ACTION_ARGS& FriendlyName( const std::string_view& aName )
134 {
135 m_friendlyName = aName;
136 return *this;
137 }
138
143 {
144 m_scope = aScope;
145 return *this;
146 }
147
151 TOOL_ACTION_ARGS& DefaultHotkey( int aDefaultHotkey )
152 {
153 m_defaultHotKey = aDefaultHotkey;
154 return *this;
155 }
156
160 TOOL_ACTION_ARGS& DefaultHotkeyAlt( int aDefaultHotkeyAlt )
161 {
162 m_defaultHotKeyAlt = aDefaultHotkeyAlt;
163 return *this;
164 }
165
171 TOOL_ACTION_ARGS& LegacyHotkeyName( const std::string_view& aLegacyName )
172 {
173 m_legacyName = aLegacyName;
174 return *this;
175 }
176
180 TOOL_ACTION_ARGS& MenuText( const std::string_view& aMenuText )
181 {
182 m_menuText = aMenuText;
183 return *this;
184 }
185
189 TOOL_ACTION_ARGS& Tooltip( const std::string_view& aTooltip )
190 {
191 m_tooltip = aTooltip;
192 return *this;
193 }
194
198 TOOL_ACTION_ARGS& Description( const std::string_view& aDescription )
199 {
200 m_description = aDescription;
201 return *this;
202 }
203
208 {
209 m_icon = aIcon;
210 return *this;
211 }
212
217 {
218 m_flags = aFlags;
219 return *this;
220 }
221
225 template<typename T>
227 {
228 m_param = aParam;
229 return *this;
230 }
231
235 TOOL_ACTION_ARGS& UIId( int aUIId )
236 {
237 m_uiid = aUIId;
238 return *this;
239 }
240
242 {
243 m_group = aGroup;
244 return *this;
245 }
246
248 {
250 m_toolbarState.value().set( static_cast<size_t>( aState ) );
251 return *this;
252 }
253
254 TOOL_ACTION_ARGS& ToolbarState( std::initializer_list<TOOLBAR_STATE> aState )
255 {
257
258 for( auto flag : aState )
259 m_toolbarState.value().set( static_cast<size_t>( flag ) );
260
261 return *this;
262 }
263
264protected:
265 // Let the TOOL_ACTION constructor have direct access to the members here
266 friend class TOOL_ACTION;
267
268 std::optional<std::string_view> m_name;
269 std::optional<std::string_view> m_friendlyName;
270 std::optional<TOOL_ACTION_SCOPE> m_scope;
271 std::optional<TOOL_ACTION_FLAGS> m_flags;
272
273 std::optional<int> m_uiid;
274
275 std::optional<int> m_defaultHotKey;
276 std::optional<int> m_defaultHotKeyAlt;
277 std::optional<std::string_view> m_legacyName;
278
279 std::optional<std::string_view> m_menuText;
280 std::optional<std::string_view> m_tooltip;
281 std::optional<std::string_view> m_description;
282
283 std::optional<BITMAPS> m_icon;
284
285 std::optional<TOOL_ACTION_GROUP> m_group;
286
287 std::optional<TOOLBAR_STATE_FLAGS> m_toolbarState;
288
290};
291
304{
305public:
306 TOOL_ACTION( const TOOL_ACTION_ARGS& aArgs );
307 TOOL_ACTION( const std::string& aName, TOOL_ACTION_SCOPE aScope = AS_CONTEXT,
308 int aDefaultHotKey = 0, const std::string& aLegacyHotKeyName = "",
309 const wxString& aMenuText = wxEmptyString,
310 const wxString& aTooltip = wxEmptyString,
311 BITMAPS aIcon = static_cast<BITMAPS>( 0 ), TOOL_ACTION_FLAGS aFlags = AF_NONE );
312
313 ~TOOL_ACTION();
314
315 // TOOL_ACTIONS are singletons; don't be copying them around....
316 TOOL_ACTION( const TOOL_ACTION& ) = delete;
317 TOOL_ACTION& operator= ( const TOOL_ACTION& ) = delete;
318
319 bool operator==( const TOOL_ACTION& aRhs ) const
320 {
321 return m_id == aRhs.m_id;
322 }
323
324 bool operator!=( const TOOL_ACTION& aRhs ) const
325 {
326 return m_id != aRhs.m_id;
327 }
328
337 const std::string& GetName() const { return m_name; }
338
342 int GetDefaultHotKey() const { return m_defaultHotKey; }
344
348 int GetHotKey() const { return m_hotKey; }
349 int GetHotKeyAlt() const { return m_hotKeyAlt; }
350 void SetHotKey( int aKeycode, int aKeycodeAlt = 0 );
351
359 int GetId() const { return m_id; }
360
364 bool HasCustomUIId() const { return m_uiid.has_value(); }
365
374 int GetUIId() const { return m_uiid.value_or( m_id + ACTION_BASE_UI_ID ); }
375
379 static int GetBaseUIId() { return ACTION_BASE_UI_ID; }
380
385 TOOL_EVENT MakeEvent() const;
386
390 wxString GetMenuLabel() const;
391 wxString GetMenuItem() const;
392 wxString GetTooltip( bool aIncludeHotkey = true ) const;
393 wxString GetButtonTooltip() const;
394 wxString GetDescription() const;
395
399 wxString GetFriendlyName() const;
400
402
406 template<typename T>
407 T GetParam() const
408 {
409 wxASSERT_MSG( m_param.has_value(),
410 "Attempted to get a parameter from an action with no parameter." );
411
412 T param;
413
414 try
415 {
416 param = ki::any_cast<T>( m_param );
417 }
418 catch( const ki::bad_any_cast& e )
419 {
420 wxASSERT_MSG( false,
421 wxString::Format( "Requested parameter type %s from action with "
422 "parameter type %s.",
423 typeid(T).name(), m_param.type().name() ) );
424 }
425
426 return param;
427 }
428
429 const std::optional<TOOL_ACTION_GROUP> GetActionGroup() const { return m_group; }
430
436 std::string GetToolName() const;
437
441 bool IsActivation() const
442 {
443 return m_flags & AF_ACTIVATE;
444 }
445
449 bool IsNotification() const
450 {
451 return m_flags & AF_NOTIFY;
452 }
453
460 {
461 // The value of 0 corresponds to BITMAPS::INVALID_BITMAP, but is just
462 // used here to make it so we don't need to include the full list in this
463 // header.
464 return m_icon.value_or( static_cast<BITMAPS>( 0 ) );
465 }
466
473 bool CheckToolbarState( TOOLBAR_STATE aState ) const
474 {
475 return m_toolbarState[static_cast<std::size_t>( aState )];
476 }
477
478
479protected:
480 TOOL_ACTION();
481
482 friend class ACTION_MANAGER;
483
485 static constexpr int ACTION_BASE_UI_ID = 20000;
486
488 std::string m_name;
490
491 std::optional<TOOL_ACTION_GROUP> m_group;
492
493 const int m_defaultHotKey;
496
499 const std::string m_legacyName;
500
501 wxString m_friendlyName;
502 std::optional<wxString> m_menuLabel;
503 wxString m_tooltip;
504 std::optional<wxString> m_description;
505
506 std::optional<BITMAPS> m_icon;
507
508 int m_id;
509 std::optional<int> m_uiid;
510
512
515};
516
517#endif
const char * name
BITMAPS
A list of all bitmap identifiers.
@ HIDDEN
Inactive layers are hidden.
Build up the properties of a TOOL_ACTION in an incremental manner that is static-construction safe.
TOOL_ACTION_ARGS & Parameter(T aParam)
Custom parameter to pass information to the tool.
TOOL_ACTION_ARGS & ToolbarState(std::initializer_list< TOOLBAR_STATE > aState)
TOOL_ACTION_ARGS & DefaultHotkeyAlt(int aDefaultHotkeyAlt)
The default alternate hotkey to assign to the action.
std::optional< std::string_view > m_description
TOOL_ACTION_ARGS & UIId(int aUIId)
The ID number to use for the action when interacting with any UI elements.
std::optional< int > m_defaultHotKey
TOOL_ACTION_ARGS & Flags(TOOL_ACTION_FLAGS aFlags)
Flags describing the type of the action.
std::optional< std::string_view > m_friendlyName
TOOL_ACTION_ARGS & Scope(TOOL_ACTION_SCOPE aScope)
The scope of the action.
std::optional< int > m_uiid
TOOL_ACTION_ARGS & FriendlyName(const std::string_view &aName)
TOOL_ACTION_ARGS & Icon(BITMAPS aIcon)
The bitmap to use as the icon for the action in toolbars and menus.
std::optional< TOOL_ACTION_GROUP > m_group
friend class TOOL_ACTION
TOOL_ACTION_ARGS & ToolbarState(TOOLBAR_STATE aState)
std::optional< TOOL_ACTION_SCOPE > m_scope
TOOL_ACTION_ARGS & Name(const std::string_view &aName)
The name of the action, the convention is "app.tool.actionName".
std::optional< std::string_view > m_tooltip
TOOL_ACTION_ARGS & Group(const TOOL_ACTION_GROUP &aGroup)
TOOL_ACTION_ARGS & DefaultHotkey(int aDefaultHotkey)
The default hotkey to assign to the action.
TOOL_ACTION_ARGS & MenuText(const std::string_view &aMenuText)
The string to use when displaying the action in a menu.
std::optional< std::string_view > m_name
std::optional< TOOL_ACTION_FLAGS > m_flags
TOOL_ACTION_ARGS & Description(const std::string_view &aDescription)
The description of the action.
std::optional< std::string_view > m_legacyName
TOOL_ACTION_ARGS & LegacyHotkeyName(const std::string_view &aLegacyName)
The legacy hotkey name from the old system.
std::optional< BITMAPS > m_icon
TOOL_ACTION_ARGS()=default
std::optional< TOOLBAR_STATE_FLAGS > m_toolbarState
TOOL_ACTION_ARGS & Tooltip(const std::string_view &aTooltip)
The string to use as a tooltip for the action in menus and toolbars.
std::optional< int > m_defaultHotKeyAlt
std::optional< std::string_view > m_menuText
Define a group that can be used to group actions (and their events) of similar operations.
Definition tool_action.h:79
bool operator==(const TOOL_ACTION_GROUP &aOther) const
TOOL_ACTION_GROUP(std::string aName)
Definition tool_action.h:81
const std::string & GetName() const
Definition tool_action.h:98
std::string m_name
TOOL_ACTION_GROUP(const TOOL_ACTION_GROUP &aOther)
Definition tool_action.h:89
int GetGroupID() const
Definition tool_action.h:97
int m_id
Unique ID for maps. Assigned by ACTION_MANAGER.
bool HasCustomUIId() const
Return true if this action has a custom UI ID set.
std::optional< wxString > m_description
Description of the action.
TOOL_ACTION(const TOOL_ACTION_ARGS &aArgs)
TOOL_ACTION & operator=(const TOOL_ACTION &)=delete
static int GetBaseUIId()
Get the base value used to offset the user interface IDs for the actions.
wxString GetMenuLabel() const
Return the translated label for the action.
wxString GetTooltip(bool aIncludeHotkey=true) const
std::optional< wxString > m_menuLabel
Menu label.
BITMAPS GetIcon() const
Return an icon associated with the action.
TOOL_ACTION_SCOPE m_scope
bool operator!=(const TOOL_ACTION &aRhs) const
bool IsActivation() const
Return true if the action is intended to activate a tool.
bool operator==(const TOOL_ACTION &aRhs) const
TOOL_ACTION_FLAGS m_flags
void SetHotKey(int aKeycode, int aKeycodeAlt=0)
int GetDefaultHotKeyAlt() const
TOOL_ACTION_SCOPE GetScope() const
std::string GetToolName() const
Return name of the tool associated with the action.
std::optional< int > m_uiid
ID to use when interacting with the UI (if empty, generate one).
wxString m_friendlyName
User-friendly name.
int GetId() const
Return the unique id of the TOOL_ACTION object.
bool IsNotification() const
Return true if the action is a notification.
const std::optional< TOOL_ACTION_GROUP > GetActionGroup() const
const std::string & GetName() const
Return name of the action.
std::optional< BITMAPS > m_icon
Icon for the menu entry.
wxString m_tooltip
User facing tooltip help text.
int m_hotKeyAlt
The alternate hotkey (post-user-settings-application).
TOOL_ACTION(const TOOL_ACTION &)=delete
TOOLBAR_STATE_FLAGS m_toolbarState
Toolbar state behavior for the action.
wxString GetDescription() const
bool CheckToolbarState(TOOLBAR_STATE aState) const
Check if a specific toolbar state is required for this action.
int GetHotKeyAlt() const
wxString GetMenuItem() const
T GetParam() const
Return a non-standard parameter assigned to the action.
int GetHotKey() const
Return the hotkey keycode which initiates the action.
ki::any m_param
Generic parameter.
const int m_defaultHotKey
Default hot key.
int m_hotKey
The current hotkey (post-user-settings-application).
TOOL_EVENT MakeEvent() const
Return the event associated with the action (i.e.
static constexpr int ACTION_BASE_UI_ID
Base ID to use inside the user interface system to offset the action IDs.
int GetDefaultHotKey() const
Return the default hotkey (if any) for the action.
const std::string m_legacyName
Name for reading legacy hotkey settings.
std::string m_name
Name of the action (convention is "app.tool.actionName")
wxString GetFriendlyName() const
Return the translated user-friendly name of the action.
friend class ACTION_MANAGER
wxString GetButtonTooltip() const
std::optional< TOOL_ACTION_GROUP > m_group
Optional group for the action to belong to.
int GetUIId() const
Get the unique ID for this action in the user interface system.
const int m_defaultHotKeyAlt
Default hot key alternate.
Generic, UI-independent tool event.
Definition tool_event.h:171
A type-safe container of any type.
Definition ki_any.h:93
Exception class thrown by a failed any_cast.
Definition ki_any.h:81
An implementation of std::any_cast, which uses type_info::hash_code to check validity of cast types.
ValueType any_cast(const any &any)
Access the contained object.
Definition ki_any.h:446
TOOLBAR_STATE
Flags that control how actions appear and interact on the toolbar.
Definition tool_action.h:62
@ TOGGLE
Action is a toggle button on the toolbar.
Definition tool_action.h:64
@ CANCEL
Action can be cancelled by clicking the toolbar button again.
Definition tool_action.h:65
TOOL_ACTION_SCOPE
Scope of tool actions.
Definition tool_action.h:46
@ AS_GLOBAL
Global action (toolbar/main menu event, global shortcut)
Definition tool_action.h:49
@ AS_ACTIVE
All active tools.
Definition tool_action.h:48
@ AS_CONTEXT
Action belongs to a particular tool (i.e. a part of a pop-up menu)
Definition tool_action.h:47
std::bitset< gToolbarStateNumber > TOOLBAR_STATE_FLAGS
Definition tool_action.h:73
const size_t gToolbarStateNumber
Definition tool_action.h:71
TOOL_ACTION_FLAGS
Flags for tool actions.
Definition tool_action.h:54
@ AF_ACTIVATE
Action activates a tool.
Definition tool_action.h:56
@ AF_NOTIFY
Action is a notification (it is by default passed to all tools)
Definition tool_action.h:57
@ AF_NONE
Definition tool_action.h:55