1 /* 2 * This program source code file is part of KiCad, a free EDA CAD application. 3 * 4 * Copyright (C) 2013-2017 CERN 5 * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. 6 * 7 * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch> 8 * @author Maciej Suminski <maciej.suminski@cern.ch> 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 __CONTEXT_MENU_H 29 #define __CONTEXT_MENU_H 30 31 #include <map> 32 #include <list> 33 #include <functional> 34 35 #include <wx/menu.h> 36 #include <wx/textentry.h> 37 #include <tool/tool_event.h> 38 39 class KIFACE_BASE; 40 class TOOL_INTERACTIVE; 41 class TOOL_MANAGER; 42 43 enum class BITMAPS : unsigned int; 44 45 /** 46 * Defines the structure of a menu based on ACTIONs. 47 */ 48 class ACTION_MENU : public wxMenu 49 { 50 public: 51 ///< Default constructor 52 ACTION_MENU( bool isContextMenu, TOOL_INTERACTIVE* aTool = nullptr ); 53 54 ~ACTION_MENU() override; 55 56 ACTION_MENU( const ACTION_MENU& aMenu ) = delete; 57 ACTION_MENU& operator=( const ACTION_MENU& aMenu ) = delete; 58 59 /** 60 * Set title for the menu. The title is shown as a text label shown on the top of 61 * the menu. 62 * 63 * @param aTitle is the new title. 64 */ 65 void SetTitle( const wxString& aTitle ) override; 66 67 /** 68 * Decide whether a title for a pop up menu should be displayed. 69 */ 70 void DisplayTitle( bool aDisplay = true ); 71 72 /** 73 * Assign an icon for the entry. 74 * 75 * @param aIcon is the icon to be assigned. NULL is used to remove icon. 76 */ 77 void SetIcon( BITMAPS aIcon ); 78 79 /** 80 * Add a wxWidgets-style entry to the menu. 81 * 82 * After highlighting/selecting the entry, a wxWidgets event is generated. 83 */ 84 wxMenuItem* Add( const wxString& aLabel, int aId, BITMAPS aIcon ); 85 wxMenuItem* Add( const wxString& aLabel, const wxString& aToolTip, int aId, 86 BITMAPS aIcon, bool aIsCheckmarkEntry = false ); 87 88 /** 89 * Add an entry to the menu based on the #TOOL_ACTION object. 90 * 91 * After selecting the entry, a #TOOL_EVENT command containing name of the action is sent. 92 * 93 * @param aAction is the action to be added to menu entry. 94 * @param aIsCheckmarkEntry is true to indicate a check menu entry, false for normal menu entry 95 * @param aOverrideLabel is the label to show in the menu (overriding the action's menu text) 96 * when non-empty 97 */ 98 wxMenuItem* Add( const TOOL_ACTION& aAction, bool aIsCheckmarkEntry = false, 99 const wxString& aOverrideLabel = wxEmptyString ); 100 101 /** 102 * Add an action menu as a submenu. 103 * 104 * The difference between this function and wxMenu::AppendSubMenu() is the capability to 105 * handle icons. 106 * 107 * @param aMenu is the submenu to be added. 108 */ 109 wxMenuItem* Add( ACTION_MENU* aMenu ); 110 111 /** 112 * Add a standard close item to the menu with the accelerator key CTRL-W. 113 * 114 * Emits the wxID_CLOSE event. 115 * 116 * @param aAppname is the application name to append to the tooltip. 117 */ 118 void AddClose( const wxString& aAppname = "" ); 119 120 /** 121 * Add either a standard Quit or Close item to the menu. 122 * 123 * If \a aKiface is NULL or in single-instance then quit (wxID_QUIT) is used, otherwise 124 * close (wxID_CLOSE) is used. 125 * 126 * @param aAppname is the application name to append to the tooltip. 127 */ 128 void AddQuitOrClose( KIFACE_BASE* aKiface, wxString aAppname = "" ); 129 130 /** 131 * Remove all the entries from the menu (as well as its title). 132 * 133 * It leaves the menu in the initial state. 134 */ 135 void Clear(); 136 137 /** 138 * Returns true if the menu has any enabled items 139 */ 140 bool HasEnabledItems() const; 141 142 /** 143 * Return the position of selected item. 144 * 145 * If the returned value is negative, that means that menu was dismissed. 146 * 147 * @return The position of selected item in the action menu. 148 */ GetSelected()149 inline int GetSelected() const 150 { 151 return m_selected; 152 } 153 154 /** 155 * Run update handlers for the menu and its submenus. 156 */ 157 void UpdateAll(); 158 159 /** 160 * Clear the dirty flag on the menu and all descendants. 161 */ 162 void ClearDirty(); 163 void SetDirty(); 164 165 /** 166 * Set a tool that is the creator of the menu. 167 * 168 * @param aTool is the tool that created the menu. 169 */ 170 void SetTool( TOOL_INTERACTIVE* aTool ); 171 172 /** 173 * Create a deep, recursive copy of this ACTION_MENU. 174 */ 175 ACTION_MENU* Clone() const; 176 177 void OnMenuEvent( wxMenuEvent& aEvent ); 178 void OnIdle( wxIdleEvent& event ); 179 PassHelpTextToHandler()180 virtual bool PassHelpTextToHandler() { return false; } 181 182 static constexpr bool NORMAL = false; 183 static constexpr bool CHECK = true; 184 185 protected: 186 ///< Return an instance of this class. It has to be overridden in inheriting classes. 187 virtual ACTION_MENU* create() const; 188 189 ///< Returns an instance of TOOL_MANAGER class. 190 TOOL_MANAGER* getToolManager() const; 191 192 /** 193 * Update menu state stub. 194 * 195 * It is called before a menu is shown, in order to update its state. Here you can tick 196 * current settings, enable/disable entries, etc. 197 */ update()198 virtual void update() 199 { 200 } 201 202 /** 203 * Event handler stub. 204 * 205 * It should be used if you want to generate a #TOOL_EVENT from a wxMenuEvent. It will be 206 * called when a menu entry is clicked. 207 */ eventHandler(const wxMenuEvent &)208 virtual OPT_TOOL_EVENT eventHandler( const wxMenuEvent& ) 209 { 210 return OPT_TOOL_EVENT(); 211 } 212 213 /** 214 * Copy another menus data to this instance. 215 * 216 * Old entries are preserved and ones form aMenu are copied. 217 */ 218 void copyFrom( const ACTION_MENU& aMenu ); 219 220 protected: 221 /** 222 * Append a copy of wxMenuItem. 223 */ 224 wxMenuItem* appendCopy( const wxMenuItem* aSource ); 225 226 ///< Initialize handlers for events. 227 void setupEvents(); 228 229 ///< Update hot key settings for TOOL_ACTIONs in this menu. 230 void updateHotKeys(); 231 232 ///< Traverse the submenus tree looking for a submenu capable of handling a particular menu 233 ///< event. In case it is handled, it is returned the aToolEvent parameter. 234 void runEventHandlers( const wxMenuEvent& aMenuEvent, OPT_TOOL_EVENT& aToolEvent ); 235 236 ///< Run a function on the menu and all its submenus. 237 void runOnSubmenus( std::function<void(ACTION_MENU*)> aFunction ); 238 239 ///< Check if any of submenus contains a TOOL_ACTION with a specific ID. 240 OPT_TOOL_EVENT findToolAction( int aId ); 241 242 bool m_isForcedPosition; 243 wxPoint m_forcedPosition; 244 245 bool m_dirty; // Menu requires update before display 246 247 bool m_titleDisplayed; 248 bool m_isContextMenu; 249 250 ///< Menu title 251 wxString m_title; 252 253 ///< Optional icon 254 BITMAPS m_icon; 255 256 ///< Stores the id number of selected item. 257 int m_selected; 258 259 ///< Creator of the menu 260 TOOL_INTERACTIVE* m_tool; 261 262 ///< Associates tool actions with menu item IDs. Non-owning. 263 std::map<int, const TOOL_ACTION*> m_toolActions; 264 265 ///< List of submenus. 266 std::list<ACTION_MENU*> m_submenus; 267 268 friend class TOOL_INTERACTIVE; 269 }; 270 271 #endif 272