diff --git a/include/tool/action_manager.h b/include/tool/action_manager.h index a96575619a..6e45c192ff 100644 --- a/include/tool/action_manager.h +++ b/include/tool/action_manager.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -40,15 +42,11 @@ class TOOL_ACTION; * Functors that can be used to figure out how the action controls should be displayed in the UI * and if an action should be enabled given the current selection. * - * @note @c checkCondition is also used for determing the state of a toggled toolbar item + * @note @c checkCondition is also used for determining the state of a toggled toolbar item * (the item is toggled when the condition is true). */ struct ACTION_CONDITIONS { - SELECTION_CONDITION checkCondition; ///< Returns true if the UI control should be checked - SELECTION_CONDITION enableCondition; ///< Returns true if the UI control should be enabled - SELECTION_CONDITION showCondition; ///< Returns true if the UI control should be shown - ACTION_CONDITIONS() { checkCondition = SELECTION_CONDITIONS::ShowNever; // Never check by default @@ -73,13 +71,16 @@ struct ACTION_CONDITIONS showCondition = aCondition; return *this; } + + SELECTION_CONDITION checkCondition; ///< Returns true if the UI control should be checked + SELECTION_CONDITION enableCondition; ///< Returns true if the UI control should be enabled + SELECTION_CONDITION showCondition; ///< Returns true if the UI control should be shown }; /** - * ACTION_MANAGER + * Manage #TOOL_ACTION objects. * - * Takes care of TOOL_ACTION objects. Registers them and allows one to run them - * using associated hot keys, names or ids. + * Registering them and allows one to run them using associated hot keys, names or ids. */ class ACTION_MANAGER { @@ -90,12 +91,12 @@ public: ACTION_MANAGER( TOOL_MANAGER* aToolManager ); /** - * Unregisters every registered action. + * Unregister every registered action. */ ~ACTION_MANAGER(); /** - * Adds a tool action to the manager and sets it up. After that is is possible to invoke + * Add a tool action to the manager and sets it up. After that is is possible to invoke * the action using hotkeys or sending a command event with its name. * * @param aAction: action to be added. Ownership is not transferred. @@ -103,7 +104,7 @@ public: void RegisterAction( TOOL_ACTION* aAction ); /** - * Generates an unique ID from for an action with given name. + * Generate an unique ID from for an action with given name. */ static int MakeActionId( const std::string& aActionName ); @@ -113,7 +114,7 @@ public: const std::map& GetActions() const; /** - * Finds an action with a given name (if there is one available). + * Find an action with a given name (if there is one available). * * @param aActionName is the searched action. * @return Pointer to a TOOL_ACTION object or NULL if there is no such action. @@ -121,7 +122,7 @@ public: TOOL_ACTION* FindAction( const std::string& aActionName ) const; /** - * Runs an action associated with a hotkey (if there is one available). + * Run an action associated with a hotkey (if there is one available). * * @param aHotKey is the hotkey to be handled. * @return True if there was an action associated with the hotkey, false otherwise. @@ -129,20 +130,22 @@ public: bool RunHotKey( int aHotKey ) const; /** - * Returns the hot key associated with a given action or 0 if there is none. + * Return the hot key associated with a given action or 0 if there is none. * * @param aAction is the queried action. */ int GetHotKey( const TOOL_ACTION& aAction ) const; /** - * Optionally reads the hotkey config files and then rebuilds the internal hotkey maps. + * Optionally read the hotkey config files and then rebuilds the internal hotkey maps. */ void UpdateHotKeys( bool aFullUpdate ); /** - * Returns list of TOOL_ACTIONs. TOOL_ACTIONs add themselves to the list upon their - * creation. + * Return list of TOOL_ACTIONs. + * + * #TOOL_ACTIONs add themselves to the list upon their creation. + * * @return List of TOOL_ACTIONs. */ static std::list& GetActionList() @@ -156,36 +159,36 @@ public: * Set the conditions the UI elements for activating a specific tool action should use * for determining the current UI state (e.g. checked, enabled, shown) * - * @param aAction is the tool action using these conditions - * @param aConditions are the conditions to use for the action + * @param aAction is the tool action using these conditions. + * @param aConditions are the conditions to use for the action. */ void SetConditions( const TOOL_ACTION& aAction, const ACTION_CONDITIONS& aConditions ); /** * Get the conditions to use for a specific tool action. * - * @param aAction is the tool action - * @return the action conditions, returns nullptr if no conditions are registered + * @param aAction is the tool action. + * @return the action conditions, returns nullptr if no conditions are registered. */ const ACTION_CONDITIONS* GetCondition( const TOOL_ACTION& aAction ) const; private: - // Resolves a hotkey by applying legacy and current settings over the action's + // Resolve a hotkey by applying legacy and current settings over the action's // default hotkey. int processHotKey( TOOL_ACTION* aAction, std::map aLegacyMap, std::map aHotKeyMap ); - ///> Tool manager needed to run actions + ///< Tool manager needed to run actions TOOL_MANAGER* m_toolMgr; - ///> Map for indexing actions by their names + ///< Map for indexing actions by their names std::map m_actionNameIndex; - ///> Map for indexing actions by their hotkeys + ///< Map for indexing actions by their hotkeys typedef std::map > HOTKEY_LIST; HOTKEY_LIST m_actionHotKeys; - ///> Quick action<->hot key lookup + ///< Quick action<->hot key lookup std::map m_hotkeys; /// Map the command ID that wx uses for the action to the UI conditions for the diff --git a/include/tool/action_menu.h b/include/tool/action_menu.h index cba07c9f18..e0de6c3b60 100644 --- a/include/tool/action_menu.h +++ b/include/tool/action_menu.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2017 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -43,7 +45,7 @@ class TOOL_INTERACTIVE; class ACTION_MENU : public wxMenu { public: - ///> Default constructor + ///< Default constructor ACTION_MENU( bool isContextMenu, TOOL_INTERACTIVE* aTool = nullptr ); ~ACTION_MENU() override; @@ -52,7 +54,7 @@ public: ACTION_MENU& operator=( const ACTION_MENU& aMenu ) = delete; /** - * Sets title for the menu. The title is shown as a text label shown on the top of + * Set title for the menu. The title is shown as a text label shown on the top of * the menu. * * @param aTitle is the new title. @@ -60,36 +62,40 @@ public: void SetTitle( const wxString& aTitle ) override; /** - * Decides whether a title for a pop up menu should be displayed. + * Decide whether a title for a pop up menu should be displayed. */ void DisplayTitle( bool aDisplay = true ); /** - * Assigns an icon for the entry. + * Assign an icon for the entry. * * @param aIcon is the icon to be assigned. NULL is used to remove icon. */ void SetIcon( const BITMAP_OPAQUE* aIcon ); /** - * Adds a wxWidgets-style entry to the menu. After highlighting/selecting the entry, - * a wxWidgets event is generated. + * Add a wxWidgets-style entry to the menu. + * + * After highlighting/selecting the entry, a wxWidgets event is generated. */ wxMenuItem* Add( const wxString& aLabel, int aId, const BITMAP_OPAQUE* aIcon ); wxMenuItem* Add( const wxString& aLabel, const wxString& aToolTip, int aId, const BITMAP_OPAQUE* aIcon, bool aIsCheckmarkEntry = false ); /** - * Adds an entry to the menu, basing on the TOOL_ACTION object. After selecting the entry, - * a TOOL_EVENT command containing name of the action is sent. + * Add an entry to the menu based on the #TOOL_ACTION object. + * + * After selecting the entry, a #TOOL_EVENT command containing name of the action is sent. * * @param aAction is the action to be added to menu entry. */ wxMenuItem* Add( const TOOL_ACTION& aAction, bool aIsCheckmarkEntry = false ); /** - * Adds an action menu as a submenu. The difference between this function and - * wxMenu::AppendSubMenu() is the capability to handle icons. + * Add an action menu as a submenu. + * + * The difference between this function and wxMenu::AppendSubMenu() is the capability to + * handle icons. * * @param aMenu is the submenu to be added. */ @@ -97,23 +103,27 @@ public: /** * Add a standard close item to the menu with the accelerator key CTRL-W. + * * Emits the wxID_CLOSE event. * - * @param aAppname is the application name to append to the tooltip + * @param aAppname is the application name to append to the tooltip. */ void AddClose( wxString aAppname = "" ); /** - * Adds either a standard Quit or Close item to the menu. If aKiface is NULL or in - * single-instance then Quite (wxID_QUIT) is used, otherwise Close (wxID_CLOSE) is used. + * Add either a standard Quit or Close item to the menu. * - * @param aAppname is the application name to append to the tooltip + * If \a aKiface is NULL or in single-instance then quit (wxID_QUIT) is used, otherwise + * close (wxID_CLOSE) is used. + * + * @param aAppname is the application name to append to the tooltip. */ void AddQuitOrClose( KIFACE_I* aKiface, wxString aAppname = "" ); /** - * Removes all the entries from the menu (as well as its title). It leaves the menu in the - * initial state. + * Remove all the entries from the menu (as well as its title). + * + * It leaves the menu in the initial state. */ void Clear(); @@ -123,8 +133,9 @@ public: bool HasEnabledItems() const; /** - * Returns the position of selected item. If the returned value is negative, that means that - * menu was dismissed. + * Return the position of selected item. + * + * If the returned value is negative, that means that menu was dismissed. * * @return The position of selected item in the action menu. */ @@ -134,25 +145,25 @@ public: } /** - * Runs update handlers for the menu and its submenus. + * Run update handlers for the menu and its submenus. */ void UpdateAll(); /** - * Clears the dirty flag on the menu and all descendants. + * Clear the dirty flag on the menu and all descendants. */ void ClearDirty(); void SetDirty(); /** - * Sets a tool that is the creator of the menu. + * Set a tool that is the creator of the menu. * * @param aTool is the tool that created the menu. */ void SetTool( TOOL_INTERACTIVE* aTool ); /** - * Creates a deep, recursive copy of this ACTION_MENU. + * Create a deep, recursive copy of this ACTION_MENU. */ ACTION_MENU* Clone() const; @@ -162,23 +173,27 @@ public: static constexpr bool CHECK = true; protected: - ///> Returns an instance of this class. It has to be overridden in inheriting classes. + ///< Return an instance of this class. It has to be overridden in inheriting classes. virtual ACTION_MENU* create() const; - ///> Returns an instance of TOOL_MANAGER class. + ///< Returns an instance of TOOL_MANAGER class. TOOL_MANAGER* getToolManager() const; /** - * Update menu state stub. It is called before a menu is shown, in order to update its state. - * Here you can tick current settings, enable/disable entries, etc. + * Update menu state stub. + * + * It is called before a menu is shown, in order to update its state. Here you can tick + * current settings, enable/disable entries, etc. */ virtual void update() { } /** - * Event handler stub. It should be used if you want to generate a TOOL_EVENT from a wxMenuEvent. - * It will be called when a menu entry is clicked. + * Event handler stub. + * + * It should be used if you want to generate a #TOOL_EVENT from a wxMenuEvent. It will be + * called when a menu entry is clicked. */ virtual OPT_TOOL_EVENT eventHandler( const wxMenuEvent& ) { @@ -186,32 +201,32 @@ protected: } /** - * Copies another menus data to this instance. Old entries are preserved, and ones form aMenu - * are copied. + * Copy another menus data to this instance. + * + * Old entries are preserved and ones form aMenu are copied. */ void copyFrom( const ACTION_MENU& aMenu ); protected: /** - * Function appendCopy - * Appends a copy of wxMenuItem. + * Append a copy of wxMenuItem. */ wxMenuItem* appendCopy( const wxMenuItem* aSource ); - ///> Initializes handlers for events. + ///< Initialize handlers for events. void setupEvents(); - ///> Updates hot key settings for TOOL_ACTIONs in this menu. + ///< Update hot key settings for TOOL_ACTIONs in this menu. void updateHotKeys(); - ///> Traverses the submenus tree looking for a submenu capable of handling a particular menu - ///> event. In case it is handled, it is returned the aToolEvent parameter. + ///< Traverse the submenus tree looking for a submenu capable of handling a particular menu + ///< event. In case it is handled, it is returned the aToolEvent parameter. void runEventHandlers( const wxMenuEvent& aMenuEvent, OPT_TOOL_EVENT& aToolEvent ); - ///> Runs a function on the menu and all its submenus. + ///< Run a function on the menu and all its submenus. void runOnSubmenus( std::function aFunction ); - ///> Checks if any of submenus contains a TOOL_ACTION with a specific ID. + ///< Check if any of submenus contains a TOOL_ACTION with a specific ID. OPT_TOOL_EVENT findToolAction( int aId ); bool m_isForcedPosition; @@ -222,22 +237,22 @@ protected: bool m_titleDisplayed; bool m_isContextMenu; - ///> Menu title + ///< Menu title wxString m_title; - ///> Optional icon + ///< Optional icon const BITMAP_OPAQUE* m_icon; - ///> Stores the id number of selected item. + ///< Stores the id number of selected item. int m_selected; - ///> Creator of the menu + ///< Creator of the menu TOOL_INTERACTIVE* m_tool; - ///> Associates tool actions with menu item IDs. Non-owning. + ///< Associates tool actions with menu item IDs. Non-owning. std::map m_toolActions; - ///> List of submenus. + ///< List of submenus. std::list m_submenus; friend class TOOL_INTERACTIVE; diff --git a/include/tool/action_toolbar.h b/include/tool/action_toolbar.h index e3b4e988ef..330b1f1cef 100644 --- a/include/tool/action_toolbar.h +++ b/include/tool/action_toolbar.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see CHANGELOG.txt for contributors. + * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -54,6 +54,7 @@ public: /** * Set the default action to use when first creating the toolbar palette icon. + * * If no default action is provided, the default will be the first action in the * vector. * @@ -82,16 +83,16 @@ public: const std::vector< const TOOL_ACTION*>& GetActions() const { return m_actions; } protected: - ///> The action ID for this action group + ///< The action ID for this action group int m_id; - ///> The name of this action group + ///< The name of this action group std::string m_name; - ///> The default action to display on the toolbar item + ///< The default action to display on the toolbar item const TOOL_ACTION* m_defaultAction; - ///> The actions that compose the group + ///< The actions that compose the group std::vector m_actions; }; @@ -107,7 +108,7 @@ public: * * @param aParent is the parent window * @param aVertical is true if the palette should make the buttons a vertical line, - * false for a horizonatl line. + * false for a horizontal line. */ ACTION_TOOLBAR_PALETTE( wxWindow* aParent, bool aVertical ); @@ -159,29 +160,26 @@ public: protected: void onCharHook( wxKeyEvent& aEvent ); -protected: // The group that the buttons in the palette are part of ACTION_GROUP* m_group; - ///> The size each button on the toolbar should be + ///< The size each button on the toolbar should be wxRect m_buttonSize; - ///> True if the palette uses vertical buttons, false for horizontal buttons + ///< True if the palette uses vertical buttons, false for horizontal buttons bool m_isVertical; wxPanel* m_panel; wxBoxSizer* m_mainSizer; wxBoxSizer* m_buttonSizer; - ///> The buttons that act as the toolbar on the palette + ///< The buttons that act as the toolbar on the palette std::map m_buttons; }; /** - * ACTION_TOOLBAR - * - * Defines the structure of a toolbar with buttons that invoke ACTIONs. + * Define the structure of a toolbar with buttons that invoke ACTIONs. */ class ACTION_TOOLBAR : public wxAuiToolBar { @@ -200,18 +198,19 @@ public: void SetAuiManager( wxAuiManager* aManager ) { m_auiManager = aManager; } /** - * Adds a TOOL_ACTION-based button to the toolbar. After selecting the entry, - * a TOOL_EVENT command containing name of the action is sent. + * Add a TOOL_ACTION-based button to the toolbar. * - * @param aAction is the action to add - * @param aIsToggleEntry makes the toolbar item a toggle entry when true - * @param aIsCancellable when true, cancels the tool if clicked when tool is active + * After selecting the entry, a #TOOL_EVENT command containing name of the action is sent. + * + * @param aAction is the action to add. + * @param aIsToggleEntry makes the toolbar item a toggle entry when true. + * @param aIsCancellable when true, cancels the tool if clicked when tool is active. */ void Add( const TOOL_ACTION& aAction, bool aIsToggleEntry = false, bool aIsCancellable = false ); /** - * Adds a large button such as used in the Kicad Manager Frame's launch bar. + * Add a large button such as used in the KiCad Manager Frame's launch bar. * * @param aAction */ @@ -227,6 +226,7 @@ public: /** * Add a context menu to a specific tool item on the toolbar. + * * This toolbar gets ownership of the menu object, and will delete it when the * ClearToolbar() function is called. * @@ -239,7 +239,8 @@ public: * Add a set of actions to a toolbar as a group. One action from the group will be displayed * at a time. * - * @param aGroup is the group to add. The first action in the group will be the first shown on the toolbar. + * @param aGroup is the group to add. The first action in the group will be the first shown + * on the toolbar. * @param aIsToggleEntry makes the toolbar item a toggle entry when true */ void AddGroup( ACTION_GROUP* aGroup, bool aIsToggleEntry = false ); @@ -258,14 +259,16 @@ public: void ClearToolbar(); /** - * Updates the bitmap of a particular tool. Not icon-based because we use it - * for the custom-drawn layer pair bitmap. + * Updates the bitmap of a particular tool. + * + * Not icon-based because we use it for the custom-drawn layer pair bitmap. */ void SetToolBitmap( const TOOL_ACTION& aAction, const wxBitmap& aBitmap ); /** - * Applies the default toggle action. For checked items this is check/uncheck; for - * non-checked items it's enable/disable. + * Apply the default toggle action. + * + * For checked items this is check/uncheck; for non-checked items it's enable/disable. */ void Toggle( const TOOL_ACTION& aAction, bool aState ); @@ -276,7 +279,8 @@ public: * * The standard Realize() draws both horizontal and vertical to determine sizing * However with many icons, potato PCs, etc, you can actually see that double draw - * This custom function avoids the double draw if the HORIZONTAL or VERTICAL toolbar properties are set. + * This custom function avoids the double draw if the HORIZONTAL or VERTICAL toolbar + * properties are set. */ bool KiRealize(); @@ -292,33 +296,32 @@ protected: void doSelectAction( ACTION_GROUP* aGroup, const TOOL_ACTION& aAction ); /** - * Popup the ACTION_TOOLBAR_PALETTE associated with the ACTION_GROUP of the + * Popup the #ACTION_TOOLBAR_PALETTE associated with the ACTION_GROUP of the * given toolbar item. */ void popupPalette( wxAuiToolBarItem* aItem ); - ///> Handler for a mouse up/down event + ///< Handler for a mouse up/down event void onMouseClick( wxMouseEvent& aEvent ); - ///> Handler for when a drag event occurs on an item + ///< Handler for when a drag event occurs on an item void onItemDrag( wxAuiToolBarEvent& aEvent ); - ///> The default tool event handler + ///< The default tool event handler void onToolEvent( wxAuiToolBarEvent& aEvent ); - ///> Handle a right-click on a menu item + ///< Handle a right-click on a menu item void onToolRightClick( wxAuiToolBarEvent& aEvent ); - ///> Handle the button select inside the palette + ///< Handle the button select inside the palette void onPaletteEvent( wxCommandEvent& aEvent ); - ///> Handle the palette timer triggering + ///< Handle the palette timer triggering void onTimerDone( wxTimerEvent& aEvent ); - ///> Render the triangle in the lower-right corner that represents that an action pallette - ///> is available for an item - void OnCustomRender( wxDC& aDc, const wxAuiToolBarItem& aItem, - const wxRect& aRect ) override; + ///< Render the triangle in the lower-right corner that represents that an action palette + ///< is available for an item + void OnCustomRender( wxDC& aDc, const wxAuiToolBarItem& aItem, const wxRect& aRect ) override; protected: // Timer used to determine when the palette should be opened after a group item is pressed diff --git a/include/tool/actions.h b/include/tool/actions.h index fe38ce0e21..bb7bf00ef7 100644 --- a/include/tool/actions.h +++ b/include/tool/actions.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN - * Copyright (C) 2016-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -35,10 +35,10 @@ class TOOL_MANAGER; #define LEGACY_HK_NAME( x ) x /** - * ACTIONS + * Gather all the actions that are shared by tools. * - * Gathers all the actions that are shared by tools. The instance of a subclass of - * ACTIONS is created inside of ACTION_MANAGER object that registers the actions. + * The instance of a subclass of ACTIONS is created inside of #ACTION_MANAGER object that + * registers the actions. */ class ACTIONS { @@ -184,28 +184,26 @@ public: static TOOL_ACTION reportBug; /** - * Function TranslateLegacyId() - * Translates legacy tool ids to the corresponding TOOL_ACTION name. + * Translate legacy tool ids to the corresponding TOOL_ACTION name. + * * @param aId is legacy tool id to be translated. * @return std::string is name of the corresponding TOOL_ACTION. It may be empty, if there is - * no corresponding TOOL_ACTION. + * no corresponding TOOL_ACTION. */ virtual OPT TranslateLegacyId( int aId ) = 0; - ///> Cursor control event types + ///< Cursor control event types enum CURSOR_EVENT_TYPE { CURSOR_NONE, CURSOR_UP, CURSOR_DOWN, CURSOR_LEFT, CURSOR_RIGHT, CURSOR_CLICK, CURSOR_DBL_CLICK, CURSOR_RIGHT_CLICK, CURSOR_FAST_MOVE = 0x8000 }; - ///> Remove event modifier flags + ///< Remove event modifier flags enum class REMOVE_FLAGS { NORMAL = 0x00, ALT = 0x01, CUT = 0x02 }; }; /** - * EVENTS - * - * Gathers all the events that are shared by tools. + * Gather all the events that are shared by tools. */ class EVENTS { @@ -214,13 +212,13 @@ public: const static TOOL_EVENT UnselectedEvent; const static TOOL_EVENT ClearedEvent; - //< Selected item had a property changed (except movement) + ///< Selected item had a property changed (except movement) const static TOOL_EVENT SelectedItemsModified; - //< Selected items were moved, this can be very high frequency on the canvas, use with care + ///< Selected items were moved, this can be very high frequency on the canvas, use with care const static TOOL_EVENT SelectedItemsMoved; - ///> Used to inform tools that the selection should temporarily be non-editable + ///< Used to inform tools that the selection should temporarily be non-editable const static TOOL_EVENT InhibitSelectionEditing; const static TOOL_EVENT UninhibitSelectionEditing; }; diff --git a/include/tool/common_control.h b/include/tool/common_control.h index b1e82bcf28..5f27baf9b3 100644 --- a/include/tool/common_control.h +++ b/include/tool/common_control.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -29,9 +29,7 @@ class EDA_BASE_FRAME; /** - * COMMON_CONTROL - * - * Handles actions that are shared between different applications + * Handle actions that are shared between different applications */ class COMMON_CONTROL : public TOOL_INTERACTIVE @@ -49,7 +47,7 @@ public: int ConfigurePaths( const TOOL_EVENT& aEvent ); int ShowLibraryTable( const TOOL_EVENT& aEvent ); - + int ShowPlayer( const TOOL_EVENT& aEvent ); int ShowHelp( const TOOL_EVENT& aEvent ); @@ -57,11 +55,11 @@ public: int GetInvolved( const TOOL_EVENT& aEvent ); int ReportBug( const TOOL_EVENT& aEvent ); - ///> Sets up handlers for various events. + ///< Sets up handlers for various events. void setTransitions() override; - + private: - ///> Pointer to the currently used edit frame. + ///< Pointer to the currently used edit frame. EDA_BASE_FRAME* m_frame; static wxString m_bugReportUrl; diff --git a/include/tool/common_tools.h b/include/tool/common_tools.h index 1823c3db6b..bd31d15c09 100644 --- a/include/tool/common_tools.h +++ b/include/tool/common_tools.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014-2016 CERN + * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -30,11 +32,8 @@ class EDA_DRAW_FRAME; /** - * COMMON_TOOLS - * - * Handles actions that are shared between different applications + * Handles action that are shared between different applications. */ - class COMMON_TOOLS : public TOOL_INTERACTIVE { public: @@ -90,30 +89,29 @@ public: private: /** - * Enum ZOOM_FIT_TYPE_T - * is the set of "Zoom to Fit" types that can be performed + * The set of "Zoom to Fit" types that can be performed. */ enum ZOOM_FIT_TYPE_T { - ZOOM_FIT_ALL, // Zoom to fall all items in view INCLUDING page and border - ZOOM_FIT_OBJECTS, // Zoom to fit all items in view EXCLUDING page and border + ZOOM_FIT_ALL, ///< Zoom to fall all items in view INCLUDING page and border + ZOOM_FIT_OBJECTS, ///< Zoom to fit all items in view EXCLUDING page and border }; - ///> Sets up handlers for various events. + ///< Sets up handlers for various events. void setTransitions() override; - ///> Pointer to the currently used edit frame. + ///< Pointer to the currently used edit frame. EDA_DRAW_FRAME* m_frame; int doZoomInOut( bool aDirection, bool aCenterOnCursor ); - ///> Note: idx == 0 is Auto; idx == 1 is first entry in zoomList + ///< Note: idx == 0 is Auto; idx == 1 is first entry in zoomList int doZoomToPreset( int idx, bool aCenterOnCursor ); int doZoomFit( ZOOM_FIT_TYPE_T aFitType ); - std::vector m_grids; // grids from APP_SETTINGS converted to internal units - // and with the user grid appended + std::vector m_grids; ///< Grids from #APP_SETTINGS converted to internal units + ///< and with the user grid appended. // The last used units in each system (used for toggling between metric and imperial) EDA_UNITS m_imperialUnit; diff --git a/include/tool/conditional_menu.h b/include/tool/conditional_menu.h index 1301c981a7..99073ddc73 100644 --- a/include/tool/conditional_menu.h +++ b/include/tool/conditional_menu.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2015 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -38,7 +40,7 @@ class TOOL_INTERACTIVE; class CONDITIONAL_MENU : public ACTION_MENU { public: - ///> Constant to indicate that we do not care about an ENTRY location in the menu. + ///< Constant to indicate that we do not care about an #ENTRY location in the menu. static const int ANY_ORDER = -1; CONDITIONAL_MENU( TOOL_INTERACTIVE* aTool ); @@ -46,12 +48,12 @@ public: ACTION_MENU* create() const override; /** - * Adds a menu entry to run a TOOL_ACTION on selected items. + * Add a menu entry to run a #TOOL_ACTION on selected items. * * @param aAction is a menu entry to be added. * @param aCondition is a condition that has to be fulfilled to show the menu entry in the menu. * @param aOrder determines location of the added item, higher numbers are put on the bottom. - * You may use ANY_ORDER here if you think it does not matter. + * You may use ANY_ORDER here if you think it does not matter. */ void AddItem( const TOOL_ACTION& aAction, const SELECTION_CONDITION& aCondition, int aOrder = ANY_ORDER ); @@ -60,15 +62,15 @@ public: const SELECTION_CONDITION& aCondition, int aOrder = ANY_ORDER ); /** - * Adds a checked menu entry to run a TOOL_ACTION on selected items. + * Add a checked menu entry to run a TOOL_ACTION on selected items. * - * The condition for checking the menu entry should be supplied through a ACTION_CONDITION - * registered with the ACTION_MANAGER. + * The condition for checking the menu entry should be supplied through a #ACTION_CONDITION + * registered with the #ACTION_MANAGER. * * @param aAction is a menu entry to be added. * @param aCondition is a condition that has to be fulfilled to show the menu entry in the menu. * @param aOrder determines location of the added item, higher numbers are put on the bottom. - * You may use ANY_ORDER here if you think it does not matter. + * You may use #ANY_ORDER here if you think it does not matter. */ void AddCheckItem( const TOOL_ACTION& aAction, const SELECTION_CONDITION& aCondition, int aOrder = ANY_ORDER ); @@ -77,41 +79,43 @@ public: const SELECTION_CONDITION& aCondition, int aOrder = ANY_ORDER ); /** - * Adds a submenu to the menu. CONDITIONAL_MENU takes ownership of the added menu, so it will - * be freed when the CONDITIONAL_MENU object is destroyed. + * Add a submenu to the menu. + * CONDITIONAL_MENU takes ownership of the added menu, so it will be freed when the + * CONDITIONAL_MENU object is destroyed. * * @param aMenu is the submenu to be added. * @param aExpand determines if the added submenu items should be added as individual items - * or as a submenu. - * @param aCondition is a condition that has to be fulfilled to show the submenu entry in the menu. + * or as a submenu. + * @param aCondition is a condition that has to be fulfilled to show the submenu entry in + * the menu. * @param aOrder determines location of the added menu, higher numbers are put on the bottom. - * You may use ANY_ORDER here if you think it does not matter. + * You may use ANY_ORDER here if you think it does not matter. */ void AddMenu( ACTION_MENU* aMenu, const SELECTION_CONDITION& aCondition = SELECTION_CONDITIONS::ShowAlways, int aOrder = ANY_ORDER ); /** - * Adds a separator to the menu. + * Add a separator to the menu. * * @param aOrder determines location of the separator, higher numbers are put on the bottom. */ void AddSeparator( int aOrder = ANY_ORDER ); /** - * Updates the contents of the menu based on the supplied conditions. + * Update the contents of the menu based on the supplied conditions. */ void Evaluate( SELECTION& aSelection ); /** - * Updates the initial contents so that wxWidgets doesn't get its knickers tied in a knot + * Update the initial contents so that wxWidgets doesn't get its knickers tied in a knot * over the menu being empty (mainly an issue on GTK, but also on OSX with the preferences * and quit menu items). */ void Resolve(); private: - ///> Helper class to organize menu entries. + ///< Helper class to organize menu entries. class ENTRY { public: @@ -158,7 +162,7 @@ private: ~ENTRY(); - ///> Possible entry types. + ///< Possible entry types. enum ENTRY_TYPE { ACTION, MENU, @@ -226,19 +230,19 @@ private: wxMenuItem* wxItem; } m_data; - ///> Condition to be fulfilled to show the entry in menu. + ///< Condition to be fulfilled to show the entry in menu. SELECTION_CONDITION m_condition; - ///> Order number, the higher the number the lower position it takes it is in the menu. + ///< Order number, the higher the number the lower position it takes it is in the menu. int m_order; bool m_isCheckmarkEntry; }; - ///> Inserts the entry, preserving the requested order. + ///< Inserts the entry, preserving the requested order. void addEntry( ENTRY aEntry ); - ///> List of all menu entries. + ///< List of all menu entries. std::list m_entries; }; diff --git a/include/tool/coroutine.h b/include/tool/coroutine.h index 24505acc39..55c20bb180 100644 --- a/include/tool/coroutine.h +++ b/include/tool/coroutine.h @@ -2,8 +2,9 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski - * Copyright (C) 2016-2019 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -39,8 +40,9 @@ #include /** - * Class COROUNTINE. - * Implements a coroutine. Wikipedia has a good explanation: + * Implement a coroutine. + * + * Wikipedia has a good explanation: * * "Coroutines are computer program components that generalize subroutines to * allow multiple entry points for suspending and resuming execution at certain locations. @@ -135,8 +137,7 @@ public: } /** - * Constructor - * Creates a coroutine from a member method of an object + * Create a coroutine from a member method of an object. */ template COROUTINE( T* object, ReturnType(T::*ptr)( ArgType ) ) : @@ -145,8 +146,7 @@ public: } /** - * Constructor - * Creates a coroutine from a delegate object + * Create a coroutine from a delegate object. */ COROUTINE( std::function aEntry ) : m_func( std::move( aEntry ) ), @@ -176,9 +176,8 @@ public: public: /** - * Function KiYield() + * Stop execution of the coroutine and returns control to the caller. * - * Stops execution of the coroutine and returns control to the caller. * After a yield, Call() or Resume() methods invoked by the caller will * immediately return true, indicating that we are not done yet, just asleep. */ @@ -188,10 +187,9 @@ public: } /** - * Function KiYield() + * KiYield with a value. * - * KiYield with a value - passes a value of given type to the caller. - * Useful for implementing generator objects. + * Passe a value of given type to the caller. Useful for implementing generator objects. */ void KiYield( ReturnType& aRetVal ) { @@ -200,9 +198,8 @@ public: } /** - * Function RunMainStack() + * Run a functor inside the application main stack context. * - * Run a functor inside the application main stack context * Call this function for example if the operation will spawn a webkit browser instance which * will walk the stack to the upper border of the address space on mac osx systems because * its javascript needs garbage collection (for example if you paste text into an edit box). @@ -214,12 +211,12 @@ public: } /** - * Function Call() + * Start execution of a coroutine, passing args as its arguments. * - * Starts execution of a coroutine, passing args as its arguments. Call this method - * from the application main stack only. - * @return true, if the coroutine has yielded and false if it has finished its - * execution (returned). + * Call this method from the application main stack only. + * + * @return true if the coroutine has yielded and false if it has finished its + * execution (returned). */ bool Call( ArgType aArg ) { @@ -231,12 +228,12 @@ public: } /** - * Function Call() + * Start execution of a coroutine, passing args as its arguments. * - * Starts execution of a coroutine, passing args as its arguments. Call this method - * for a nested coroutine invocation. - * @return true, if the coroutine has yielded and false if it has finished its - * execution (returned). + * Call this method for a nested coroutine invocation. + * + * @return true if the coroutine has yielded and false if it has finished its + * execution (returned). */ bool Call( const COROUTINE& aCor, ArgType aArg ) { @@ -248,13 +245,13 @@ public: } /** - * Function Resume() - * - * Resumes execution of a previously yielded coroutine. Call this method only - * from the main application stack. - * @return true, if the coroutine has yielded again and false if it has finished its - * execution (returned). - */ + * Resume execution of a previously yielded coroutine. + * + * Call this method only from the main application stack. + * + * @return true if the coroutine has yielded again and false if it has finished its + * execution (returned). + */ bool Resume() { CALL_CONTEXT ctx; @@ -265,13 +262,13 @@ public: } /** - * Function Resume() - * - * Resumes execution of a previously yielded coroutine. Call this method - * for a nested coroutine invocation. - * @return true, if the coroutine has yielded again and false if it has finished its - * execution (returned). - */ + * Resume execution of a previously yielded coroutine. + * + * Call this method for a nested coroutine invocation. + * + * @return true if the coroutine has yielded again and false if it has finished its + * execution (returned). + */ bool Resume( const COROUTINE& aCor ) { INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROUTINE, this, aCor.m_callContext }; @@ -282,9 +279,7 @@ public: } /** - * Function ReturnValue() - * - * Returns the yielded value (the argument KiYield() was called with) + * Return the yielded value (the argument KiYield() was called with). */ const ReturnType& ReturnValue() const { @@ -292,9 +287,7 @@ public: } /** - * Function Running() - * - * @return true, if the coroutine is active + * @return true if the coroutine is active. */ bool Running() const { @@ -314,7 +307,8 @@ private: size_t stackSize = m_stacksize; void* sp = nullptr; - #ifndef LIBCONTEXT_HAS_OWN_STACK +#ifndef LIBCONTEXT_HAS_OWN_STACK + // fixme: Clean up stack stuff. Add a guard m_stack.reset( new char[stackSize] ); @@ -327,7 +321,7 @@ private: #ifdef KICAD_USE_VALGRIND valgrind_stack = VALGRIND_STACK_REGISTER( sp, m_stack.get() ); #endif - #endif +#endif m_callee = libcontext::make_fcontext( sp, stackSize, callerStub ); m_running = true; @@ -345,6 +339,7 @@ private: static void callerStub( intptr_t aData ) { INVOCATION_ARGS& args = *reinterpret_cast( aData ); + // get pointer to self COROUTINE* cor = args.destination; cor->m_callContext = args.context; @@ -364,7 +359,7 @@ private: { args = reinterpret_cast( libcontext::jump_fcontext( &m_caller, m_callee, - reinterpret_cast( args ) ) + reinterpret_cast( args ) ) ); return args; @@ -374,9 +369,10 @@ private: { INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROUTINE, nullptr, nullptr }; INVOCATION_ARGS* ret; + ret = reinterpret_cast( libcontext::jump_fcontext( &m_callee, m_caller, - reinterpret_cast( &args ) ) + reinterpret_cast( &args ) ) ); m_callContext = ret->context; diff --git a/include/tool/edit_constraints.h b/include/tool/edit_constraints.h index d4302d65b8..0227442be2 100644 --- a/include/tool/edit_constraints.h +++ b/include/tool/edit_constraints.h @@ -2,6 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -42,18 +44,16 @@ enum GRID_CONSTRAINT_TYPE /** - * EDIT_CONSTRAINT + * Describe constraints between two edit handles. * - * Allows one to describe constraints between two edit handles. After the constrained handle is changed, - * Apply() has to be called to fix its coordinates according to the implemented constraint. + * After the constrained handle is changed, Apply() has to be called to fix its coordinates + * according to the implemented constraint. */ template class EDIT_CONSTRAINT { public: /** - * Constructor - * * @param aConstrained is EDIT_POINT to which the constraint is applied. */ EDIT_CONSTRAINT( EDIT_TYPE& aConstrained ) : m_constrained( aConstrained ) {}; @@ -61,16 +61,12 @@ public: virtual ~EDIT_CONSTRAINT() {}; /** - * Function Apply() - * - * Corrects coordinates of the constrained edit handle. + * Correct coordinates of the constrained edit handle. */ virtual void Apply( EDIT_TYPE& aHandle ) = 0; /** - * Function Apply() - * - * Corrects coordinates of the constrained edit handle. + * Correct coordinates of the constrained edit handle. */ void Apply() { @@ -78,21 +74,17 @@ public: } protected: - EDIT_TYPE& m_constrained; ///< Point that is constrained by rules implemented by Apply() + EDIT_TYPE& m_constrained; ///< Point that is constrained by rules implemented by Apply(). }; /** - * EC_VERTICAL. - * - * EDIT_CONSTRAINT that imposes a constraint that two points have to have the same X coordinate. + * #EDIT_CONSTRAINT that imposes a constraint that two points have to have the same X coordinate. */ class EC_VERTICAL : public EDIT_CONSTRAINT { public: /** - * Constructor. - * * @param aConstrained is the point that is put under constrain. * @param aConstrainer is the point that is the source of the constrain. */ @@ -100,7 +92,7 @@ public: EDIT_CONSTRAINT( aConstrained ), m_constrainer( aConstrainer ) {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_POINT& aHandle ) override; private: @@ -109,16 +101,12 @@ private: /** - * EC_HORIZONTAL. - * - * EDIT_CONSTRAINT that imposes a constraint that two points have to have the same Y coordinate. + * #EDIT_CONSTRAINT that imposes a constraint that two points have to have the same Y coordinate. */ class EC_HORIZONTAL : public EDIT_CONSTRAINT { public: /** - * Constructor. - * * @param aConstrained is the point that is put under constrain. * @param aConstrainer is the point that is the source of the constrain. */ @@ -126,7 +114,7 @@ public: EDIT_CONSTRAINT( aConstrained ), m_constrainer( aConstrainer ) {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_POINT& aHandle ) override; private: @@ -135,17 +123,13 @@ private: /** - * EC_45DEGREE - * - * EDIT_CONSTRAINT that imposes a constraint that two points have to be located at angle of 45 + * #EDIT_CONSTRAINT that imposes a constraint that two points have to be located at angle of 45 * degree multiplicity. */ class EC_45DEGREE : public EDIT_CONSTRAINT { public: /** - * Constructor. - * * @param aConstrained is the point that is put under constrain. * @param aConstrainer is the point that is the source of the constrain. */ @@ -153,7 +137,7 @@ public: EDIT_CONSTRAINT( aConstrained ), m_constrainer( aConstrainer ) {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_POINT& aHandle ) override; private: @@ -162,9 +146,7 @@ private: /** - * EC_LINE - * - * EDIT_CONSTRAINT that imposes a constraint that a point has to lie on a line (determined + * #EDIT_CONSTRAINT that imposes a constraint that a point has to lie on a line (determined * by 2 points). */ class EC_LINE : public EDIT_CONSTRAINT @@ -172,7 +154,7 @@ class EC_LINE : public EDIT_CONSTRAINT public: EC_LINE( EDIT_POINT& aConstrained, const EDIT_POINT& aConstrainer ); - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_POINT& aHandle ) override; private: @@ -182,16 +164,12 @@ private: /** - * EC_CIRCLE. - * - * EDIT_CONSTRAINT that imposes a constraint that a point has to lie on a circle. + * #EDIT_CONSTRAINT that imposes a constraint that a point has to lie on a circle. */ class EC_CIRCLE : public EDIT_CONSTRAINT { public: /** - * Constructor. - * * @param aConstrained is the point that is put under constrain. * @param aCenter is the point that is the center of the circle. * @param aEnd is the point that decides on the radius of the circle. @@ -200,22 +178,20 @@ public: EDIT_CONSTRAINT( aConstrained ), m_center( aCenter ), m_end( aEnd ) {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_POINT& aHandle ) override; private: - ///> Point that imposes the constraint (center of the circle). + ///< Point that imposes the constraint (center of the circle). const EDIT_POINT& m_center; - ///> Point that imposes the constraint (decides on the radius of the circle). + ///< Point that imposes the constraint (decides on the radius of the circle). const EDIT_POINT& m_end; }; /** - * EC_CONVERGING - * - * EDIT_CONSTRAINT for 3 segments: dragged and two adjacent ones, enforcing to keep their slopes + * #EDIT_CONSTRAINT for 3 segments: dragged and two adjacent ones, enforcing to keep their slopes * and allows only to change ending points. Applied to zones. */ class EC_CONVERGING : public EDIT_CONSTRAINT @@ -225,39 +201,37 @@ public: virtual ~EC_CONVERGING(); - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_LINE& aHandle ) override; private: - ///> Constraint for origin side segment. + ///< Constraint for origin side segment. EDIT_CONSTRAINT* m_originSideConstraint; - ///> Constraint for end side segment. + ///< Constraint for end side segment. EDIT_CONSTRAINT* m_endSideConstraint; - ///> Additional constriant, applied when at least two points are collinear. It is a pointer to - ///> m_[origin/end]SideConstraint, so it should not be freed. + ///< Additional constraint, applied when at least two points are collinear. It is a pointer to + ///< m_[origin/end]SideConstraint, so it should not be freed. EDIT_CONSTRAINT* m_colinearConstraint; - ///> EDIT_POINTS instance that stores currently modified lines. + ///< EDIT_POINTS instance that stores currently modified lines. EDIT_POINTS& m_editPoints; - ///> Vector that represents the initial direction of the dragged segment. + ///< Vector that represents the initial direction of the dragged segment. VECTOR2I m_draggedVector; }; /** - * EC_SNAPLINE - * - * EDIT_CONSTRAINT for a EDIT_LINE, one of the ends is snapped to a spot determined by a + * #EDIT_CONSTRAINT for a EDIT_LINE, one of the ends is snapped to a spot determined by a * transform function passed as parameter (e.g. it can be snapped to a grid), instead of having * the line center snapped to a point. */ class EC_SNAPLINE : public EDIT_CONSTRAINT { public: - ///> Typedef for a function that determines snapping point. + ///< Typedef for a function that determines snapping point. typedef boost::function V2D_TRANSFORM_FUN; EC_SNAPLINE( EDIT_LINE& aLine, V2D_TRANSFORM_FUN aSnapFun ); @@ -265,19 +239,17 @@ public: virtual ~EC_SNAPLINE() {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_LINE& aHandle ) override; private: - ///> Function that determines snapping point. + ///< Function that determines snapping point. V2D_TRANSFORM_FUN m_snapFun; }; /** - * EC_PERPLINE - * - * EDIT_CONSTRAINT for a EDIT_LINE, that constrains the line to move perpendicular + * #EDIT_CONSTRAINT for a EDIT_LINE, that constrains the line to move perpendicular * to the line itself. */ class EC_PERPLINE : public EDIT_CONSTRAINT @@ -289,7 +261,7 @@ public: virtual ~EC_PERPLINE() {} - ///> @copydoc EDIT_CONSTRAINT::Apply() + ///< @copydoc EDIT_CONSTRAINT::Apply() virtual void Apply( EDIT_LINE& aHandle ) override; private: diff --git a/include/tool/edit_points.h b/include/tool/edit_points.h index 573d83f723..a9d2487e6b 100644 --- a/include/tool/edit_points.h +++ b/include/tool/edit_points.h @@ -2,6 +2,8 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2014-2017 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -37,17 +39,15 @@ /** - * EDIT_POINT + * Represent a single point that can be used for modifying items. * - * Represents a single point that can be used for modifying items. It is directly related to one - * of points in a graphical item (e.g. vertex of a zone or center of a circle). + * It is directly related to one of points in a graphical item (e.g. vertex of a zone or + * center of a circle). */ class EDIT_POINT { public: /** - * Constructor - * * @param aPoint stores coordinates for EDIT_POINT. */ EDIT_POINT( const VECTOR2I& aPoint, std::pair aConnected = { nullptr, 0 } ) : @@ -62,10 +62,10 @@ public: virtual ~EDIT_POINT() {} /** - * Function GetPosition() + * Return coordinates of an EDIT_POINT. * - * Returns coordinates of an EDIT_POINT. Note that it may be different than coordinates of - * a graphical item that is bound to the EDIT_POINT. + * @note It may be different than coordinates of a graphical item that is bound to the + * EDIT_POINT. */ virtual VECTOR2I GetPosition() const { @@ -81,9 +81,7 @@ public: } /** - * Function GetX() - * - * Returns X coordinate of an EDIT_POINT. + * Return X coordinate of an EDIT_POINT. */ inline int GetX() const { @@ -91,9 +89,7 @@ public: } /** - * Function GetY() - * - * Returns Y coordinate of an EDIT_POINT. + * Return Y coordinate of an EDIT_POINT. */ inline int GetY() const { @@ -101,10 +97,10 @@ public: } /** - * Function SetPosition() + * Set new coordinates for an EDIT_POINT. + * + * It does not change the coordinates of a graphical item. * - * Sets new coordinates for an EDIT_POINT. It does not change the coordinates of a graphical - * item. * @param aPosition are new coordinates. */ virtual void SetPosition( const VECTOR2I& aPosition ) @@ -119,18 +115,16 @@ public: } /** - * Function WithinPoint() + * Check if given point is within a square centered in the EDIT_POINT position. * - * Checks if given point is within a square centered in the EDIT_POINT position. * @param aPoint is point to be checked. * @param aSize is length of the square side. */ bool WithinPoint( const VECTOR2I& aPoint, unsigned int aSize ) const; /** - * Function SetConstraint() + * Set a constraint for and EDIT_POINT. * - * Sets a constraint for and EDIT_POINT. * @param aConstraint is the constraint to be set. */ void SetConstraint( EDIT_CONSTRAINT* aConstraint ) @@ -139,9 +133,7 @@ public: } /** - * Function GetConstraint() - * - * Returns the constraint imposed on an EDIT_POINT. If there are no constraints, NULL is + * Return the constraint imposed on an EDIT_POINT. If there are no constraints, NULL is * returned. */ EDIT_CONSTRAINT* GetConstraint() const @@ -150,9 +142,7 @@ public: } /** - * Function ClearConstraint() - * - * Removes previously set constraint. + * Remove previously set constraint. */ inline void ClearConstraint() { @@ -160,9 +150,8 @@ public: } /** - * Function IsConstrained() + * Check if point is constrained. * - * Checks if point is constrained. * @return True is point is constrained, false otherwise. */ inline bool IsConstrained() const @@ -171,9 +160,7 @@ public: } /** - * Function ApplyConstraint() - * - * Corrects coordinates of an EDIT_POINT by applying previously set constraint. + * Correct coordinates of an EDIT_POINT by applying previously set constraint. */ virtual void ApplyConstraint() { @@ -195,43 +182,40 @@ public: return m_position == aOther.m_position; } - ///> Single point size in pixels + ///< Single point size in pixels static const int POINT_SIZE = 10; - ///> Border size when not hovering + ///< Border size when not hovering static const int BORDER_SIZE = 2; - ///> Border size when hovering + ///< Border size when hovering static const int HOVER_SIZE = 5; private: - VECTOR2I m_position; // Position of EDIT_POINT - bool m_isActive; // True if this point is being manipulated - bool m_isHover; // True if this point is being hovered over - GRID_CONSTRAINT_TYPE m_gridConstraint; // Describes the grid snapping behavior. + VECTOR2I m_position; ///< Position of EDIT_POINT. + bool m_isActive; ///< True if this point is being manipulated. + bool m_isHover; ///< True if this point is being hovered over. + GRID_CONSTRAINT_TYPE m_gridConstraint; ///< Describe the grid snapping behavior. - ///> An optional connected item record used to mimic polyLine behaviour with individual - /// line segments. + ///< An optional connected item record used to mimic polyLine behavior with individual + ///< line segments. std::pair m_connected; - ///> Constraint for the point, NULL if none + ///< Constraint for the point, NULL if none std::shared_ptr > m_constraint; }; /** - * EDIT_LINE + * Represent a line connecting two EDIT_POINTs. * - * Represents a line connecting two EDIT_POINTs. That allows one to move them - * both by dragging the EDIT_POINT in the middle. As it uses references to - * EDIT_POINTs, all coordinates are automatically synchronized. + * This allows one to move them both by dragging the EDIT_POINT in the middle. It uses + * references to EDIT_POINTs, all coordinates are automatically synchronized. */ class EDIT_LINE : public EDIT_POINT { public: /** - * Constructor - * * @param aOrigin is the origin of EDIT_LINE. * @param aEnd is the end of EDIT_LINE. */ @@ -243,13 +227,13 @@ public: SetGridConstraint( SNAP_BY_GRID ); } - ///> @copydoc EDIT_POINT::GetPosition() + ///< @copydoc EDIT_POINT::GetPosition() virtual VECTOR2I GetPosition() const override { return ( m_origin.GetPosition() + m_end.GetPosition() ) / 2; } - ///> @copydoc EDIT_POINT::GetPosition() + ///< @copydoc EDIT_POINT::GetPosition() virtual void SetPosition( const VECTOR2I& aPosition ) override { VECTOR2I difference = aPosition - GetPosition(); @@ -258,7 +242,7 @@ public: m_end.SetPosition( m_end.GetPosition() + difference ); } - ///> @copydoc EDIT_POINT::ApplyConstraint() + ///< @copydoc EDIT_POINT::ApplyConstraint() virtual void ApplyConstraint() override { if( m_constraint ) @@ -269,9 +253,8 @@ public: } /** - * Function SetConstraint() + * Set a constraint for and EDIT_POINT. * - * Sets a constraint for and EDIT_POINT. * @param aConstraint is the constraint to be set. */ void SetConstraint( EDIT_CONSTRAINT* aConstraint ) @@ -280,9 +263,7 @@ public: } /** - * Function GetConstraint() - * - * Returns the constraint imposed on an EDIT_POINT. If there are no constraints, NULL is + * Return the constraint imposed on an EDIT_POINT. If there are no constraints, NULL is * returned. */ EDIT_CONSTRAINT* GetConstraint() const @@ -291,9 +272,7 @@ public: } /** - * Function GetOrigin() - * - * Returns the origin EDIT_POINT. + * Return the origin EDIT_POINT. */ EDIT_POINT& GetOrigin() { @@ -306,9 +285,7 @@ public: } /** - * Function GetEnd() - * - * Returns the end EDIT_POINT. + * Return the end EDIT_POINT. */ EDIT_POINT& GetEnd() { @@ -334,38 +311,31 @@ private: EDIT_POINT& m_origin; ///< Origin point for a line EDIT_POINT& m_end; ///< End point for a line - ///> Constraint for the point, NULL if none + ///< Constraint for the point, NULL if none std::shared_ptr > m_constraint; }; /** - * EDIT_POINTS - * - * EDIT_POINTS is a VIEW_ITEM that manages EDIT_POINTs and EDIT_LINEs and draws them. + * EDIT_POINTS is a #VIEW_ITEM that manages EDIT_POINTs and EDIT_LINEs and draws them. */ class EDIT_POINTS : public EDA_ITEM { public: /** - * Constructor. - * * @param aParent is the item to which EDIT_POINTs are related. */ EDIT_POINTS( EDA_ITEM* aParent ); /** - * Function FindPoint() + * Return a point that is at given coordinates or NULL if there is no such point. * - * Returns a point that is at given coordinates or NULL if there is no such point. * @param aLocation is the location for searched point. */ EDIT_POINT* FindPoint( const VECTOR2I& aLocation, KIGFX::VIEW *aView ); /** - * Function GetParent() - * - * Returns parent of the EDIT_POINTS. + * Return parent of the EDIT_POINTS. */ EDA_ITEM* GetParent() const { @@ -373,9 +343,8 @@ public: } /** - * Function AddPoint() + * Add an EDIT_POINT. * - * Adds an EDIT_POINT. * @param aPoint is the new point. */ void AddPoint( const EDIT_POINT& aPoint ) @@ -384,9 +353,8 @@ public: } /** - * Function AddPoint() + * Add an EDIT_POINT. * - * Adds an EDIT_POINT. * @param aPoint are coordinates of the new point. */ void AddPoint( const VECTOR2I& aPoint, std::pair aConnected = { nullptr, 0 } ) @@ -395,9 +363,8 @@ public: } /** - * Function AddLine() - * * Adds an EDIT_LINE. + * * @param aLine is the new line. */ void AddLine( const EDIT_LINE& aLine ) @@ -406,9 +373,8 @@ public: } /** - * Function AddLine() - * * Adds an EDIT_LINE. + * * @param aOrigin is the origin for a new line. * @param aEnd is the end for a new line. */ @@ -418,8 +384,6 @@ public: } /** - * Function AddBreak() - * * Adds a break, indicating the end of a contour. */ void AddBreak() @@ -429,66 +393,60 @@ public: } /** - * Function GetContourStartIdx() + * Return index of the contour origin for a point with given index. * - * Returns index of the contour origin for a point with given index. * @param aPointIdx is the index of point for which the contour origin is searched. * @return Index of the contour origin point. */ int GetContourStartIdx( int aPointIdx ) const; /** - * Function GetContourEndIdx() + * Return index of the contour finish for a point with given index. * - * Returns index of the contour finish for a point with given index. * @param aPointIdx is the index of point for which the contour finish is searched. * @return Index of the contour finish point. */ int GetContourEndIdx( int aPointIdx ) const; /** - * Function IsContourStart() + * Check if a point with given index is a contour origin. * - * Checks is a point with given index is a contour origin. * @param aPointIdx is the index of the point to be checked. * @return True if the point is an origin of a contour. */ bool IsContourStart( int aPointIdx ) const; /** - * Function IsContourEnd() + * Check is a point with given index is a contour finish. * - * Checks is a point with given index is a contour finish. * @param aPointIdx is the index of the point to be checked. * @return True if the point is a finish of a contour. */ bool IsContourEnd( int aPointIdx ) const; /** - * Function Previous() + * Return the point that is after the given point in the list. * - * Returns the point that is after the given point in the list. * @param aPoint is the point that is supposed to be preceding the searched point. * @param aTraverseContours decides if in case of breaks should we return to the origin - * of contour or continue with the next contour. + * of contour or continue with the next contour. * @return The point following aPoint in the list. If aPoint is the first in - * the list, the last from the list will be returned. If there are no points at all, NULL - * is returned. + * the list, the last from the list will be returned. If there are no points at + * all, NULL is returned. */ EDIT_POINT* Previous( const EDIT_POINT& aPoint, bool aTraverseContours = true ); EDIT_LINE* Previous( const EDIT_LINE& aLine ); /** - * Function Next() + * Return the point that is before the given point in the list. * - * Returns the point that is before the given point in the list. * @param aPoint is the point that is supposed to be following the searched point. * @param aTraverseContours decides if in case of breaks should we return to the origin - * of contour or continue with the next contour. - * @return The point preceding aPoint in the list. If aPoint is the last in - * the list, the first point from the list will be returned. If there are no points at all, - * NULL is returned. + * of contour or continue with the next contour. + * @return The point preceding aPoint in the list. If aPoint is the last in the list, the + * first point from the list will be returned. If there are no points at all, + * NULL is returned. */ EDIT_POINT* Next( const EDIT_POINT& aPoint, bool aTraverseContours = true ); @@ -515,9 +473,7 @@ public: } /** - * Function PointsSize() - * - * Returns number of stored EDIT_POINTs. + * Return number of stored EDIT_POINTs. */ unsigned int PointsSize() const { @@ -525,22 +481,20 @@ public: } /** - * Function LinesSize() - * - * Returns number of stored EDIT_LINEs. + * Return number of stored EDIT_LINEs. */ unsigned int LinesSize() const { return m_lines.size(); } - ///> @copydoc VIEW_ITEM::ViewBBox() + ///< @copydoc VIEW_ITEM::ViewBBox() virtual const BOX2I ViewBBox() const override; - ///> @copydoc VIEW_ITEM::ViewDraw() + ///< @copydoc VIEW_ITEM::ViewDraw() virtual void ViewDraw( int aLayer, KIGFX::VIEW* aView ) const override; - ///> @copydoc VIEW_ITEM::ViewGetLayers() + ///< @copydoc VIEW_ITEM::ViewGetLayers() virtual void ViewGetLayers( int aLayers[], int& aCount ) const override { aCount = 1; @@ -553,8 +507,10 @@ public: } #endif - /** Get class name - * @return string "EDIT_POINTS" + /** + * Get the class name. + * + * @return string "EDIT_POINTS". */ virtual wxString GetClass() const override { @@ -562,11 +518,11 @@ public: } private: - EDA_ITEM* m_parent; ///< Parent of the EDIT_POINTs - std::deque m_points; ///< EDIT_POINTs for modifying m_parent - std::deque m_lines; ///< EDIT_LINEs for modifying m_parent - std::list m_contours; ///< Indices of end contour points - bool m_allowPoints; ///< If false, only allow editing of EDIT_LINES + EDA_ITEM* m_parent; ///< Parent of the EDIT_POINTs. + std::deque m_points; ///< EDIT_POINTs for modifying m_parent. + std::deque m_lines; ///< EDIT_LINEs for modifying m_parent. + std::list m_contours; ///< Indices of end contour points. + bool m_allowPoints; ///< If false, only allow editing of EDIT_LINES. }; #endif /* EDIT_POINTS_H_ */ diff --git a/include/tool/editor_conditions.h b/include/tool/editor_conditions.h index c3be088e7b..053caad57b 100644 --- a/include/tool/editor_conditions.h +++ b/include/tool/editor_conditions.h @@ -33,6 +33,7 @@ class EDA_BASE_FRAME; class EDA_DRAW_FRAME; + /** * Class that groups generic conditions for editor states. */ @@ -49,116 +50,117 @@ public: {} /** - * Creates a functor that tests if the content of the frame is modified. + * Create a functor that tests if the content of the frame is modified. * - * @return Functor testing for modified content + * @return Functor testing for modified content. */ SELECTION_CONDITION ContentModified(); /** - * Creates a functor that tests if there are any items in the undo queue + * Create a functor that tests if there are any items in the undo queue. * * @return Functor testing if the undo queue has items. */ SELECTION_CONDITION UndoAvailable(); /** - * Creates a functor that tests if there are any items in the redo queue + * Create a functor that tests if there are any items in the redo queue. * * @return Functor testing if the redo queue has items. */ SELECTION_CONDITION RedoAvailable(); /** - * Creates a functor that tests if the frame has the specified units + * Create a functor that tests if the frame has the specified units. * * @return Functor testing the units of a frame. */ SELECTION_CONDITION Units( EDA_UNITS aUnit ); /** - * Creates a functor testing if the specified tool is the current active tool in the frame. + * Create a functor testing if the specified tool is the current active tool in the frame. * - * @return Functor testing the current tool of a frame + * @return Functor testing the current tool of a frame. */ SELECTION_CONDITION CurrentTool( const TOOL_ACTION& aTool ); /** - * Creates a functor testing if there are no tools active in the frame. + * Create a functor testing if there are no tools active in the frame. * - * @return Functor testing the frame has no tools running + * @return Functor testing the frame has no tools running. */ SELECTION_CONDITION NoActiveTool(); /** - * Creates a functor testing if the grid is visible in a frame. + * Create a functor testing if the grid is visible in a frame. * - * @note this requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. + * @note This requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. * * @return Functor testing if the grid is visible */ SELECTION_CONDITION GridVisible(); /** - * Creates a functor testing if polar coordinates are current being used. + * Create a functor testing if polar coordinates are current being used. * - * @note this requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. + * @note This requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. * * @return Functor testing if the grid is visible */ SELECTION_CONDITION PolarCoordinates(); /** - * Creates a functor testing if the cursor is full screen in a frame. + * Create a functor testing if the cursor is full screen in a frame. * - * @note this requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. + * @note This requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. * * @return Functor testing if the cursor is full screen */ SELECTION_CONDITION FullscreenCursor(); /** - * Creates a functor testing if the specified canvas is active in the frame. + * Create a functor testing if the specified canvas is active in the frame. * - * @note this requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. + * @note This requires the frame passed into the constructor be be derived from EDA_DRAW_FRAME. * * @return Functor testing the canvas type of the frame */ SELECTION_CONDITION CanvasType( EDA_DRAW_PANEL_GAL::GAL_TYPE aType ); protected: - ///> Helper function used by ContentModified() + ///< Helper function used by ContentModified(). static bool contentModifiedFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame ); - ///> Helper function used by UndoAvailable() + ///< Helper function used by UndoAvailable(). static bool undoFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame ); - ///> Helper function used by RedoAvailable() + ///< Helper function used by RedoAvailable(). static bool redoFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame ); - ///> Helper function used by Units() + ///< Helper function used by Units(). static bool unitsFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame, EDA_UNITS aUnits ); - ///> Helper function used by CurrentTool() - static bool toolFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame, const TOOL_ACTION& aTool ); + ///< Helper function used by CurrentTool(). + static bool toolFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame, + const TOOL_ACTION& aTool ); - ///> Helper function used by NoActiveTool() + ///< Helper function used by NoActiveTool(). static bool noToolFunc( const SELECTION& aSelection, EDA_BASE_FRAME* aFrame ); - ///> Helper function used by GridVisible() + ///< Helper function used by GridVisible(). static bool gridFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame ); - ///> Helper function used by PolarCoordinates() + ///< Helper function used by PolarCoordinates(). static bool polarCoordFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame ); - ///> Helper function used by FullscreenCursor() + ///< Helper function used by FullscreenCursor(). static bool cursorFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame ); - ///> Helper function used by CanvasType() + ///< Helper function used by CanvasType(). static bool canvasTypeFunc( const SELECTION& aSelection, EDA_DRAW_FRAME* aFrame, EDA_DRAW_PANEL_GAL::GAL_TYPE aType ); - ///> The frame to apply the conditions to + ///< The frame to apply the conditions to. EDA_BASE_FRAME* m_frame; }; diff --git a/include/tool/picker_tool.h b/include/tool/picker_tool.h index 06c2f38d78..bb1465744f 100644 --- a/include/tool/picker_tool.h +++ b/include/tool/picker_tool.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2019 CERN - * Copyright (C) 2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2019-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -45,7 +45,7 @@ public: /// @copydoc TOOL_INTERACTIVE::Reset() void Reset( RESET_REASON aReason ) override { } - ///> Event handler types. + ///< Event handler types. typedef std::function CLICK_HANDLER; typedef std::function MOTION_HANDLER; typedef std::function CANCEL_HANDLER; @@ -60,15 +60,15 @@ public: EXCEPTION_CANCEL }; - ///> Main event loop. + ///< Main event loop. int Main( const TOOL_EVENT& aEvent ); inline void SetCursor( KICURSOR aCursor ) { m_cursor = aCursor; } /** - * Function SetClickHandler() - * Sets a handler for mouse click event. Handler may decide to receive further click by - * returning true. + * Set a handler for mouse click event. + * + * The handler may decide to receive further click by returning true. */ inline void SetClickHandler( CLICK_HANDLER aHandler ) { @@ -77,8 +77,9 @@ public: } /** - * Function SetMotionHandler() - * Sets a handler for mouse motion. Used for roll-over highlighting. + * Set a handler for mouse motion. + * + * This is used for roll-over highlighting. */ inline void SetMotionHandler( MOTION_HANDLER aHandler ) { @@ -87,8 +88,7 @@ public: } /** - * Function SetCancelHandler() - * Sets a handler for cancel events (ESC or context-menu Cancel). + * Set a handler for cancel events (ESC or context-menu Cancel). */ inline void SetCancelHandler( CANCEL_HANDLER aHandler ) { @@ -97,8 +97,9 @@ public: } /** - * Function SetFinalizeHandler() - * Sets a handler for the finalize event. Takes the state of the exit from the Main loop + * Set a handler for the finalize event. + * + * Takes the state of the exit from the main loop. */ inline void SetFinalizeHandler( FINALIZE_HANDLER aHandler ) { @@ -107,13 +108,13 @@ public: } private: - ///> Reinitializes tool to its initial state. + ///< Reinitializes tool to its initial state. void resetPicker(); - ///> Applies the requested VIEW_CONTROLS settings. + ///< Applies the requested VIEW_CONTROLS settings. void setControls(); - ///> @copydoc TOOL_INTERACTIVE::setTransitions(); + ///< @copydoc TOOL_INTERACTIVE::setTransitions(); void setTransitions() override; private: diff --git a/include/tool/selection_conditions.h b/include/tool/selection_conditions.h index 4493bf77f1..d4d482764f 100644 --- a/include/tool/selection_conditions.h +++ b/include/tool/selection_conditions.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2014 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -30,7 +32,7 @@ #include #include -///> Functor type that checks a specific condition for selected items. +///< Functor type that checks a specific condition for selected items. typedef std::function SELECTION_CONDITION; SELECTION_CONDITION operator||( const SELECTION_CONDITION& aConditionA, @@ -89,7 +91,7 @@ public: } /** - * Tests if there are any items selected. + * Test if there are any items selected. * * @param aSelection is the selection to be tested. * @return True if there is at least one item selected. @@ -97,7 +99,7 @@ public: static bool NotEmpty( const SELECTION& aSelection ); /** - * Tests if there are no items selected. + * Test if there are no items selected. * * @param aSelection is the selection to be tested. * @return True if there are no items selected. @@ -105,7 +107,7 @@ public: static bool Empty( const SELECTION& aSelection ); /** - * Tests if there no items selected or being edited. + * Test if there no items selected or being edited. * * @param aSelection is the selection to be tested. * @return True if there are no items being edited or no items selected. @@ -113,7 +115,7 @@ public: static bool Idle( const SELECTION& aSelection ); /** - * Tests if all selected items are not being edited. + * Test if all selected items are not being edited. * * @param aSelection is the selection to be tested. * @return True if no selected items are being edited. @@ -121,7 +123,8 @@ public: static bool IdleSelection( const SELECTION& aSelection ); /** - * Creates a functor that tests if among the selected items there is at least one of a given type. + * Create a functor that tests if among the selected items there is at least one of a + * given type. * * @param aType is the type that is searched. * @return Functor testing for presence of items of a given type. @@ -129,7 +132,7 @@ public: static SELECTION_CONDITION HasType( KICAD_T aType ); /** - * Creates a functor that tests if the selected items are *only* of given type. + * Create a functor that tests if the selected items are *only* of given type. * * @param aType is the type that is searched. * @return Functor testing if selected items are exclusively of one type. @@ -137,16 +140,16 @@ public: static SELECTION_CONDITION OnlyType( KICAD_T aType ); /** - * Creates a functor that tests if the selected items are *only* of given types. + * Create a functor that tests if the selected items are *only* of given types. * * @param aTypes is an array containing types that are searched. It has to be ended with - * KICAD_T::EOT as end marker. + * #KICAD_T::EOT as end marker. * @return Functor testing if selected items are exclusively of the requested types. */ static SELECTION_CONDITION OnlyTypes( const KICAD_T aTypes[] ); /** - * Creates a functor that tests if the number of selected items is equal to the value given as + * Create a functor that tests if the number of selected items is equal to the value given as * parameter. * * @param aNumber is the number of expected items. @@ -155,7 +158,7 @@ public: static SELECTION_CONDITION Count( int aNumber ); /** - * Creates a functor that tests if the number of selected items is greater than the value given + * Create a functor that tests if the number of selected items is greater than the value given * as parameter. * * @param aNumber is the number used for comparison. @@ -164,7 +167,7 @@ public: static SELECTION_CONDITION MoreThan( int aNumber ); /** - * Creates a functor that tests if the number of selected items is smaller than the value given + * Create a functor that tests if the number of selected items is smaller than the value given * as parameter. * * @param aNumber is the number used for comparison. @@ -173,52 +176,52 @@ public: static SELECTION_CONDITION LessThan( int aNumber ); private: - ///> Helper function used by HasType() + ///< Helper function used by HasType() static bool hasTypeFunc( const SELECTION& aSelection, KICAD_T aType ); - ///> Helper function used by OnlyType() + ///< Helper function used by OnlyType() static bool onlyTypeFunc( const SELECTION& aSelection, KICAD_T aType ); - ///> Helper function used by OnlyTypes() + ///< Helper function used by OnlyTypes() static bool onlyTypesFunc( const SELECTION& aSelection, const KICAD_T aTypes[] ); - ///> Helper function used by Count() + ///< Helper function used by Count() static bool countFunc( const SELECTION& aSelection, int aNumber ); - ///> Helper function used by MoreThan() + ///< Helper function used by MoreThan() static bool moreThanFunc( const SELECTION& aSelection, int aNumber ); - ///> Helper function used by LessThan() + ///< Helper function used by LessThan() static bool lessThanFunc( const SELECTION& aSelection, int aNumber ); - ///> Helper function used by operator|| + ///< Helper function used by operator|| static bool orFunc( const SELECTION_CONDITION& aConditionA, const SELECTION_CONDITION& aConditionB, const SELECTION& aSelection ) { return aConditionA( aSelection ) || aConditionB( aSelection ); } - ///> Helper function used by operator&& + ///< Helper function used by operator&& static bool andFunc( const SELECTION_CONDITION& aConditionA, const SELECTION_CONDITION& aConditionB, const SELECTION& aSelection ) { return aConditionA( aSelection ) && aConditionB( aSelection ); } - ///> Helper function used by operator! + ///< Helper function used by operator! static bool notFunc( const SELECTION_CONDITION& aCondition, const SELECTION& aSelection ) { return !aCondition( aSelection ); } - ///> Helper function used by operator|| + ///< Helper function used by operator|| static bool orBoolFunc( const SELECTION_CONDITION& aConditionA, SELECTION_BOOL& aConditionB, const SELECTION& aSelection ) { return aConditionA( aSelection ) || aConditionB( aSelection ); } - ///> Helper function used by operator&& + ///< Helper function used by operator&& static bool andBoolFunc( const SELECTION_CONDITION& aConditionA, SELECTION_BOOL& aConditionB, const SELECTION& aSelection ) { diff --git a/include/tool/tool_action.h b/include/tool/tool_action.h index 38a8b38862..4f12725fe0 100644 --- a/include/tool/tool_action.h +++ b/include/tool/tool_action.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2015 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -34,10 +36,13 @@ struct BITMAP_OPAQUE; /** - * Represents a single user action. For instance: + * Represent a single user action. + * + * For instance: * - changing layer to top by pressing PgUp * - running the DRC from the menu * and so on, and so forth.... + * * Action class groups all necessary properties of an action, including explanation, * icons, hotkeys, menu items, etc. */ @@ -46,7 +51,8 @@ class TOOL_ACTION public: TOOL_ACTION( const std::string& aName, TOOL_ACTION_SCOPE aScope = AS_CONTEXT, int aDefaultHotKey = 0, const std::string& aLegacyHotKeyName = "", - const wxString& aMenuText = wxEmptyString, const wxString& aTooltip = wxEmptyString, + const wxString& aMenuText = wxEmptyString, + const wxString& aTooltip = wxEmptyString, const BITMAP_OPAQUE* aIcon = nullptr, TOOL_ACTION_FLAGS aFlags = AF_NONE, void* aParam = nullptr ); @@ -67,35 +73,39 @@ public: } /** - * Returns name of the action. It is the same one that is contained in TOOL_EVENT that is - * sent by activating the TOOL_ACTION. Convention is "app.tool.actionName". + * Return name of the action. + * + * It is the same one that is contained in #TOOL_EVENT that is sent by activating the + * TOOL_ACTION. Convention is "app.tool.actionName". * * @return Name of the action. */ const std::string& GetName() const { return m_name; } /** - * Returns the default hotkey (if any) for the action. + * Return the default hotkey (if any) for the action. */ int GetDefaultHotKey() const { return m_defaultHotKey; } /** - * Returns the hotkey keycode which initiates the action. + * Return the hotkey keycode which initiates the action. */ int GetHotKey() const { return m_hotKey; } void SetHotKey( int aKeycode ); /** - * Returns the unique id of the TOOL_ACTION object. It is valid only after registering the - * TOOL_ACTION by ACTION_MANAGER. + * Return the unique id of the TOOL_ACTION object. + * + * It is valid only after registering the TOOL_ACTION by #ACTION_MANAGER. * * @return The unique identification number. If the number is negative, then it is not valid. */ int GetId() const { return m_id; } /* - * Get the unique ID for this action in the user interface system. This is simply - * the action ID offset by @c ACTION_BASE_UI_ID. + * Get the unique ID for this action in the user interface system. + * + * This is simply the action ID offset by @c ACTION_BASE_UI_ID. * * @return The unique ID number for use in the user interface system. */ @@ -107,7 +117,7 @@ public: static int GetBaseUIId() { return ACTION_BASE_UI_ID; } /** - * Returns the event associated with the action (i.e. the event that will be sent after + * Return the event associated with the action (i.e. the event that will be sent after * activating the action). */ TOOL_EVENT MakeEvent() const @@ -127,14 +137,14 @@ public: TOOL_ACTION_SCOPE GetScope() const { return m_scope; } /** - * Returns name of the tool associated with the action. It is basically the action name + * Return name of the tool associated with the action. It is basically the action name * stripped of the last part (e.g. for "pcbnew.InteractiveDrawing.drawCircle" it is * "pcbnew.InteractiveDrawing"). */ std::string GetToolName() const; /** - * Returns true if the action is intended to activate a tool. + * Return true if the action is intended to activate a tool. */ bool IsActivation() const { @@ -142,7 +152,7 @@ public: } /** - * Returns true if the action is a notification. + * Return true if the action is a notification. */ bool IsNotification() const { @@ -150,7 +160,9 @@ public: } /** - * Returns an icon associated with the action. It is used in context menu. + * Return an icon associated with the action. + * + * It is used in context menu. */ const BITMAP_OPAQUE* GetIcon() const { @@ -162,15 +174,15 @@ protected: friend class ACTION_MANAGER; - ///> Base ID to use inside the user interface system to offset the action IDs. + ///< Base ID to use inside the user interface system to offset the action IDs. static constexpr int ACTION_BASE_UI_ID = 20000; - /// Name of the action (convention is "app.tool.actionName") + ///< Name of the action (convention is "app.tool.actionName") std::string m_name; TOOL_ACTION_SCOPE m_scope; const int m_defaultHotKey; // Default hot key - int m_hotKey; // The curret hotkey (post-user-settings-application) + int m_hotKey; // The current hotkey (post-user-settings-application) const std::string m_legacyName; // Name for reading legacy hotkey settings wxString m_label; diff --git a/include/tool/tool_base.h b/include/tool/tool_base.h index 4b8185baa3..b31f028547 100644 --- a/include/tool/tool_base.h +++ b/include/tool/tool_base.h @@ -2,8 +2,9 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2016-2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -45,10 +46,10 @@ class VIEW_CONTROLS; enum TOOL_TYPE { - ///> Tool that interacts with the user + ///< Tool that interacts with the user INTERACTIVE = 0x01, - ///> Tool that runs in the background without any user intervention + ///< Tool that runs in the background without any user intervention BATCH = 0x02 }; @@ -59,8 +60,6 @@ using TOOL_STATE_FUNC = std::function; /** - * TOOL_BASE - * * Base abstract interface for all kinds of tools. */ @@ -75,7 +74,7 @@ public: virtual ~TOOL_BASE() {}; - ///> Determines the reason of reset for a tool + ///< Determine the reason of reset for a tool. enum RESET_REASON { RUN, ///< Tool is invoked after being inactive @@ -84,7 +83,6 @@ public: }; /** - * Function Init() * Init() is called once upon a registration of the tool. * * @return True if the initialization went fine, false - otherwise. @@ -95,16 +93,17 @@ public: } /** - * Function Reset() - * Brings the tool to a known, initial state. If the tool claimed anything from - * the model or the view, it must release it when its reset. + * Bring the tool to a known, initial state. + * + * If the tool claimed anything from the model or the view, it must release it when its + * reset. * @param aReason contains information about the reason of tool reset. */ virtual void Reset( RESET_REASON aReason ) = 0; /** - * Function GetType() - * Returns the type of the tool. + * Return the type of the tool. + * * @return The type of the tool. */ TOOL_TYPE GetType() const @@ -113,9 +112,10 @@ public: } /** - * Function GetId() - * Returns the unique identifier of the tool. The identifier is set by an instance of - * TOOL_MANAGER. + * Return the unique identifier of the tool. + * + * The identifier is set by an instance of #TOOL_MANAGER. + * * @return Identifier of the tool. */ TOOL_ID GetId() const @@ -124,9 +124,11 @@ public: } /** - * Function GetName() - * Returns the name of the tool. Tool names are expected to obey the format: - * application.ToolName (eg. pcbnew.InteractiveSelection). + * Return the name of the tool. + * + * Tool names are expected to obey the format: application.ToolName (eg. + * pcbnew.InteractiveSelection). + * * @return The name of the tool. */ const std::string& GetName() const @@ -135,10 +137,9 @@ public: } /** - * Function GetManager() - * Returns the instance of TOOL_MANAGER that takes care of the tool. - * @return Instance of the TOOL_MANAGER. If there is no TOOL_MANAGER associated, it returns - * NULL. + * Return the instance of #TOOL_MANAGER that takes care of the tool. + * + * @return Instance of the #TOOL_MANAGER or NULL if there is no associated tool manager. */ TOOL_MANAGER* GetManager() const { @@ -148,40 +149,37 @@ public: //TOOL_SETTINGS& GetAdapter(); bool IsToolActive() const; - + protected: friend class TOOL_MANAGER; friend class TOOL_SETTINGS; /** - * Function attachManager() + * Set the #TOOL_MANAGER the tool will belong to. * - * Sets the TOOL_MANAGER the tool will belong to. - * Called by TOOL_MANAGER::RegisterTool() + * Called by #TOOL_MANAGER::RegisterTool() */ void attachManager( TOOL_MANAGER* aManager ); /** - * Function getView() + * Returns the instance of #VIEW object used in the application. It allows tools to draw. * - * Returns the instance of VIEW object used in the application. It allows tools to draw. * @return The instance of VIEW. */ KIGFX::VIEW* getView() const; /** - * Function getViewControls() + * Return the instance of VIEW_CONTROLS object used in the application. + * + * It allows tools to read & modify user input and its settings (eg. show cursor, enable + * snapping to grid, etc.). * - * Returns the instance of VIEW_CONTROLS object used in the application. It allows tools to - * read & modify user input and its settings (eg. show cursor, enable snapping to grid, etc.) * @return The instance of VIEW_CONTROLS. */ KIGFX::VIEW_CONTROLS* getViewControls() const; /** - * Function getEditFrame() - * - * Returns the application window object, casted to requested user type. + * Return the application window object, casted to requested user type. */ template T* getEditFrame() const @@ -193,9 +191,7 @@ protected: } /** - * Function getModel() - * - * Returns the model object if it matches the requested type. + * Return the model object if it matches the requested type. */ template T* getModel() const @@ -207,14 +203,14 @@ protected: return static_cast( m ); } - ///> Stores the type of the tool. + ///< Store the type of the tool. TOOL_TYPE m_type; - ///> Unique identifier for the tool, assigned by a TOOL_MANAGER instance. + ///< Unique identifier for the tool, assigned by a TOOL_MANAGER instance. TOOL_ID m_toolId; - ///> Name of the tool. Names are expected to obey the format application.ToolName - ///> (eg. pcbnew.InteractiveSelection). + ///< Name of the tool. Names are expected to obey the format application.ToolName + ///< (eg. pcbnew.InteractiveSelection). std::string m_toolName; TOOL_MANAGER* m_toolMgr; //TOOL_SETTINGS m_toolSettings; diff --git a/include/tool/tool_dispatcher.h b/include/tool/tool_dispatcher.h index e0a15c899d..3720e204ea 100644 --- a/include/tool/tool_dispatcher.h +++ b/include/tool/tool_dispatcher.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -42,28 +44,28 @@ class VIEW; * - takes wx events, * - fixes all wx quirks (mouse warping, panning, ordering problems, etc) * - translates coordinates to world space - * - low-level input conditioning (drag/click threshold), updating mouse position during view auto-scroll/pan. + * - low-level input conditioning (drag/click threshold), updating mouse position during + * view auto-scroll/pan. * - issues TOOL_EVENTS to the tool manager */ - class TOOL_DISPATCHER : public wxEvtHandler { public: /** - * @param aToolMgr: tool manager instance the events will be sent to - * @param aActions: ACTIONS subclass instance for ACTIONS::TranslateLegacyId() + * @param aToolMgr: tool manager instance the events will be sent to. + * @param aActions: ACTIONS subclass instance for ACTIONS::TranslateLegacyId(). */ TOOL_DISPATCHER( TOOL_MANAGER* aToolMgr, ACTIONS *aActions ); virtual ~TOOL_DISPATCHER(); /** - * Brings the dispatcher to its initial state. + * Bring the dispatcher to its initial state. */ virtual void ResetState(); /** - * Processes wxEvents (mostly UI events), translates them to TOOL_EVENTs, and makes tools + * Process wxEvents (mostly UI events), translate them to TOOL_EVENTs, and make tools * handle those. * * @param aEvent is the wxWidgets event to be processed. @@ -71,12 +73,12 @@ public: virtual void DispatchWxEvent( wxEvent& aEvent ); /** - * Maps a wxWidgets key event to a TOOL_EVENT. + * Map a wxWidgets key event to a TOOL_EVENT. */ OPT GetToolEvent( wxKeyEvent* aKeyEvent, bool* aSpecialKeyFlag ); /** - * Processes wxCommands (mostly menu related events) and runs appropriate actions (eg. run the + * Process wxCommands (mostly menu related events) and runs appropriate actions (eg. run the * specified tool). * * @param aEvent is the wxCommandEvent to be processed. @@ -84,21 +86,21 @@ public: virtual void DispatchWxCommand( wxCommandEvent& aEvent ); private: - ///> Number of mouse buttons that is handled in events. + ///< Number of mouse buttons that is handled in events. static const int MouseButtonCount = 3; - ///> The time threshold for a mouse button press that distinguishes between a single mouse - ///> click and a beginning of drag event (expressed in milliseconds). + ///< The time threshold for a mouse button press that distinguishes between a single mouse + ///< click and a beginning of drag event (expressed in milliseconds). static const int DragTimeThreshold = 300; - ///> The distance threshold for mouse cursor that disinguishes between a single mouse click - ///> and a beginning of drag event (expressed in screen pixels). + ///< The distance threshold for mouse cursor that distinguishes between a single mouse click + ///< and a beginning of drag event (expressed in screen pixels). static const int DragDistanceThreshold = 8; - ///> Handles mouse related events (click, motion, dragging). + ///< Handles mouse related events (click, motion, dragging). bool handleMouseButton( wxEvent& aEvent, int aIndex, bool aMotion ); - ///> Saves the state of key modifiers (Alt, Ctrl and so on). + ///< Saves the state of key modifiers (Alt, Ctrl and so on). static int decodeModifiers( const wxKeyboardState* aState ) { int mods = 0; @@ -115,22 +117,22 @@ private: return mods; } - ///> Stores all the informations regarding a mouse button state. + ///< Stores all the information regarding a mouse button state. struct BUTTON_STATE; - ///> The last mouse cursor position (in world coordinates). + ///< The last mouse cursor position (in world coordinates). VECTOR2D m_lastMousePos; - ///> State of mouse buttons. + ///< State of mouse buttons. std::vector m_buttons; - ///> Returns the instance of VIEW, used by the application. + ///< Returns the instance of VIEW, used by the application. KIGFX::VIEW* getView(); - ///> Instance of tool manager that cooperates with the dispatcher. + ///< Instance of tool manager that cooperates with the dispatcher. TOOL_MANAGER* m_toolMgr; - ///> Instance of an actions list that handles legacy action translation + ///< Instance of an actions list that handles legacy action translation ACTIONS* m_actions; }; diff --git a/include/tool/tool_event.h b/include/tool/tool_event.h index b13f78eb64..487421700a 100644 --- a/include/tool/tool_event.h +++ b/include/tool/tool_event.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -45,7 +47,6 @@ class TOOL_BASE; /** * Internal (GUI-independent) event definitions. - * Enums are mostly self-explanatory. */ enum TOOL_EVENT_CATEGORY { @@ -88,7 +89,7 @@ enum TOOL_ACTIONS TA_CANCEL_TOOL = 0x2000, // Context menu update. Issued whenever context menu is open and the user hovers the mouse - // over one of choices. Used in dynamic highligting in disambiguation menu + // over one of choices. Used in dynamic highlighting in disambiguation menu TA_CHOICE_MENU_UPDATE = 0x4000, // Context menu choice. Sent if the user picked something from the context menu or @@ -142,17 +143,17 @@ enum TOOL_MODIFIERS /// Scope of tool actions enum TOOL_ACTION_SCOPE { - AS_CONTEXT = 1, ///> Action belongs to a particular tool (i.e. a part of a pop-up menu) - AS_ACTIVE, ///> All active tools - AS_GLOBAL ///> Global action (toolbar/main menu event, global shortcut) + AS_CONTEXT = 1, ///< Action belongs to a particular tool (i.e. a part of a pop-up menu) + AS_ACTIVE, ///< All active tools + AS_GLOBAL ///< Global action (toolbar/main menu event, global shortcut) }; /// Flags for tool actions enum TOOL_ACTION_FLAGS { AF_NONE = 0, - AF_ACTIVATE = 1, ///> Action activates a tool - AF_NOTIFY = 2 ///> Action is a notification (it is by default passed to all tools) + AF_ACTIVATE = 1, ///< Action activates a tool + AF_NOTIFY = 2 ///< Action is a notification (it is by default passed to all tools) }; /// Defines when a context menu is opened. @@ -164,16 +165,13 @@ enum CONTEXT_MENU_TRIGGER }; /** - * TOOL_EVENT - * * Generic, UI-independent tool event. */ class TOOL_EVENT { public: /** - * Function Format() - * Returns information about event in form of a human-readable string. + * Return information about event in form of a human-readable string. * * @return Event information. */ @@ -243,46 +241,46 @@ public: init(); } - ///> Returns the category (eg. mouse/keyboard/action) of an event.. + ///< Returns the category (eg. mouse/keyboard/action) of an event.. TOOL_EVENT_CATEGORY Category() const { return m_category; } - ///> Returns more specific information about the type of an event. + ///< Returns more specific information about the type of an event. TOOL_ACTIONS Action() const { return m_actions; } - ///> These give a tool a method of informing the TOOL_MANAGER that a particular event should - ///> be passed on to subsequent tools on the stack. Defaults to true for TC_MESSAGES; false - ///> for everything else. + ///< These give a tool a method of informing the TOOL_MANAGER that a particular event should + ///< be passed on to subsequent tools on the stack. Defaults to true for TC_MESSAGES; false + ///< for everything else. bool PassEvent() const { return m_passEvent; } void SetPassEvent( bool aPass = true ) { m_passEvent = aPass; } - ///> Returns if it this event has a valid position (true for mouse events and context-menu - ///> or hotkey-based command events) + ///< Returns if it this event has a valid position (true for mouse events and context-menu + ///< or hotkey-based command events) bool HasPosition() const { return m_hasPosition; } void SetHasPosition( bool aHasPosition ) { m_hasPosition = aHasPosition; } TOOL_BASE* FirstResponder() const { return m_firstResponder; } void SetFirstResponder( TOOL_BASE* aTool ) { m_firstResponder = aTool; } - ///> Returns information about difference between current mouse cursor position and the place - ///> where dragging has started. + ///< Returns information about difference between current mouse cursor position and the place + ///< where dragging has started. const VECTOR2D Delta() const { return returnCheckedPosition( m_mouseDelta ); } - ///> Returns mouse cursor position in world coordinates. + ///< Returns mouse cursor position in world coordinates. const VECTOR2D Position() const { return returnCheckedPosition( m_mousePos ); } - ///> Returns the point where dragging has started. + ///< Returns the point where dragging has started. const VECTOR2D DragOrigin() const { return returnCheckedPosition( m_mouseDragOrigin ); } - ///> Returns information about mouse buttons state. + ///< Returns information about mouse buttons state. int Buttons() const { assert( m_category == TC_MOUSE ); // this should be used only with mouse events @@ -338,7 +336,7 @@ public: return m_actions == TA_PRIME; } - ///> Returns information about key modifiers state (Ctrl, Alt, etc.) + ///< Returns information about key modifiers state (Ctrl, Alt, etc.) int Modifier( int aMask = MD_MODIFIER_MASK ) const { return m_modifiers & aMask; @@ -355,8 +353,7 @@ public: } /** - * Function Matches() - * Tests whether two events match in terms of category & action or command. + * Test whether two events match in terms of category & action or command. * * @param aEvent is the event to test against. * @return True if two events match, false otherwise. @@ -388,47 +385,41 @@ public: } /** - * Function IsAction() - * Tests if the event contains an action issued upon activation of the given TOOL_ACTION. + * Test if the event contains an action issued upon activation of the given #TOOL_ACTION. + * * @param aAction is the TOOL_ACTION to be checked against. * @return True if it matches the given TOOL_ACTION. */ bool IsAction( const TOOL_ACTION* aAction ) const; /** - * Function IsCancelInteractive() - * - * Indicates the event should restart/end an ongoing interactive tool's event loop (eg esc + * Indicate the event should restart/end an ongoing interactive tool's event loop (eg esc * key, click cancel, start different tool). */ bool IsCancelInteractive(); /** - * Function IsSelectionEvent() - * - * Indicates an selection-changed notification event. + * Indicate an selection-changed notification event. */ bool IsSelectionEvent(); /** - * Function IsPointEditor + * Indicate if the event is from one of the point editors. * - * Indicates if the event is from one of the point editors. Usually used to allow the - * point editor to activate itself without de-activating the current drawing tool. + * Usually used to allow the point editor to activate itself without de-activating the + * current drawing tool. */ bool IsPointEditor(); /** - * Function IsMoveTool + * Indicate if the event is from one of the move tools. * - * Indicates if the event is from one of the move tools. Usually used to allow move to - * be done without de-activating the current drawing tool. + * Usually used to allow move to be done without de-activating the current drawing tool. */ bool IsMoveTool(); /** - * Function Parameter() - * Returns a non-standard parameter assigned to the event. Its meaning depends on the + * Return a non-standard parameter assigned to the event. Its meaning depends on the * target tool. */ template @@ -444,9 +435,9 @@ public: } /** - * Function SetParameter() - * Sets a non-standard parameter assigned to the event. Its meaning depends on the + * Set a non-standard parameter assigned to the event. Its meaning depends on the * target tool. + * * @param aParam is the new parameter. */ template @@ -500,6 +491,7 @@ private: /** * Ensure that the event is a type that has a position before returning a * position, otherwise return a null-constructed position. + * * Used to defend the position accessors from runtime access when the event * does not have a valid position. * @@ -524,29 +516,29 @@ private: bool m_passEvent; bool m_hasPosition; - ///> Difference between mouse cursor position and - ///> the point where dragging event has started + ///< Difference between mouse cursor position and + ///< the point where dragging event has started VECTOR2D m_mouseDelta; - ///> Current mouse cursor position + ///< Current mouse cursor position VECTOR2D m_mousePos; - ///> Point where dragging has started + ///< Point where dragging has started VECTOR2D m_mouseDragOrigin; - ///> State of mouse buttons + ///< State of mouse buttons int m_mouseButtons; - ///> Stores code of pressed/released key + ///< Stores code of pressed/released key int m_keyCode; - ///> State of key modifierts (Ctrl/Alt/etc.) + ///< State of key modifiers (Ctrl/Alt/etc.) int m_modifiers; - ///> Generic parameter used for passing non-standard data. + ///< Generic parameter used for passing non-standard data. void* m_param; - ///> The first tool to receive the event + ///< The first tool to receive the event TOOL_BASE* m_firstResponder; OPT m_commandId; @@ -556,10 +548,8 @@ private: typedef OPT OPT_TOOL_EVENT; /** - * TOOL_EVENT_LIST - * - * A list of TOOL_EVENTs, with overloaded || operators allowing for - * concatenating TOOL_EVENTs with little code. + * A list of TOOL_EVENTs, with overloaded || operators allowing for concatenating TOOL_EVENTs + * with little code. */ class TOOL_EVENT_LIST { @@ -568,17 +558,17 @@ public: typedef std::deque::iterator iterator; typedef std::deque::const_iterator const_iterator; - ///> Default constructor. Creates an empty list. + ///< Default constructor. Creates an empty list. TOOL_EVENT_LIST() {} - ///> Constructor for a list containing only one TOOL_EVENT. + ///< Constructor for a list containing only one TOOL_EVENT. TOOL_EVENT_LIST( const TOOL_EVENT& aSingleEvent ) { m_events.push_back( aSingleEvent ); } - ///> Copy an existing TOOL_EVENT_LIST + /// - * Copyright (C) 2016 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -37,62 +38,59 @@ class TOOL_INTERACTIVE : public TOOL_BASE { public: /** - * Constructor - * - * Creates a tool with given id & name. The name must be unique. */ + * Create a tool with given id & name. The name must be unique. + */ TOOL_INTERACTIVE( TOOL_ID aId, const std::string& aName ); /** - * Constructor - * - * Creates a tool with given name. The name must be unique. */ + * Creates a tool with given name. The name must be unique. + */ TOOL_INTERACTIVE( const std::string& aName ); virtual ~TOOL_INTERACTIVE(); /** - * Function Activate() - * Runs the tool. After activation, the tool starts receiving events until it is finished. + * Run the tool. + * + * After activation, the tool starts receiving events until it is finished. */ void Activate(); TOOL_MENU& GetToolMenu() { return m_menu; } - + /** - * Function SetContextMenu() + * Assign a context menu and tells when it should be activated. * - * Assigns a context menu and tells when it should be activated. * @param aMenu is the menu to be assigned. * @param aTrigger determines conditions upon which the context menu is activated. */ void SetContextMenu( ACTION_MENU* aMenu, CONTEXT_MENU_TRIGGER aTrigger = CMENU_BUTTON ); /** - * Function RunMainStack() + * Call a function using the main stack. * - * Calls a function using the main stack. * @param aFunc is the function to be calls. */ void RunMainStack( std::function aFunc ); /** - * Function Go() + * Define which state (aStateFunc) to go when a certain event arrives (aConditions). * - * Defines which state (aStateFunc) to go when a certain event arrives (aConditions). * No conditions means any event. */ template void Go( int (T::* aStateFunc)( const TOOL_EVENT& ), - const TOOL_EVENT_LIST& aConditions = TOOL_EVENT( TC_ANY, TA_ANY ) ); + const TOOL_EVENT_LIST& aConditions = TOOL_EVENT( TC_ANY, TA_ANY ) ); /** - * Function Wait() + * Suspend execution of the tool until an event specified in aEventList arrives. * - * Suspends execution of the tool until an event specified in aEventList arrives. * No parameters means waiting for any event. */ TOOL_EVENT* Wait( const TOOL_EVENT_LIST& aEventList = TOOL_EVENT( TC_ANY, TA_ANY ) ); - /** functions below are not yet implemented - their interface may change */ + /** + * The functions below are not yet implemented - their interface may change + */ /*template bool InvokeTool( const std::string& aToolName, const Parameters& parameters, ReturnValue& returnValue ); @@ -109,13 +107,14 @@ protected: private: /** - * This method is meant to be overridden in order to specify handlers for events. It is called - * every time tool is reset or finished. + * This method is meant to be overridden in order to specify handlers for events. + * + * It is called every time tool is reset or finished. */ virtual void setTransitions() = 0; /** - * Clears the current transition map and restores the default one created by setTransitions(). + * Clear the current transition map and restores the default one created by setTransitions(). */ void resetTransitions(); diff --git a/include/tool/tool_manager.h b/include/tool/tool_manager.h index b321ed642e..06632b3d06 100644 --- a/include/tool/tool_manager.h +++ b/include/tool/tool_manager.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -42,7 +44,6 @@ class APP_SETTINGS_BASE; /** - * TOOL_MANAGER. * Master controller class: * - registers editing tools * - pumps UI events to tools requesting them @@ -71,16 +72,15 @@ public: static TOOL_ID MakeToolId( const std::string& aToolName ); /** - * Function RegisterTool() - * Adds a tool to the manager set and sets it up. Called once for - * each tool during application initialization. + * Add a tool to the manager set and sets it up. Called once for each tool during + * application initialization. + * * @param aTool: tool to be added. Ownership is transferred. */ void RegisterTool( TOOL_BASE* aTool ); /** - * Function InvokeTool() - * Calls a tool by sending a tool activation event to tool of given ID. + * Call a tool by sending a tool activation event to tool of given ID. * * @param aToolId is the ID number of the requested tool. * @return True if the requested tool was invoked successfully. @@ -88,8 +88,7 @@ public: bool InvokeTool( TOOL_ID aToolId ); /** - * Function InvokeTool() - * Calls a tool by sending a tool activation event to tool of given name. + * Call a tool by sending a tool activation event to tool of given name. * * @param aToolName is the name of the requested tool. * @return True if the requested tool was invoked successfully. @@ -127,14 +126,15 @@ public: void ShutdownTool( const std::string& aToolName ); /** - * Function RunAction() - * Runs the specified action. The common format for action names is "application.ToolName.Action". + * Run the specified action. + * + * The common format for action names is "application.ToolName.Action". * * @param aActionName is the name of action to be invoked. * @param aNow decides if the action has to be run immediately or after the current coroutine - * is preemptied. + * is preemptied. * @param aParam is an optional parameter that might be used by the invoked action. Its meaning - * depends on the action. + * depends on the action. * @return False if the action was not found. */ template @@ -151,18 +151,16 @@ public: } /** - * Function RunAction() - * Runs the specified action. + * Run the specified action. * * This function will only return if the action has been handled when the action is run * immediately (aNow = true), otherwise it will always return false. * * @param aAction is the action to be invoked. * @param aNow decides if the action has to be run immediately or after the current coroutine - * is preemptied. + * is preemptied. * @param aParam is an optional parameter that might be used by the invoked action. Its meaning - * depends on the action. - * + * depends on the action. * @return True if the action was handled immediately */ template @@ -186,22 +184,20 @@ public: void CancelTool(); /** - * Function PrimeTool() - * "Primes" a tool by sending a cursor left-click event with the mouse position set + * "Prime" a tool by sending a cursor left-click event with the mouse position set * to the passed in position. * * @param aPosition is the mouse position to use in the event */ void PrimeTool( const VECTOR2D& aPosition ); - ///> @copydoc ACTION_MANAGER::GetHotKey() + ///< @copydoc ACTION_MANAGER::GetHotKey() int GetHotKey( const TOOL_ACTION& aAction ); ACTION_MANAGER* GetActionManager() { return m_actionMgr; } /** - * Function FindTool() - * Searches for a tool with given ID. + * Search for a tool with given ID. * * @param aId is the ID number of the requested tool. * @return Pointer to the requested tool or NULL in case of failure. @@ -209,8 +205,7 @@ public: TOOL_BASE* FindTool( int aId ) const; /** - * Function FindTool() - * Searches for a tool with given name. + * Search for a tool with given name. * * @param aName is the name of the requested tool. * @return Pointer to the requested tool or NULL in case of failure. @@ -218,8 +213,7 @@ public: TOOL_BASE* FindTool( const std::string& aName ) const; /* - * Function GetTool() - * Returns the tool of given type or NULL if there is no such tool registered. + * Return the tool of given type or NULL if there is no such tool registered. */ template T* GetTool() @@ -233,42 +227,41 @@ public: } /** - * Function DeactivateTool() - * Deactivates the currently active tool. + * Deactivate the currently active tool. */ void DeactivateTool(); /** - * Function IsToolActive() - * Returns true if a tool with given id is active (executing) + * Return true if a tool with given id is active (executing) */ bool IsToolActive( TOOL_ID aId ) const; /** - * Function ResetTools() - * Resets all tools (i.e. calls their Reset() method). + * Reset all tools (i.e. calls their Reset() method). */ void ResetTools( TOOL_BASE::RESET_REASON aReason ); /** - * Function InitTools() - * Initializes all registered tools. If a tool fails during the initialization, it is - * deactivated and becomes unavailable for further use. Initialization should be done - * only once. + * Initializes all registered tools. + * + * If a tool fails during the initialization, it is deactivated and becomes unavailable + * for further use. Initialization should be done only once. */ void InitTools(); /** - * Propagates an event to tools that requested events of matching type(s). + * Propagate an event to tools that requested events of matching type(s). + * * @param aEvent is the event to be processed. * @return true if the event is a managed hotkey */ bool ProcessEvent( const TOOL_EVENT& aEvent ); /** - * Puts an event to the event queue to be processed at the end of event processing cycle. + * Put an event to the event queue to be processed at the end of event processing cycle. + * * @param aEvent is the event to be put into the queue. */ inline void PostEvent( const TOOL_EVENT& aEvent ) @@ -277,7 +270,8 @@ public: } /** - * Sets the work environment (model, view, view controls and the parent window). + * Set the work environment (model, view, view controls and the parent window). + * * These are made available to the tool. Called by the parent frame when it is set up. */ void SetEnvironment( EDA_ITEM* aModel, KIGFX::VIEW* aView, @@ -286,7 +280,7 @@ public: /* * Accessors for the environment objects (view, model, etc.) - * */ + */ KIGFX::VIEW* GetView() const { return m_view; } KIGFX::VIEW_CONTROLS* GetViewControls() const { return m_viewControls; } @@ -301,8 +295,9 @@ public: TOOLS_HOLDER* GetToolHolder() const { return m_frame; } /** - * Returns id of the tool that is on the top of the active tools stack - * (was invoked the most recently). + * Return id of the tool that is on the top of the active tools stack (was invoked the + * most recently). + * * @return Id of the currently used tool. */ inline int GetCurrentToolId() const @@ -311,8 +306,9 @@ public: } /** - * Returns the tool that is on the top of the active tools stack - * (was invoked the most recently). + * Return the tool that is on the top of the active tools stack (was invoked the most + * recently). + * * @return Pointer to the currently used tool. */ inline TOOL_BASE* GetCurrentTool() const @@ -321,7 +317,7 @@ public: } /** - * Returns the TOOL_STATE object representing the state of the active tool. If there are no + * Return the #TOOL_STATE object representing the state of the active tool. If there are no * tools active, it returns nullptr. */ TOOL_STATE* GetCurrentToolState() const @@ -331,24 +327,29 @@ public: } /** - * Returns priority of a given tool. Higher number means that the tool is closer to the - * beginning of the active tools queue (i.e. receives events earlier, tools with lower - * priority receive events later). + * Return priority of a given tool. + * + * Higher number means that the tool is closer to the beginning of the active tools + * queue (i.e. receives events earlier, tools with lower priority receive events later). + * * @param aToolId is the id of queried tool. * @return The priority of a given tool. If returned number is negative, then it means that - * the tool id is invalid or the tool is not active. + * the tool id is invalid or the tool is not active. */ int GetPriority( int aToolId ) const; /** - * Defines a state transition - the events that cause a given handler method in the tool - * to be called. Called by TOOL_INTERACTIVE::Go(). May be called from a coroutine context. + * Define a state transition. + * + * The events that cause a given handler method in the tool to be called. Called by + * TOOL_INTERACTIVE::Go(). May be called from a coroutine context. */ void ScheduleNextState( TOOL_BASE* aTool, TOOL_STATE_FUNC& aHandler, - const TOOL_EVENT_LIST& aConditions ); + const TOOL_EVENT_LIST& aConditions ); /** - * Clears the state transition map for a tool + * Clear the state transition map for a tool. + * * @param aTool is the tool that should have the transition map cleared. */ void ClearTransitions( TOOL_BASE* aTool ); @@ -356,22 +357,23 @@ public: void RunMainStack( TOOL_BASE* aTool, std::function aFunc ); /** - * Updates the status bar and synchronizes toolbars. + * Update the status bar and synchronizes toolbars. */ void UpdateUI( const TOOL_EVENT& aEvent ); /** - * Pauses execution of a given tool until one or more events matching aConditions arrives. - * The pause/resume operation is done through COROUTINE object. - * Called only from coroutines. + * Pause execution of a given tool until one or more events matching aConditions arrives. + * + * The pause/resume operation is done through #COROUTINE object. Called only from coroutines. */ TOOL_EVENT* ScheduleWait( TOOL_BASE* aTool, const TOOL_EVENT_LIST& aConditions ); /** - * Sets behaviour of the tool's context popup menu. - * @param aTool - the parent tool - * @param aMenu - the menu structure, defined by the tool - * @param aTrigger - when the menu is activated: + * Set behavior of the tool's context popup menu. + * + * @param aTool is the parent tool. + * @param aMenu is the menu structure, defined by the tool. + * @param aTrigger determines when the menu is activated: * CMENU_NOW: opens the menu right now * CMENU_BUTTON: opens the menu when RMB is pressed * CMENU_OFF: menu is disabled. @@ -380,23 +382,26 @@ public: void ScheduleContextMenu( TOOL_BASE* aTool, ACTION_MENU* aMenu, CONTEXT_MENU_TRIGGER aTrigger ); /** - * Stores an information to the system clipboard. - * @param aText is the information to be stored, expected UTF8 encoding. - * the text will be stored as Unicode string (not stored as UTF8 string) + * Store information to the system clipboard. + * + * @param aText is the information to be stored, expected UTF8 encoding. The text will be + * stored as Unicode string (not stored as UTF8 string). * @return False if error occurred. */ bool SaveClipboard( const std::string& aTextUTF8 ); /** - * Returns the information currently stored in the system clipboard. If data stored in the - * clipboard is in non-text format, empty string is returned. - * Note also the clipboard is expected containing unicode chars, not only ASCII7 chars. - * The returned string is UTF8 encoded + * Return the information currently stored in the system clipboard. + * + * If data stored in the clipboard is in non-text format, empty string is returned. + * + * @note The clipboard is expected containing Unicode chars, not only ASCII7 chars. + * The returned string is UTF8 encoded */ std::string GetClipboardUTF8() const; /** - * Returns the view controls settings for the current tool or the general settings if there is + * Return the view controls settings for the current tool or the general settings if there is * no active tool. */ const KIGFX::VC_SETTINGS& GetCurrentToolVC() const; @@ -410,9 +415,10 @@ public: } /** - * Disables mouse warping after the current context menu is closed. - * Must be called before invoking each context menu. - * It's a good idea to call this from non-modal dialogs (e.g. DRC window). + * Disable mouse warping after the current context menu is closed. + * + * This must be called before invoking each context menu. It's a good idea to call this + * from non-modal dialogs (e.g. DRC window). */ void VetoContextMenuMouseWarp() { @@ -420,14 +426,13 @@ public: } /** - * Function DispatchContextMenu() - * Handles context menu related events. + * Handle context menu related events. */ void DispatchContextMenu( const TOOL_EVENT& aEvent ); /** - * Function dispatchHotKey() - * Handles specific events, that are intended for TOOL_MANAGER rather than tools. + * Handle specific events, that are intended for TOOL_MANAGER rather than tools. + * * @param aEvent is the event to be processed. * @return true if the event was processed and should not go any further. */ @@ -442,49 +447,48 @@ private: typedef std::pair TRANSITION; /** - * Function dispatchInternal - * Passes an event at first to the active tools, then to all others. + * Passe an event at first to the active tools, then to all others. */ bool dispatchInternal( const TOOL_EVENT& aEvent ); /** - * Function dispatchActivation() - * Checks if it is a valid activation event and invokes a proper tool. + * Check if it is a valid activation event and invokes a proper tool. + * * @param aEvent is an event to be tested. * @return True if a tool was invoked, false otherwise. */ bool dispatchActivation( const TOOL_EVENT& aEvent ); /** - * Function invokeTool() - * Invokes a tool by sending a proper event (in contrary to runTool, which makes the tool run + * Invoke a tool by sending a proper event (in contrary to runTool, which makes the tool run * for real). + * * @param aTool is the tool to be invoked. */ bool invokeTool( TOOL_BASE* aTool ); /** - * Function runTool() - * Makes a tool active, so it can receive events and react to them. Activated tool is pushed - * on the active tools stack, so the last activated tool receives events first. + * Make a tool active, so it can receive events and react to them. + * + * The activated tool is pushed on the active tools stack, so the last activated tool + * receives events first. * * @param aTool is the tool to be run. */ bool runTool( TOOL_BASE* aTool ); /** - * Function finishTool() - * Deactivates a tool and does the necessary clean up. + * Deactivate a tool and does the necessary clean up. * * @param aState is the state variable of the tool to be stopped. * @return m_activeTools iterator. If the tool has been completely deactivated, it points - * to the next active tool on the list. Otherwise it is an iterator pointing to aState. + * to the next active tool on the list. Otherwise it is an iterator pointing to + * \a aState. */ ID_LIST::iterator finishTool( TOOL_STATE* aState ); /** - * Function isRegistered() - * Returns information about a tool registration status. + * Return information about a tool registration status. * * @param aTool is the tool to be checked. * @return true if the tool is in the registered tools list, false otherwise. @@ -495,8 +499,7 @@ private: } /** - * Function isActive() - * Returns information about a tool activation status. + * Return information about a tool activation status. * * @param aTool is the tool to be checked. * @return True if the tool is on the active tools stack, false otherwise. @@ -504,53 +507,54 @@ private: bool isActive( TOOL_BASE* aTool ); /** - * Function saveViewControls() - * Saves the VIEW_CONTROLS settings to the tool state object. If VIEW_CONTROLS - * settings are affected by TOOL_MANAGER, the original settings are saved. + * Save the #VIEW_CONTROLS settings to the tool state object. + * + * If #VIEW_CONTROLS settings are affected by #TOOL_MANAGER, the original settings are saved. */ void saveViewControls( TOOL_STATE* aState ); /** - * Function applyViewControls() - * Applies VIEW_CONTROLS settings stored in a TOOL_STATE object. + * Apply #VIEW_CONTROLS settings stored in a #TOOL_STATE object. */ void applyViewControls( TOOL_STATE* aState ); /** * Main function for event processing. - * @return true if a hotkey was handled + * + * @return true if a hotkey was handled. */ bool processEvent( const TOOL_EVENT& aEvent ); /** - * Saves the previous active state and sets a new one. + * Save the previous active state and sets a new one. + * * @param aState is the new active state. Might be null to indicate there is no new - * active state. + * active state. */ void setActiveState( TOOL_STATE* aState ); - /// List of tools in the order they were registered + ///< List of tools in the order they were registered TOOL_VEC m_toolOrder; - /// Index of registered tools current states, associated by tools' objects. + ///< Index of registered tools current states, associated by tools' objects. TOOL_STATE_MAP m_toolState; - /// Index of the registered tools current states, associated by tools' names. + ///< Index of the registered tools current states, associated by tools' names. NAME_STATE_MAP m_toolNameIndex; - /// Index of the registered tools current states, associated by tools' ID numbers. + ///< Index of the registered tools current states, associated by tools' ID numbers. ID_STATE_MAP m_toolIdIndex; - /// Index of the registered tools to easily lookup by their type. + ///< Index of the registered tools to easily lookup by their type. std::map m_toolTypes; - /// Stack of the active tools + ///< Stack of the active tools ID_LIST m_activeTools; - /// Instance of ACTION_MANAGER that handles TOOL_ACTIONs + ///< Instance of ACTION_MANAGER that handles TOOL_ACTIONs ACTION_MANAGER* m_actionMgr; - /// Original cursor position, if overridden by the context menu handler + ///< Original cursor position, if overridden by the context menu handler std::map> m_cursorSettings; EDA_ITEM* m_model; @@ -559,21 +563,21 @@ private: TOOLS_HOLDER* m_frame; APP_SETTINGS_BASE* m_settings; - /// Queue that stores events to be processed at the end of the event processing cycle. + ///< Queue that stores events to be processed at the end of the event processing cycle. std::list m_eventQueue; - /// Right click context menu position. + ///< Right click context menu position. VECTOR2D m_menuCursor; bool m_warpMouseAfterContextMenu; - /// Flag indicating whether a context menu is currently displayed. + ///< Flag indicating whether a context menu is currently displayed. bool m_menuActive; - /// Tool currently displaying a popup menu. It is negative when there is no menu displayed. + ///< Tool currently displaying a popup menu. It is negative when there is no menu displayed. TOOL_ID m_menuOwner; - /// Pointer to the state object corresponding to the currently executed tool. + ///< Pointer to the state object corresponding to the currently executed tool. TOOL_STATE* m_activeState; }; diff --git a/include/tool/tool_menu.h b/include/tool/tool_menu.h index 514c0103fb..4e04357b94 100644 --- a/include/tool/tool_menu.h +++ b/include/tool/tool_menu.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2017 KiCad Developers, see CHANGELOG.txt for contributors. + * Copyright (C) 2017-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,57 +33,42 @@ class ACTION_MENU; /** - * TOOL_MENU + * Manage a #CONDITIONAL_MENU and some number of CONTEXT_MENUs as sub-menus. * - * Manages a CONDITIONAL_MENU and some number of - * CONTEXT_MENUs as sub-menus - * - * Each "top-level" interactive tool can have one of these, - * and other tools can contribute CONTEXT_MENUS to it. - * - * There are also helper functions for adding common sets of - * menu items, for example zoom and grid controls. + * Each "top-level" interactive tool can have one of these, and other tools can contribute + * #CONTEXT_MENUS to it. There are also helper functions for adding common sets of menu + * items, for example zoom and grid controls. */ class TOOL_MENU { public: /** - * Function TOOL_MENU + * Construct a new TOOL_MENU for a specific tool. * - * Construct a new TOOL_MENU for a specific tool. This menu - * will be empty - it's up to the caller to add the relevant - * items. This can be done directy, using the reference returned - * by TOOL_MENU::GetMenu(), or the helpers for common command sets - * can be used, or a combination of the two. + * This menu will be empty - it's up to the caller to add the relevant items. This can be + * done directly, using the reference returned by TOOL_MENU::GetMenu(), or the helpers for + * common command sets can be used, or a combination of the two. */ TOOL_MENU( TOOL_INTERACTIVE& aTool ); /** - * Destructor, also destructs any submenus created with - * TOOL_MENU::CreateSubMenu(). + * Destruct any submenus created with TOOL_MENU::CreateSubMenu(). */ ~TOOL_MENU(); /** - * Function GetMenu - * - * @return reference to the CONDITIONAL_MENU model, which can be - * used tby tools to add their own commands to the menu. + * @return reference to the CONDITIONAL_MENU model, which can be used by tools to add + * their own commands to the menu. */ CONDITIONAL_MENU& GetMenu(); /** - * Function CreateSubMenu + * Store a submenu of this menu model. This can be shared with other menu models. * - * Store a submenu of this menu model. This can be shared with - * other menu models. - * - * It is the callers responsibility to add the submenu to - * m_menu (via GetMenu() ) in the right way, as well - * as to set the tool with SetTool(), since it's not a given - * that the menu's tool is the tool that directly owns this - * TOOL_MENU + * It is the callers responsibility to add the submenu to m_menu (via GetMenu() ) in the + * right way, as well as to set the tool with SetTool(), since it's not a given that the + * menu's tool is the tool that directly owns this #TOOL_MENU. * * @param aSubMenu: a sub menu to add */ @@ -98,39 +83,34 @@ public: } /** - * Function ShowContextMenu + * Helper function to set and immediately show a #CONDITIONAL_MENU in concert with the + * given #SELECTION * - * Helper function to set and immediately show a CONDITIONAL_MENU - * in concert with the given SELECTION - * - * You don't have to use this function, if the caller has a - * different way to show the menu, it can create one from - * the reference returned by TOOL_MENU::GetMenu(), but it will - * have to be managed externally to this class. + * You don't have to use this function, if the caller has a different way to show the + * menu, it can create one from the reference returned by TOOL_MENU::GetMenu(), but it + * will have to be managed externally to this class. */ void ShowContextMenu( SELECTION& aSelection ); /** - * Function ShowContextMenu - * - * Helper function to show a context menu without any selection - * for tools that can't make selections. + * Helper function to show a context menu without any selection for tools that can't + * make selections. */ void ShowContextMenu(); private: /** - * The conditional menu displayed by the tool + * The conditional menu displayed by the tool. */ CONDITIONAL_MENU m_menu; /** - * The tool that owns this menu + * The tool that owns this menu. */ TOOL_INTERACTIVE& m_tool; /** - * Lifetime-managing container of submenus + * Lifetime-managing container of submenus. */ std::vector > m_subMenus; }; diff --git a/include/tool/tools_holder.h b/include/tool/tools_holder.h index 9b739c82ea..eb3080abee 100644 --- a/include/tool/tools_holder.h +++ b/include/tool/tools_holder.h @@ -36,7 +36,6 @@ class ACTIONS; /* - * Class TOOLS_HOLDER * A mix-in class which allows its owner to hold a set of tools from the tool framework. * * This is just the framework; the owner is responsible for registering individual tools, @@ -44,27 +43,6 @@ class ACTIONS; */ class TOOLS_HOLDER { -protected: - TOOL_MANAGER* m_toolManager; - ACTIONS* m_actions; - TOOL_DISPATCHER* m_toolDispatcher; - - SELECTION m_dummySelection; // Empty dummy selection - - std::vector m_toolStack; // Stack of user-level "tools". This is NOT a - // stack of TOOL instances, because somewhat - // confusingly most TOOLs implement more than one - // user-level tool. A user-level tool actually - // equates to an ACTION handler, so this stack - // stores ACTION names. - - bool m_immediateActions; // Preference for immediate actions. If false, - // the first invocation of a hotkey will just - // select the relevant tool rather than executing - // the tool's action. - bool m_dragSelects; // Prefer selection to dragging. - bool m_moveWarpsCursor; // cursor is warped to move/drag origin - public: TOOLS_HOLDER(); @@ -79,8 +57,8 @@ public: * Register an action's update conditions with the UI layer to allow the UI to appropriately * display the state of its controls. * - * @param aAction is the action to register - * @param aConditions are the UI conditions to use for the control states + * @param aAction is the action to register. + * @param aConditions are the UI conditions to use for the control states. */ virtual void RegisterUIUpdateHandler( const TOOL_ACTION& aAction, const ACTION_CONDITIONS& aConditions ) @@ -89,18 +67,18 @@ public: } /** - * Register a UI update handler for the control with ID @c aID + * Register a UI update handler for the control with ID @c aID. * - * @param aID is the control ID to register the handler for - * @param aConditions are the UI conditions to use for the control states + * @param aID is the control ID to register the handler for. + * @param aConditions are the UI conditions to use for the control states. */ virtual void RegisterUIUpdateHandler( int aID, const ACTION_CONDITIONS& aConditions ) {} /** - * Unregister a UI handler for an action that was registered using @c RegisterUIUpdateHandler + * Unregister a UI handler for an action that was registered using @c RegisterUIUpdateHandler. * - * @param aAction is the action to unregister the handler for + * @param aAction is the action to unregister the handler for. */ virtual void UnregisterUIUpdateHandler( const TOOL_ACTION& aAction ) { @@ -108,9 +86,9 @@ public: } /** - * Unregister a UI handler for a given ID that was registered using @c RegisterUIUpdateHandler + * Unregister a UI handler for a given ID that was registered using @c RegisterUIUpdateHandler. * - * @param aID is the control ID to unregister the handler for + * @param aID is the control ID to unregister the handler for. */ virtual void UnregisterUIUpdateHandler( int aID ) {} @@ -118,7 +96,7 @@ public: /** * Get the current selection from the canvas area. * - * @return the current selection + * @return the current selection. */ virtual SELECTION& GetCurrentSelection() { @@ -126,9 +104,11 @@ public: } /** - * NB: the definition of "tool" is different at the user level. The implementation uses - * a single TOOL_BASE derived class to implement several user "tools", such as rectangle - * and circle, or wire and bus. So each user-level tool is actually a TOOL_ACTION. + * NB: the definition of "tool" is different at the user level. + * + * The implementation uses a single TOOL_BASE derived class to implement several user + * "tools", such as rectangle and circle, or wire and bus. So each user-level tool is + * actually a #TOOL_ACTION. */ virtual void PushTool( const std::string& actionName ); virtual void PopTool( const std::string& actionName ); @@ -141,20 +121,20 @@ public: virtual void DisplayToolMsg( const wxString& msg ) {}; /** - * Indicates that hotkeys should perform an immediate action even if another tool is + * Indicate that hotkeys should perform an immediate action even if another tool is * currently active. If false, the first hotkey should select the relevant tool. */ bool GetDoImmediateActions() const { return m_immediateActions; } /** - * Indicates that a drag should draw a selection rectangle, even when started over an + * Indicate that a drag should draw a selection rectangle, even when started over an * item. */ bool GetDragSelects() const { return m_dragSelects; } /** - * Indicates that a move operation should warp the mouse pointer to the origin of the - * move object. This improves snapping, but some users are alergic to mouse warping. + * Indicate that a move operation should warp the mouse pointer to the origin of the + * move object. This improves snapping, but some users are allergic to mouse warping. */ bool GetMoveWarpsCursor() const { return m_moveWarpsCursor; } @@ -171,6 +151,27 @@ public: virtual void RefreshCanvas() { } virtual wxString ConfigBaseName() { return wxEmptyString; } + +protected: + TOOL_MANAGER* m_toolManager; + ACTIONS* m_actions; + TOOL_DISPATCHER* m_toolDispatcher; + + SELECTION m_dummySelection; // Empty dummy selection + + std::vector m_toolStack; // Stack of user-level "tools". This is NOT a + // stack of TOOL instances, because somewhat + // confusingly most TOOLs implement more than one + // user-level tool. A user-level tool actually + // equates to an ACTION handler, so this stack + // stores ACTION names. + + bool m_immediateActions; // Preference for immediate actions. If false, + // the first invocation of a hotkey will just + // select the relevant tool rather than executing + // the tool's action. + bool m_dragSelects; // Prefer selection to dragging. + bool m_moveWarpsCursor; // cursor is warped to move/drag origin }; #endif // TOOL_HOLDER_H diff --git a/include/view/view.h b/include/view/view.h index e0ac202429..d0a9da87d6 100644 --- a/include/view/view.h +++ b/include/view/view.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -46,19 +48,21 @@ class VIEW_GROUP; class VIEW_RTREE; /** - * VIEW. - * Holds a (potentially large) number of VIEW_ITEMs and renders them on a graphics device - * provided by the GAL. VIEWs can exist in two flavors: + * Hold a (potentially large) number of VIEW_ITEMs and renders them on a graphics device + * provided by the GAL. + * + * VIEWs can exist in two flavors: * - dynamic - where items can be added, removed or changed anytime, intended for the main - * editing panel. Each VIEW_ITEM can be added to a single dynamic view. + * editing panel. Each VIEW_ITEM can be added to a single dynamic view. * - static - where items are added once at the startup and are not linked with the VIEW. - * Foreseen for preview windows and printing. - * Items in a view are grouped in layers (not to be confused with Kicad's PCB layers). Each layer is - * identified by an integer number. Visibility and rendering order can be set individually for each - * of the layers. Future versions of the VIEW will also allows one to assign different layers to different - * rendering targets, which will be composited at the final stage by the GAL. - * The VIEW class also provides fast methods for finding all visible objects that are within a given - * rectangular area, useful for object selection/hit testing. + * Foreseen for preview windows and printing. + * + * Items in a view are grouped in layers (not to be confused with Kicad's PCB layers). Each + * layer is identified by an integer number. Visibility and rendering order can be set + * individually for each of the layers. Future versions of the VIEW will also allows one to + * assign different layers to different rendering targets, which will be composited at the + * final stage by the GAL. The VIEW class also provides fast methods for finding all visible + * objects that are within a given rectangular area, useful for object selection/hit testing. */ class VIEW { @@ -68,49 +72,52 @@ public: typedef std::pair LAYER_ITEM_PAIR; /** - * Constructor. * @param aIsDynamic decides whether we are creating a static or a dynamic VIEW. */ VIEW( bool aIsDynamic = true ); virtual ~VIEW(); - // nasty hack, invoked by the destructor of VIEW_ITEM to auto-remove the item - // from the owning VIEW if there is any. Kicad relies too much on this mechanism. - // this is the only linking dependency now between EDA_ITEM and VIEW class. In near future - // I'll replace it with observers. + /** + * Nasty hack, invoked by the destructor of VIEW_ITEM to auto-remove the item + * from the owning VIEW if there is any. + * + * KiCad relies too much on this mechanism. This is the only linking dependency now + * between #EDA_ITEM and VIEW class. In near future I'll replace it with observers. + */ static void OnDestroy( VIEW_ITEM* aItem ); /** - * Function Add() - * Adds a VIEW_ITEM to the view. - * Set aDrawPriority to -1 to assign sequential priorities. + * Add a #VIEW_ITEM to the view. + * + * Set \a aDrawPriority to -1 to assign sequential priorities. + * * @param aItem: item to be added. No ownership is given * @param aDrawPriority: priority to draw this item on its layer, lowest first. */ virtual void Add( VIEW_ITEM* aItem, int aDrawPriority = -1 ); /** - * Function Remove() - * Removes a VIEW_ITEM from the view. + * Remove a #VIEW_ITEM from the view. + * * @param aItem: item to be removed. Caller must dispose the removed item if necessary */ virtual void Remove( VIEW_ITEM* aItem ); /** - * Function Query() - * Finds all visible items that touch or are within the rectangle aRect. + * Find all visible items that touch or are within the rectangle \a aRect. + * * @param aRect area to search for items * @param aResult result of the search, containing VIEW_ITEMs associated with their layers. - * Sorted according to the rendering order (items that are on top of the rendering stack as - * first). + * Sorted according to the rendering order (items that are on top of the + * rendering stack as first). * @return Number of found items. */ virtual int Query( const BOX2I& aRect, std::vector& aResult ) const; /** - * Sets the item visibility. + * Set the item visibility. * * @param aItem: the item to modify. * @param aIsVisible: whether the item is visible (on all layers), or not. @@ -118,7 +125,7 @@ public: void SetVisible( VIEW_ITEM* aItem, bool aIsVisible = true ); /** - * Temporarily hides the item in the view (e.g. for overlaying) + * Temporarily hide the item in the view (e.g. for overlaying). * * @param aItem: the item to modify. * @param aHide: whether the item is hidden (on all layers), or not. @@ -126,7 +133,7 @@ public: void Hide( VIEW_ITEM* aItem, bool aHide = true ); /** - * Returns information if the item is visible (or not). + * Return information if the item is visible (or not). * * @param aItem: the item to test. * @return when true, the item is visible (i.e. to be displayed, not visible in the @@ -135,7 +142,7 @@ public: bool IsVisible( const VIEW_ITEM* aItem ) const; /** - * For dynamic VIEWs, informs the associated VIEW that the graphical representation of + * For dynamic VIEWs, inform the associated VIEW that the graphical representation of * this item has changed. For static views calling has no effect. * * @param aItem: the item to update. @@ -145,9 +152,9 @@ public: virtual void Update( const VIEW_ITEM* aItem ) const; /** - * Function SetRequired() - * Marks the aRequiredId layer as required for the aLayerId layer. In order to display the + * Mark the \a aRequiredId layer as required for the aLayerId layer. In order to display the * layer, all of its required layers have to be enabled. + * * @param aLayerId is the id of the layer for which we enable/disable the required layer. * @param aRequiredId is the id of the required layer. * @param aRequired tells if the required layer should be added or removed from the list. @@ -155,8 +162,8 @@ public: void SetRequired( int aLayerId, int aRequiredId, bool aRequired = true ); /** - * Function CopySettings() - * Copies layers and visibility settings from another view. + * Copy layers and visibility settings from another view. + * * @param aOtherView: view from which settings will be copied. */ void CopySettings( const VIEW* aOtherView ); @@ -168,15 +175,15 @@ public: */ /** - * Function SetGAL() - * Assigns a rendering device for the VIEW. - * @param aGal: pointer to the GAL output device + * Assign a rendering device for the VIEW. + * + * @param aGal: pointer to the GAL output device. */ void SetGAL( GAL* aGal ); /** - * Function GetGAL() - * Returns the GAL this view is using to draw graphical primitives. + * Return the #GAL this view is using to draw graphical primitives. + * * @return Pointer to the currently used GAL instance. */ inline GAL* GetGAL() const @@ -185,8 +192,7 @@ public: } /** - * Function SetPainter() - * Sets the painter object used by the view for drawing VIEW_ITEMS. + * Set the painter object used by the view for drawing #VIEW_ITEMS. */ inline void SetPainter( PAINTER* aPainter ) { @@ -194,8 +200,8 @@ public: } /** - * Function GetPainter() - * Returns the painter object used by the view for drawing VIEW_ITEMS. + * Return the painter object used by the view for drawing #VIEW_ITEMS. + * * @return Pointer to the currently used Painter instance. */ inline PAINTER* GetPainter() const @@ -204,30 +210,29 @@ public: } /** - * Function SetViewport() - * Sets the visible area of the VIEW. + * Set the visible area of the VIEW. + * * @param aViewport: desired visible area, in world space coordinates. */ void SetViewport( const BOX2D& aViewport ); /** - * Function GetViewport() - * Returns the current viewport visible area rectangle. - * @return Current viewport rectangle + * Return the current viewport visible area rectangle. + * + * @return Current viewport rectangle. */ BOX2D GetViewport() const; /** - * Function SetMirror() - * Controls the mirroring of the VIEW. - * @param aMirrorX: when true, the X axis is mirrored - * @param aMirrorY: when true, the Y axis is mirrored. + * Control the mirroring of the VIEW. + * + * @param aMirrorX: when true, the X axis is mirrored. + * @param aMirrorY: when true, the Y axis is mirrored. */ void SetMirror( bool aMirrorX, bool aMirrorY ); /** - * Function IsMirroredX() - * Returns true if view is flipped across the X axis. + * Return true if view is flipped across the X axis. */ bool IsMirroredX() const { @@ -235,8 +240,7 @@ public: } /** - * Function IsMirroredX() - * Returns true if view is flipped across the Y axis. + * Return true if view is flipped across the Y axis. */ bool IsMirroredY() const { @@ -244,16 +248,16 @@ public: } /** - * Function SetScale() - * Sets the scaling factor, zooming around a given anchor point. + * Set the scaling factor, zooming around a given anchor point. + * * (depending on correct GAL unit length & DPI settings). - * @param aAnchor: the zooming anchor point - * @param aScale: the scale factor + * + * @param aAnchor is the zooming anchor point. + * @param aScale is the scale factor. */ virtual void SetScale( double aScale, VECTOR2D aAnchor = { 0, 0 } ); /** - * Function GetScale() * @return Current scale factor of this VIEW. */ inline double GetScale() const @@ -262,8 +266,8 @@ public: } /** - * Function SetBoundary() - * Sets limits for view area. + * Set limits for view area. + * * @param aBoundary is the box that limits view area. */ inline void SetBoundary( const BOX2D& aBoundary ) @@ -272,8 +276,8 @@ public: } /** - * Function SetBoundary() - * Sets limits for view area. + * Set limits for view area. + * * @param aBoundary is the box that limits view area. */ inline void SetBoundary( const BOX2I& aBoundary ) @@ -283,7 +287,6 @@ public: } /** - * Function GetBoundary() * @return Current view area boundary. */ inline const BOX2D& GetBoundary() const @@ -292,8 +295,8 @@ public: } /** - * Function SetScaleLimits() - * Sets minimum and maximum values for scale. + * Set minimum and maximum values for scale. + * * @param aMaximum is the maximum value for scale. * @param aMinimum is the minimum value for scale. */ @@ -306,25 +309,25 @@ public: } /** - * Function SetCenter() - * Sets the center point of the VIEW (i.e. the point in world space that will be drawn in the middle - * of the screen). + * Set the center point of the VIEW (i.e. the point in world space that will be drawn in + * the middle of the screen). + * * @param aCenter: the new center point, in world space coordinates. */ void SetCenter( const VECTOR2D& aCenter ); /** - * Function SetCenter() - * Sets the center point of the VIEW, attempting to avoid \a occultingScreenRect (for + * Set the center point of the VIEW, attempting to avoid \a occultingScreenRect (for * instance, the screen rect of a modeless dialog in front of the VIEW). + * * @param aCenter: the new center point, in world space coordinates. * @param occultingScreenRect: the occulting rect, in screen space coordinates. */ void SetCenter( VECTOR2D aCenter, const BOX2D& occultingScreenRect ); /** - * Function GetCenter() - * Returns the center point of this VIEW (in world space coordinates) + * Return the center point of this VIEW (in world space coordinates). + * * @return center point of the view */ const VECTOR2D& GetCenter() const @@ -333,54 +336,53 @@ public: } /** - * Function ToWorld() * Converts a screen space point/vector to a point/vector in world space coordinates. - * @param aCoord: the point/vector to be converted - * @param aAbsolute: when true, aCoord is treated as a point, otherwise - as a direction (vector) + * + * @param aCoord is the point/vector to be converted. + * @param aAbsolute when true aCoord is treated as a point, otherwise as a direction (vector). */ VECTOR2D ToWorld( const VECTOR2D& aCoord, bool aAbsolute = true ) const; /** - * Function ToWorld() * Converts a screen space one dimensional size to a one dimensional size in world * space coordinates. - * @param aSize : the size to be converted + * + * @param aSize is the size to be converted. */ double ToWorld( double aSize ) const; /** - * Function ToScreen() - * Converts a world space point/vector to a point/vector in screen space coordinates. - * @param aCoord: the point/vector to be converted - * @param aAbsolute: when true, aCoord is treated as a point, otherwise - as a direction (vector) + * Convert a world space point/vector to a point/vector in screen space coordinates. + * + * @param aCoord is the point/vector to be converted. + * @param aAbsolute when true aCoord is treated as a point, otherwise as a direction (vector). */ VECTOR2D ToScreen( const VECTOR2D& aCoord, bool aAbsolute = true ) const; /** - * Function ToScreen() - * Converts a world space one dimensionsal size to a one dimensional size in screen space. + * Convert a world space one dimensional size to a one dimensional size in screen space. + * * @param aSize: the size to be transformed. */ double ToScreen( double aSize ) const; /** - * Function GetScreenPixelSize() - * Returns the size of the our rendering area, in pixels. - * @return viewport screen size + * Return the size of the our rendering area in pixels. + * + * @return viewport screen size. */ const VECTOR2I& GetScreenPixelSize() const; /** - * Function Clear() - * Removes all items from the view. + * Remove all items from the view. */ void Clear(); /** - * Function SetLayerVisible() - * Controls the visibility of a particular layer. - * @param aLayer: the layer to show/hide. - * @param aVisible: the obvious. + * Control the visibility of a particular layer. + * + * @param aLayer is the layer to show/hide. + * @param aVisible is the layer visibility state. */ inline void SetLayerVisible( int aLayer, bool aVisible = true ) { @@ -395,9 +397,9 @@ public: } /** - * Function IsLayerVisible() - * Returns information about visibility of a particular layer. - * @param aLayer: true if the layer is visible, false otherwise + * Return information about visibility of a particular layer. + * + * @param aLayer true if the layer is visible, false otherwise. */ inline bool IsLayerVisible( int aLayer ) const { @@ -412,8 +414,8 @@ public: } /** - * Function SetLayerTarget() - * Changes the rendering target for a particular layer. + * Change the rendering target for a particular layer. + * * @param aLayer is the layer. * @param aTarget is the rendering target. */ @@ -424,69 +426,71 @@ public: } /** - * Function SetLayerOrder() - * Sets rendering order of a particular layer. Lower values are rendered first. - * @param aLayer: the layer - * @param aRenderingOrder: arbitrary number denoting the rendering order. + * Set rendering order of a particular layer. Lower values are rendered first. + * + * @param aLayer is the layer. + * @param aRenderingOrder is an arbitrary number denoting the rendering order. */ void SetLayerOrder( int aLayer, int aRenderingOrder ); /** - * Function GetLayerOrder() - * Returns rendering order of a particular layer. Lower values are rendered first. - * @param aLayer: the layer + * Return rendering order of a particular layer. Lower values are rendered first. + * + * @param aLayer is the layer. * @return Rendering order of a particular layer. */ int GetLayerOrder( int aLayer ) const; /** - * Function SortLayers() - * Changes the order of given layer ids, so after sorting the order corresponds to layers + * Change the order of given layer ids, so after sorting the order corresponds to layers * rendering order (descending, ie. order in which layers should be drawn - from the bottom to * the top). + * * @param aLayers stores id of layers to be sorted. * @param aCount stores the number of layers. */ void SortLayers( int aLayers[], int& aCount ) const; /** - * Remaps the data between layer ids without invalidating that data + * Remap the data between layer ids without invalidating that data. * - * Used by GerbView for the "Sort by X2" functionality + * Used by GerbView for the "Sort by X2" functionality. * - * @param aReorderMap is a mapping of old to new layer ids + * @param aReorderMap is a mapping of old to new layer ids. */ void ReorderLayerData( std::unordered_map aReorderMap ); /** - * Function UpdateLayerColor() - * Applies the new coloring scheme held by RENDER_SETTINGS in case that it has changed. + * Apply the new coloring scheme held by RENDER_SETTINGS in case that it has changed. + * * @param aLayer is a number of the layer to be updated. * @see RENDER_SETTINGS */ void UpdateLayerColor( int aLayer ); /** - * Function UpdateAllLayersColor() - * Applies the new coloring scheme to all layers. The used scheme is held by RENDER_SETTINGS. + * Apply the new coloring scheme to all layers. The used scheme is held by #RENDER_SETTINGS. + * * @see RENDER_SETTINGS */ void UpdateAllLayersColor(); /** - * Function SetTopLayer() - * Sets given layer to be displayed on the top or sets back the default order of layers. + * Set given layer to be displayed on the top or sets back the default order of layers. + * * @param aEnabled = true to display aLayer on the top. - * @param aLayer: the layer or -1 in case when no particular layer should - * be displayed on the top. + * @param aLayer is the layer or -1 in case when no particular layer should be displayed + * on the top. */ virtual void SetTopLayer( int aLayer, bool aEnabled = true ); /** - * Function EnableTopLayer() - * Enables or disables display of the top layer. When disabled - layers are rendered as usual - * with no influence from SetTopLayer function. Otherwise on the top there is displayed the - * layer set previously with SetTopLayer function. + * Enable or disable display of the top layer. + * + * When disabled, layers are rendered as usual with no influence from SetTopLayer + * function. Otherwise on the top there is displayed the layer set previously with + * SetTopLayer function. + * * @param aEnable whether to enable or disable display of the top layer. */ virtual void EnableTopLayer( bool aEnable ); @@ -494,40 +498,35 @@ public: virtual int GetTopLayer() const; /** - * Function ClearTopLayers() - * Removes all layers from the on-the-top set (they are no longer displayed over the rest of + * Remove all layers from the on-the-top set (they are no longer displayed over the rest of * layers). */ void ClearTopLayers(); /** - * Function UpdateLayerOrder() - * Does everything that is needed to apply the rendering order of layers. It has to be called - * after modification of renderingOrder field of LAYER. + * Do everything that is needed to apply the rendering order of layers. + * + * It has to be called after modification of renderingOrder field of LAYER. */ void UpdateAllLayersOrder(); /** - * Function ClearTargets() - * Clears targets that are marked as dirty. + * Clear targets that are marked as dirty. */ void ClearTargets(); /** - * Function Redraw() * Immediately redraws the whole view. */ virtual void Redraw(); /** - * Function RecacheAllItems() - * Rebuilds GAL display lists. + * Rebuild GAL display lists. */ void RecacheAllItems(); /** - * Function IsDynamic() - * Tells if the VIEW is dynamic (ie. can be changed, for example displaying PCBs in a window) + * Tell if the VIEW is dynamic (ie. can be changed, for example displaying PCBs in a window) * or static (that cannot be modified, eg. displaying image/PDF). */ bool IsDynamic() const @@ -536,8 +535,8 @@ public: } /** - * Function IsDirty() - * Returns true if any of the VIEW layers needs to be refreshened. + * Return true if any of the VIEW layers needs to be refreshened. + * * @return True in case if any of layers is marked as dirty. */ bool IsDirty() const @@ -552,9 +551,9 @@ public: } /** - * Function IsTargetDirty() - * Returns true if any of layers belonging to the target or the target itself should be + * Return true if any of layers belonging to the target or the target itself should be * redrawn. + * * @return True if the above condition is fulfilled. */ bool IsTargetDirty( int aTarget ) const @@ -564,8 +563,8 @@ public: } /** - * Function MarkTargetDirty() - * Sets or clears target 'dirty' flag. + * Set or clear target 'dirty' flag. + * * @param aTarget is the target to set. */ inline void MarkTargetDirty( int aTarget ) @@ -574,7 +573,7 @@ public: m_dirtyTargets[aTarget] = true; } - /// Returns true if the layer is cached + /// Return true if the layer is cached. inline bool IsCached( int aLayer ) const { wxCHECK( aLayer < (int) m_layers.size(), false ); @@ -590,8 +589,7 @@ public: } /** - * Function MarkDirty() - * Forces redraw of view on the next rendering. + * Force redraw of view on the next rendering. */ void MarkDirty() { @@ -600,34 +598,34 @@ public: } /** - * Function MarkForUpdate() - * Adds an item to a list of items that are going to be refreshed upon the next frame rendering. + * Add an item to a list of items that are going to be refreshed upon the next frame rendering. + * * @param aItem is the item to be refreshed. */ void MarkForUpdate( VIEW_ITEM* aItem ); /** - * Function UpdateItems() - * Iterates through the list of items that asked for updating and updates them. + * Iterate through the list of items that asked for updating and updates them. */ void UpdateItems(); /** - * Updates all items in the view according to the given flags + * Update all items in the view according to the given flags. + * * @param aUpdateFlags is is according to KIGFX::VIEW_UPDATE_FLAGS */ void UpdateAllItems( int aUpdateFlags ); /** - * Updates items in the view according to the given flags and condition - * @param aUpdateFlags is is according to KIGFX::VIEW_UPDATE_FLAGS - * @param aCondition is a function returning true if the item should be updated + * Update items in the view according to the given flags and condition. + * + * @param aUpdateFlags is is according to KIGFX::VIEW_UPDATE_FLAGS. + * @param aCondition is a function returning true if the item should be updated. */ void UpdateAllItemsConditionally( int aUpdateFlags, std::function aCondition ); /** - * Function IsUsingDrawPriority() * @return true if draw priority is being respected while redrawing. */ bool IsUsingDrawPriority() const @@ -636,7 +634,6 @@ public: } /** - * Function UseDrawPriority() * @param aFlag is true if draw priority should be respected while redrawing. */ void UseDrawPriority( bool aFlag ) @@ -645,7 +642,6 @@ public: } /** - * Function IsDrawOrderReversed() * @return true if draw order is reversed */ bool IsDrawOrderReversed() const @@ -654,8 +650,8 @@ public: } /** - * Function ReverseDrawOrder() * Only takes effect if UseDrawPriority is true. + * * @param aFlag is true if draw order should be reversed */ void ReverseDrawOrder( bool aFlag ) @@ -673,38 +669,125 @@ public: void ShowPreview( bool aShow = true ); /** - * Returns a new VIEW object that shares the same set of VIEW_ITEMs and LAYERs. + * Return a new VIEW object that shares the same set of VIEW_ITEMs and LAYERs. + * * GAL, PAINTER and other properties are left uninitialized. */ std::unique_ptr DataReference() const; /** + * Get the current print mode. + * + * Return values less than or equal to zero indicate the current mode is the draw mode. + * Return values greater than zero indicate print mode. + * @return the printing mode. - * if return <= 0, the current mode is not a printing mode, just the draw mode */ int GetPrintMode() { return m_printMode; } /** * Set the printing mode. - * @param aPrintMode is the printing mode. - * If 0, the current mode is not a printing mode, just the draw mode + * + * @param aPrintMode is the printing mode. If 0, the current mode is not a printing mode, + * just the draw mode */ void SetPrintMode( int aPrintMode ) { m_printMode = aPrintMode; } - static constexpr int VIEW_MAX_LAYERS = 512; ///< maximum number of layers that may be shown + static constexpr int VIEW_MAX_LAYERS = 512; ///< maximum number of layers that may be shown protected: struct VIEW_LAYER { - bool visible; ///< is the layer to be rendered? - bool displayOnly; ///< is the layer display only? + bool visible; ///< Is the layer to be rendered? + bool displayOnly; ///< Is the layer display only? std::shared_ptr items; ///< R-tree indexing all items on this layer. - int renderingOrder; ///< rendering order of this layer - int id; ///< layer ID - RENDER_TARGET target; ///< where the layer should be rendered - std::set requiredLayers; ///< layers that have to be enabled to show the layer + int renderingOrder; ///< Rendering order of this layer. + int id; ///< Layer ID. + RENDER_TARGET target; ///< Where the layer should be rendered. + std::set requiredLayers; ///< Layers that have to be enabled to show + ///< the layer. }; + + + VIEW( const VIEW& ) = delete; + + ///* Redraws contents within rect aRect + void redrawRect( const BOX2I& aRect ); + + inline void markTargetClean( int aTarget ) + { + wxCHECK( aTarget < TARGETS_NUMBER, /* void */ ); + m_dirtyTargets[aTarget] = false; + } + + /** + * Draw an item, but on a specified layers. + * + * It has to be marked that some of drawing settings are based on the layer on which + * an item is drawn. + * + * @param aItem is the item to be drawn. + * @param aLayer is the layer which should be drawn. + * @param aImmediate dictates the way of drawing - it allows one to force immediate + * drawing mode for cached items. + */ + void draw( VIEW_ITEM* aItem, int aLayer, bool aImmediate = false ); + + /** + * Draw an item on all layers that the item uses. + * + * @param aItem is the item to be drawn. + * @param aImmediate dictates the way of drawing - it allows one to force immediate + * drawing mode for cached items. + */ + void draw( VIEW_ITEM* aItem, bool aImmediate = false ); + + /** + * Draw a group of items on all layers that those items use. + * + * @param aGroup is the group to be drawn. + * @param aImmediate dictates the way of drawing - it allows one to force immediate + * drawing mode for cached items. + */ + void draw( VIEW_GROUP* aGroup, bool aImmediate = false ); + + ///< Sort m_orderedLayers when layer rendering order has changed + void sortLayers(); + + ///< Clear cached GAL group numbers (*ONLY* numbers stored in VIEW_ITEMs, not group objects + ///< used by GAL) + void clearGroupCache(); + + /** + * Manage dirty flags & redraw queuing when updating an item. + * + * @param aItem is the item to be updated. + * @param aUpdateFlags determines the way an item is refreshed. + */ + void invalidateItem( VIEW_ITEM* aItem, int aUpdateFlags ); + + ///< Update colors that are used for an item to be drawn + void updateItemColor( VIEW_ITEM* aItem, int aLayer ); + + ///< Update all information needed to draw an item + void updateItemGeometry( VIEW_ITEM* aItem, int aLayer ); + + ///< Update bounding box of an item + void updateBbox( VIEW_ITEM* aItem ); + + ///< Update set of layers that an item occupies + void updateLayers( VIEW_ITEM* aItem ); + + ///< Determine rendering order of layers. Used in display order sorting function. + static bool compareRenderingOrder( VIEW_LAYER* aI, VIEW_LAYER* aJ ) + { + return aI->renderingOrder > aJ->renderingOrder; + } + + ///< Check if every layer required by the aLayerId layer is enabled. + bool areRequiredLayersEnabled( int aLayerId ) const; + // Function objects that need to access VIEW/VIEW_ITEM private/protected members struct clearLayerCache; struct recacheItem; @@ -717,150 +800,70 @@ protected: std::unique_ptr m_preview; std::vector m_ownedItems; - ///* Redraws contents within rect aRect - void redrawRect( const BOX2I& aRect ); - - inline void markTargetClean( int aTarget ) - { - wxCHECK( aTarget < TARGETS_NUMBER, /* void */ ); - m_dirtyTargets[aTarget] = false; - } - - /** - * Function draw() - * Draws an item, but on a specified layers. It has to be marked that some of drawing settings - * are based on the layer on which an item is drawn. - * - * @param aItem is the item to be drawn. - * @param aLayer is the layer which should be drawn. - * @param aImmediate dictates the way of drawing - it allows one to force - * immediate drawing mode for cached items. - */ - void draw( VIEW_ITEM* aItem, int aLayer, bool aImmediate = false ); - - /** - * Function draw() - * Draws an item on all layers that the item uses. - * - * @param aItem is the item to be drawn. - * @param aImmediate dictates the way of drawing - it allows one to force - * immediate drawing mode for cached items. - */ - void draw( VIEW_ITEM* aItem, bool aImmediate = false ); - - /** - * Function draw() - * Draws a group of items on all layers that those items use. - * - * @param aGroup is the group to be drawn. - * @param aImmediate dictates the way of drawing - it allows one to force - * immediate drawing mode for cached items. - */ - void draw( VIEW_GROUP* aGroup, bool aImmediate = false ); - - ///* Sorts m_orderedLayers when layer rendering order has changed - void sortLayers(); - - ///* Clears cached GAL group numbers (*ONLY* numbers stored in VIEW_ITEMs, not group objects - ///* used by GAL) - void clearGroupCache(); - - /** - * Function invalidateItem() - * Manages dirty flags & redraw queueing when updating an item. - * @param aItem is the item to be updated. - * @param aUpdateFlags determines the way an item is refreshed. - */ - void invalidateItem( VIEW_ITEM* aItem, int aUpdateFlags ); - - /// Updates colors that are used for an item to be drawn - void updateItemColor( VIEW_ITEM* aItem, int aLayer ); - - /// Updates all informations needed to draw an item - void updateItemGeometry( VIEW_ITEM* aItem, int aLayer ); - - /// Updates bounding box of an item - void updateBbox( VIEW_ITEM* aItem ); - - /// Updates set of layers that an item occupies - void updateLayers( VIEW_ITEM* aItem ); - - /// Determines rendering order of layers. Used in display order sorting function. - static bool compareRenderingOrder( VIEW_LAYER* aI, VIEW_LAYER* aJ ) - { - return aI->renderingOrder > aJ->renderingOrder; - } - - /// Checks if every layer required by the aLayerId layer is enabled. - bool areRequiredLayersEnabled( int aLayerId ) const; - - ///* Whether to use rendering order modifier or not + ///< Whether to use rendering order modifier or not. bool m_enableOrderModifier; - /// Contains set of possible displayed layers and its properties + ///< The set of possible displayed layers and its properties. std::vector m_layers; - /// Sorted list of pointers to members of m_layers + ///< Sorted list of pointers to members of m_layers. std::vector m_orderedLayers; - /// Flat list of all items + ///< Flat list of all items. std::shared_ptr> m_allItems; - /// Stores set of layers that are displayed on the top + ///< The set of layers that are displayed on the top. std::set m_topLayers; - /// Center point of the VIEW (the point at which we are looking at) + ///< Center point of the VIEW (the point at which we are looking at). VECTOR2D m_center; - /// Scale of displayed VIEW_ITEMs + ///< Scale of displayed VIEW_ITEMs. double m_scale; - /// View boundaries + ///< View boundaries. BOX2D m_boundary; - /// Scale lower limit + ///< Scale lower limit. double m_minScale; - /// Scale upper limit + ///< Scale upper limit. double m_maxScale; - ///> Horizontal flip flag + ///< Horizontal flip flag. bool m_mirrorX; - ///> Vertical flip flag + ///< Vertical flip flag. bool m_mirrorY; - /// PAINTER contains information how do draw items + ///< PAINTER contains information how do draw items. PAINTER* m_painter; - /// Gives interface to PAINTER, that is used to draw items + ///< Interface to #PAINTER that is used to draw items. GAL* m_gal; - /// Dynamic VIEW (eg. display PCB in window) allows changes once it is built, - /// static (eg. image/PDF) - does not. + ///< Dynamic VIEW (eg. display PCB in window) allows changes once it is built, + ///< static (eg. image/PDF) - does not. bool m_dynamic; - /// Flags to mark targets as dirty, so they have to be redrawn on the next refresh event + ///< Flag to mark targets as dirty so they have to be redrawn on the next refresh event. bool m_dirtyTargets[TARGETS_NUMBER]; - /// Rendering order modifier for layers that are marked as top layers + ///< Rendering order modifier for layers that are marked as top layers. static const int TOP_LAYER_MODIFIER; - /// Flat list of all items - /// Flag to respect draw priority when drawing items + ///< Flag to respect draw priority when drawing items. bool m_useDrawPriority; - /// The next sequential drawing priority + ///< The next sequential drawing priority. int m_nextDrawPriority; - /// Flag to reverse the draw order when using draw priority + ///< Flag to reverse the draw order when using draw priority. bool m_reverseDrawOrder; - /// A control for printing: m_printMode <= 0 means no printing mode (normal draw mode - /// m_printMode > 0 is a printing mode (currently means "we are in printing mode") + ///< A control for printing: m_printMode <= 0 means no printing mode (normal draw mode + ///< m_printMode > 0 is a printing mode (currently means "we are in printing mode"). int m_printMode; - - VIEW( const VIEW& ) = delete; }; } // namespace KIGFX diff --git a/include/view/view_controls.h b/include/view/view_controls.h index 8124eb4196..f3cdb10e96 100644 --- a/include/view/view_controls.h +++ b/include/view/view_controls.h @@ -3,7 +3,7 @@ * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de * Copyright (C) 2013 CERN - * Copyright (C) 2013-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2013-2020 KiCad Developers, see AUTHORS.txt for contributors. * * @author Tomasz Wlostowski * @@ -41,7 +41,7 @@ namespace KIGFX class VIEW; -///> Action to perform when the mouse is dragged +///< Action to perform when the mouse is dragged enum class MOUSE_DRAG_ACTION { SELECT, @@ -51,7 +51,7 @@ enum class MOUSE_DRAG_ACTION }; -///> Structure to keep VIEW_CONTROLS settings for easy store/restore operations +///< Structure to keep VIEW_CONTROLS settings for easy store/restore operations struct VC_SETTINGS { VC_SETTINGS() @@ -59,87 +59,86 @@ struct VC_SETTINGS Reset(); } - ///> Restores the default settings + ///< Restore the default settings. void Reset(); - ///> Flag determining the cursor visibility + ///< Flag determining the cursor visibility. bool m_showCursor; - ///> Forced cursor position (world coordinates) + ///< Forced cursor position (world coordinates). VECTOR2D m_forcedPosition; - ///> Is the forced cursor position enabled + ///< Is the forced cursor position enabled. bool m_forceCursorPosition; - ///> Should the cursor be locked within the parent window area + ///< Should the cursor be locked within the parent window area. bool m_cursorCaptured; - ///> Should the cursor snap to grid or move freely + ///< Should the cursor snap to grid or move freely. bool m_snappingEnabled; - ///> Flag for grabbing the mouse cursor + ///< Flag for grabbing the mouse cursor. bool m_grabMouse; - ///> Flag for turning on autopanning + ///< Flag for turning on autopanning. bool m_autoPanEnabled; - ///> Flag for turning on autopanning + ///< Flag for turning on autopanning. bool m_autoPanSettingEnabled; - ///> Distance from cursor to VIEW edge when panning is active + ///< Distance from cursor to VIEW edge when panning is active. float m_autoPanMargin; - ///> How fast is panning when in auto mode + ///< How fast is panning when in auto mode. float m_autoPanSpeed; - ///> How fast does panning accelerate when approaching the window boundary + ///< How fast does panning accelerate when approaching the window boundary. float m_autoPanAcceleration; - ///> If the cursor is allowed to be warped + ///< If the cursor is allowed to be warped. bool m_warpCursor; - ///> Enable horizontal panning with the horizontal scroll/trackpad input + ///< Enable horizontal panning with the horizontal scroll/trackpad input. bool m_horizontalPan; - ///> Enable the accelerating zoom controller + ///< Enable the accelerating zoom controller. bool m_zoomAcceleration; - ///> Zoom speed for the non-accelerating zoom controller + ///< Zoom speed for the non-accelerating zoom controller. int m_zoomSpeed; - ///> When true, ignore zoom_speed and pick a platform-specific default + ///< When true, ignore zoom_speed and pick a platform-specific default. bool m_zoomSpeedAuto; - ///> What modifier key to enable zoom with the (vertical) scroll wheel + ///< What modifier key to enable zoom with the (vertical) scroll wheel. int m_scrollModifierZoom; - ///> What modifier key to enable horizontal pan with the (vertical) scroll wheel + ///< What modifier key to enable horizontal pan with the (vertical) scroll wheel. int m_scrollModifierPanH; - ///> What modifier key to enable vertical with the (vertical) scroll wheel + ///< What modifier key to enable vertical with the (vertical) scroll wheel. int m_scrollModifierPanV; - ///> What drag action to perform when the middle button is pressed + ///< What drag action to perform when the middle button is pressed. MOUSE_DRAG_ACTION m_dragMiddle; - ///> What drag action to perform when the right button is pressed + ///< What drag action to perform when the right button is pressed. MOUSE_DRAG_ACTION m_dragRight; - ///> Is last cursor motion event coming from keyboard arrow cursor motion action + ///< Is last cursor motion event coming from keyboard arrow cursor motion action. bool m_lastKeyboardCursorPositionValid; - ///> ACTIONS::CURSOR_UP, ACTIONS::CURSOR_DOWN, etc. + ///< ACTIONS::CURSOR_UP, ACTIONS::CURSOR_DOWN, etc. long m_lastKeyboardCursorCommand; - ///> Position of the above event + ///< Position of the above event. VECTOR2D m_lastKeyboardCursorPosition; }; /** - * VIEW_CONTROLS - * is an interface for classes handling user events controlling the view behaviour - * (such as zooming, panning, mouse grab, etc.) + * An interface for classes handling user events controlling the view behavior such as + * zooming, panning, mouse grab, etc. */ class VIEW_CONTROLS { @@ -154,8 +153,9 @@ public: } /** - * Function SetGrabMouse - * Turns on/off mouse grabbing. When the mouse is grabbed, it cannot go outside the VIEW. + * Turn on/off mouse grabbing. + * When the mouse is grabbed, it cannot go outside the VIEW. + * * @param aEnabled tells if mouse should be grabbed or not. */ virtual void SetGrabMouse( bool aEnabled ) @@ -164,9 +164,9 @@ public: } /** - * Function SetAutoPan - * Turns on/off auto panning (this feature is used when there is a tool active (eg. drawing a + * Turn on/off auto panning (this feature is used when there is a tool active (eg. drawing a * track) and user moves mouse to the VIEW edge - then the view can be translated or not). + * * @param aEnabled tells if the autopanning should be active. */ virtual void SetAutoPan( bool aEnabled ) @@ -175,8 +175,8 @@ public: } /** - * Function EnableAutoPan - * Turns on/off auto panning (user setting to disable it entirely). + * Turn on/off auto panning (user setting to disable it entirely). + * * @param aEnabled tells if the autopanning should be enabled. */ virtual void EnableAutoPan( bool aEnabled ) @@ -185,8 +185,8 @@ public: } /** - * Function SetAutoPanSpeed() - * Sets speed of autopanning. + * Set the speed of autopanning. + * * @param aSpeed is a new speed for autopanning. */ virtual void SetAutoPanSpeed( float aSpeed ) @@ -195,8 +195,8 @@ public: } /** - * Function SetAutoPanSpeed() - * Sets speed of autopanning. + * Set the speed of autopanning. + * * @param aSpeed is a new speed for autopanning. */ virtual void SetAutoPanAcceleration( float aAcceleration ) @@ -205,8 +205,8 @@ public: } /** - * Function SetAutoPanMArgin() - * Sets margin for autopanning (ie. the area when autopanning becomes active). + * Set the margin for autopanning (ie. the area when autopanning becomes active). + * * @param aMargin is a new margin for autopanning. */ virtual void SetAutoPanMargin( float aMargin ) @@ -215,20 +215,22 @@ public: } /** - * Function GetMousePosition() - * Returns the current mouse pointer position. Note, that it may be - * different from the cursor position if snapping is enabled (@see GetCursorPosition()). + * Return the current mouse pointer position. + * + * @note The position may be different from the cursor position if snapping is + * enabled (@see GetCursorPosition()). * * @param aWorldCoordinates if true, the result is given in world coordinates, otherwise - * it is given in screen coordinates. + * it is given in screen coordinates. * @return The current mouse pointer position in either world or screen coordinates. */ virtual VECTOR2D GetMousePosition( bool aWorldCoordinates = true ) const = 0; /** - * Returns the current cursor position in world coordinates. Note, that it may be - * different from the mouse pointer position if snapping is enabled or cursor position - * is forced to a specific point. + * Return the current cursor position in world coordinates. + * + * @note The position may be different from the mouse pointer position if snapping is + * enabled or cursor position is forced to a specific point. * * @return The current cursor position in world coordinates. */ @@ -238,7 +240,7 @@ public: } /** - * Returns the current cursor position in world coordinates - ingoring the cursorUp + * Return the current cursor position in world coordinates ignoring the cursorUp * position force mode. * * @return The current cursor position in world coordinates. @@ -246,9 +248,10 @@ public: virtual VECTOR2D GetRawCursorPosition( bool aSnappingEnabled = true ) const = 0; /** - * Returns the current cursor position in world coordinates. Note, that it may be - * different from the mouse pointer position if snapping is enabled or cursor position - * is forced to a specific point. + * Return the current cursor position in world coordinates. + * + * @note The position may be different from the mouse pointer position if snapping is + * enabled or cursor position is forced to a specific point. * * @param aEnableSnapping selects whether cursor position should be snapped to the grid. * @return The current cursor position in world coordinates. @@ -256,8 +259,8 @@ public: virtual VECTOR2D GetCursorPosition( bool aEnableSnapping ) const = 0; /** - * Function ForceCursorPosition() - * Places the cursor immediately at a given point. Mouse movement is ignored. + * Place the cursor immediately at a given point. Mouse movement is ignored. + * * @param aEnabled enable forced cursor position * @param aPosition the position (world coordinates). */ @@ -268,9 +271,11 @@ public: } /** - * Moves cursor to the requested position expressed in world coordinates. The position is not - * forced and will be overridden with the next mouse motion event. Mouse cursor follows the - * world cursor. + * Move cursor to the requested position expressed in world coordinates. + * + * The position is not forced and will be overridden with the next mouse motion event. + * Mouse cursor follows the world cursor. + * * @param aPosition is the requested cursor position in the world coordinates. * @param aWarpView enables/disables view warp if the cursor is outside the current viewport. */ @@ -279,16 +284,15 @@ public: /** - * Moves the graphic crosshair cursor to the requested position expressed in world coordinates. + * Move the graphic crosshair cursor to the requested position expressed in world coordinates. + * * @param aPosition is the requested cursor position in the world coordinates. * @param aWarpView enables/disables view warp if the cursor is outside the current viewport. */ virtual void SetCrossHairCursorPosition( const VECTOR2D& aPosition, bool aWarpView = true ) = 0; - /** - * Function ForcedCursorPosition() - * Returns true if the current cursor position is forced to a specific location, ignoring + * Return true if the current cursor position is forced to a specific location, ignoring * the mouse cursor position. */ bool ForcedCursorPosition() const @@ -297,22 +301,22 @@ public: } /** - * Function ShowCursor() - * Enables or disables display of cursor. + * Enable or disables display of cursor. + * * @param aEnabled decides if the cursor should be shown. */ virtual void ShowCursor( bool aEnabled ); /** - * Function IsCursorShown() - * Returns true when cursor is visible. + * Return true when cursor is visible. + * * @return True if cursor is visible. */ bool IsCursorShown() const; /** - * Function CaptureCursor() - * Forces the cursor to stay within the drawing panel area. + * Force the cursor to stay within the drawing panel area. + * * @param aEnabled determines if the cursor should be captured. */ virtual void CaptureCursor( bool aEnabled ) @@ -321,9 +325,9 @@ public: } /** - * Function IsCursorPositionForced() - * Returns true if the cursor position is set by one of the tools. Forced cursor position - * means it does not react to mouse movement. + * Return true if the cursor position is set by one of the tools. + * + * A forced cursor position means it does not react to mouse movement. */ inline bool IsCursorPositionForced() const { @@ -331,21 +335,22 @@ public: } /** - * Function WarpCursor() * If enabled (@see SetEnableCursorWarping(), warps the cursor to the specified position, * expressed either in the screen coordinates or the world coordinates. + * * @param aPosition is the position where the cursor should be warped. * @param aWorldCoordinates if true treats aPosition as the world coordinates, otherwise it - * uses it as the screen coordinates. + * uses it as the screen coordinates. * @param aWarpView determines if the view can be warped too (only matters if the position is - * specified in the world coordinates and its not visible in the current viewport). + * specified in the world coordinates and its not visible in the current + * viewport). */ virtual void WarpCursor( const VECTOR2D& aPosition, bool aWorldCoordinates = false, bool aWarpView = false ) = 0; /** - * Function EnableCursorWarping() - * Enables or disables warping the cursor. + * Enable or disable warping the cursor. + * * @param aEnable is true if the cursor is allowed to be warped. */ void EnableCursorWarping( bool aEnable ) @@ -354,7 +359,6 @@ public: } /** - * Function IsCursorWarpingEnabled() * @return the current setting for cursor warping. */ bool IsCursorWarpingEnabled() const @@ -363,38 +367,36 @@ public: } /** - * Function CenterOnCursor() - * Sets the viewport center to the current cursor position and warps the cursor to the + * Set the viewport center to the current cursor position and warps the cursor to the * screen center. */ virtual void CenterOnCursor() const = 0; /** - * Function Reset() - * Restores the default VIEW_CONTROLS settings. + * Restore the default VIEW_CONTROLS settings. */ virtual void Reset(); - ///> Returns the current VIEW_CONTROLS settings + ///< Return the current VIEW_CONTROLS settings. const VC_SETTINGS& GetSettings() const { return m_settings; } - ///> Applies VIEW_CONTROLS settings from an object + ///< Apply VIEW_CONTROLS settings from an object. void ApplySettings( const VC_SETTINGS& aSettings ); - ///> Load new settings from program common settings + ///< Load new settings from program common settings. virtual void LoadSettings() {} protected: - ///> Pointer to controlled VIEW. + ///< Pointer to controlled VIEW. VIEW* m_view; - ///> Application warped the cursor, not the user (keyboard) + ///< Application warped the cursor, not the user (keyboard). bool m_cursorWarped; - ///> Current VIEW_CONTROLS settings + ///< Current VIEW_CONTROLS settings. VC_SETTINGS m_settings; }; } // namespace KIGFX diff --git a/include/view/view_group.h b/include/view/view_group.h index 2485ca8c97..08fe55a510 100644 --- a/include/view/view_group.h +++ b/include/view/view_group.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Maciej Suminski * * This program is free software; you can redistribute it and/or @@ -25,9 +27,6 @@ /** * @file view_group.h - * @brief VIEW_GROUP extends VIEW_ITEM by possibility of grouping items into a single object. - * VIEW_GROUP does not take over ownership of the held items. The main purpose of this class is - * to group items and draw them on a single layer (in particular the overlay). */ #ifndef VIEW_GROUP_H_ @@ -38,59 +37,55 @@ namespace KIGFX { - +/** + * Extend #VIEW_ITEM by possibility of grouping items into a single object. + * + * VIEW_GROUP does not take over ownership of the held items. The main purpose of this class is + * to group items and draw them on a single layer (in particular the overlay). + */ class VIEW_GROUP : public VIEW_ITEM { -protected: - typedef std::vector ITEMS; - public: VIEW_GROUP( VIEW* aView = NULL ); virtual ~VIEW_GROUP(); /** - * Function GetSize() - * Returns the number of stored items. + * Return the number of stored items. * * @return Number of stored items. */ virtual unsigned int GetSize() const; /** - * Function Add() - * Adds an item to the group. + * Add an item to the group. * * @param aItem is the item to be added. */ virtual void Add( VIEW_ITEM* aItem ); /** - * Function Remove() - * Removes an item from the group. + * Remove an item from the group. * * @param aItem is the item to be removed. */ virtual void Remove( VIEW_ITEM* aItem ); /** - * Function Clear() - * Removes all the stored items from the group. + * Remove all the stored items from the group. */ virtual void Clear(); virtual VIEW_ITEM* GetItem( unsigned int aIdx ) const; /** - * Function ViewBBox() - * Returns the bounding box for all stored items covering all its layers. + * Return the bounding box for all stored items covering all its layers. * * @return The current bounding box */ virtual const BOX2I ViewBBox() const override; /** - * Function ViewDraw() - * Draws all the stored items in the group on the given layer. + * Draw all the stored items in the group on the given layer. * * @param aLayer is the layer which should be drawn. * @param aView is the VIEW that should be used for drawing. @@ -98,8 +93,7 @@ public: virtual void ViewDraw( int aLayer, VIEW* aView ) const override; /** - * Function ViewGetLayers() - * Returns all the layers used by the stored items. + * Return all the layers used by the stored items. * * @param aLayers[] is the output layer index array. * @param aCount is the number of layer indices in aLayers[]. @@ -107,8 +101,7 @@ public: virtual void ViewGetLayers( int aLayers[], int& aCount ) const override; /** - * Function SetLayer() - * Sets layer used to draw the group. + * Set layer used to draw the group. * * @param aLayer is the layer used for drawing. */ @@ -118,20 +111,19 @@ public: } /** - * Function FreeItems() - * Frees all the items that were added to the group. + * Free all the items that were added to the group. */ void FreeItems(); protected: + typedef std::vector ITEMS; virtual const ITEMS updateDrawList() const; - /// Layer on which the group is drawn + ///< Layer on which the group is drawn. int m_layer; -protected: - /// Container for storing VIEW_ITEMs + ///< Container for storing VIEW_ITEMs. ITEMS m_groupItems; }; diff --git a/include/view/view_item.h b/include/view/view_item.h index 11bf1dce15..d4fc76d6ec 100644 --- a/include/view/view_item.h +++ b/include/view/view_item.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013-2016 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -43,43 +45,37 @@ class VIEW; class VIEW_ITEM_DATA; /** - * Enum VIEW_UPDATE_FLAGS. - * Defines the how severely the shape/appearance of the item has been changed: - * - NONE: TODO - * - APPEARANCE: shape or layer set of the item have not been affected, - * only colors or visibility. - * - COLOR: - * - GEOMETRY: shape or layer set of the item have changed, VIEW may need to reindex it. - * - LAYERS: TODO - * - ALL: all the flags above */ + * Define the how severely the appearance of the item has been changed. + */ enum VIEW_UPDATE_FLAGS { - NONE = 0x00, /// No updates are required - APPEARANCE = 0x01, /// Visibility flag has changed - COLOR = 0x02, /// Color has changed - GEOMETRY = 0x04, /// Position or shape has changed - LAYERS = 0x08, /// Layers have changed - INITIAL_ADD = 0x10, /// Item is being added to the view - REPAINT = 0x20, /// Item needs to be redrawn - ALL = 0xef /// All except INITIAL_ADD + NONE = 0x00, ///< No updates are required. + APPEARANCE = 0x01, ///< Visibility flag has changed. + COLOR = 0x02, ///< Color has changed. + GEOMETRY = 0x04, ///< Position or shape has changed. + LAYERS = 0x08, ///< Layers have changed. + INITIAL_ADD = 0x10, ///< Item is being added to the view. + REPAINT = 0x20, ///< Item needs to be redrawn. + ALL = 0xef ///< All except INITIAL_ADD. }; /** - * Enum VIEW_VISIBILITY_FLAGS. - * Defines the visibility of the item (temporarily hidden, invisible, etc). + * Define the visibility of the item (temporarily hidden, invisible, etc). */ enum VIEW_VISIBILITY_FLAGS { - VISIBLE = 0x01, /// Item is visible (in general) - HIDDEN = 0x02 /// Item is temporarily hidden (e.g. being used by a tool). Overrides VISIBLE flag. + VISIBLE = 0x01, ///< Item is visible (in general) + HIDDEN = 0x02 ///< Item is temporarily hidden (e.g. being used by a tool). + ///< Overrides VISIBLE flag. }; /** - * VIEW_ITEM - - * is an abstract base class for deriving all objects that can be added to a VIEW. + * An abstract base class for deriving all objects that can be added to a VIEW. + * * It's role is to: - * - communicte geometry, appearance and visibility updates to the associated dynamic VIEW, + * - communicate geometry, appearance and visibility updates to the associated dynamic VIEW, * - provide a bounding box for redraw area calculation, - * - (optional) draw the object using the GAL API functions for PAINTER-less implementations. - * VIEW_ITEM objects are never owned by a VIEW. A single VIEW_ITEM can belong to any number of + * - (optional) draw the object using the #GAL API functions for #PAINTER-less implementations. + * + * VIEW_ITEM objects are never owned by a #VIEW. A single VIEW_ITEM can belong to any number of * static VIEWs, but only one dynamic VIEW due to storage of only one VIEW reference. */ class VIEW_ITEM : public INSPECTABLE @@ -95,48 +91,48 @@ public: VIEW_ITEM& operator=( const VIEW_ITEM& aOther ) = delete; /** - * Function ViewBBox() - * returns the bounding box of the item covering all its layers. - * @return BOX2I - the current bounding box + * Return the bounding box of the item covering all its layers. + * + * @return the current bounding box. */ virtual const BOX2I ViewBBox() const = 0; /** - * Function ViewDraw() - * Draws the parts of the object belonging to layer aLayer. - * viewDraw() is an alternative way for drawing objects if - * if there is no PAINTER assigned for the view or if the PAINTER - * doesn't know how to paint this particular implementation of - * VIEW_ITEM. The preferred way of drawing is to design an - * appropriate PAINTER object, the method below is intended only - * for quick hacks and debugging purposes. + * Draw the parts of the object belonging to layer aLayer. * - * @param aLayer: current drawing layer - * @param aView: pointer to the VIEW device we are drawing on + * An alternative way for drawing objects if there is no #PAINTER assigned for the view + * or if the PAINTER doesn't know how to paint this particular implementation of VIEW_ITEM. + * The preferred way of drawing is to design an appropriate PAINTER object, the method + * below is intended only for quick hacks and debugging purposes. + * + * @param aLayer is the current drawing layer. + * @param aView is a pointer to the #VIEW device we are drawing on. */ virtual void ViewDraw( int aLayer, VIEW* aView ) const {} /** - * Function ViewGetLayers() - * Returns the all the layers within the VIEW the object is painted on. For instance, a PAD - * spans zero or more copper layers and a few technical layers. ViewDraw() or PAINTER::Draw() - * is repeatedly called for each of the layers returned by ViewGetLayers(), depending on the - * rendering order. - * @param aLayers[]: output layer index array - * @param aCount: number of layer indices in aLayers[] + * Return the all the layers within the VIEW the object is painted on. + * + * For instance, a #PAD spans zero or more copper layers and a few technical layers. + * ViewDraw() or PAINTER::Draw() is repeatedly called for each of the layers returned + * by ViewGetLayers(), depending on the rendering order. + * + * @param aLayers[] is the output layer index array. + * @param aCount is the number of layer indices in aLayers[]. */ virtual void ViewGetLayers( int aLayers[], int& aCount ) const = 0; /** - * Function ViewGetLOD() - * Returns the level of detail (LOD) of the item. - * A level of detail is the minimal VIEW scale that - * is sufficient for an item to be shown on a given layer. - * @param aLayer: current drawing layer - * @param aView: pointer to the VIEW device we are drawing on - * @return the level of detail. 0 always show the item, because the - * actual zoom level (or VIEW scale) is always > 0 + * Return the level of detail (LOD) of the item. + * + * A level of detail is the minimal #VIEW scale that is sufficient for an item to be shown + * on a given layer. + * + * @param aLayer is the current drawing layer. + * @param aView is a pointer to the #VIEW device we are drawing on. + * @return the level of detail. 0 always show the item, because the actual zoom level + * (or VIEW scale) is always > 0 */ virtual double ViewGetLOD( int aLayer, VIEW* aView ) const { @@ -144,8 +140,6 @@ public: return 0.0; } -public: - VIEW_ITEM_DATA* viewPrivData() const { return m_viewPrivData; @@ -153,7 +147,7 @@ public: void ClearViewPrivData() { - m_viewPrivData = NULL; + m_viewPrivData = nullptr; } private: diff --git a/include/view/view_rtree.h b/include/view/view_rtree.h index 92e72564eb..789f4ad4aa 100644 --- a/include/view/view_rtree.h +++ b/include/view/view_rtree.h @@ -2,6 +2,8 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -34,17 +36,15 @@ namespace KIGFX typedef RTree VIEW_RTREE_BASE; /** - * VIEW_RTREE - - * Implements an R-tree for fast spatial indexing of VIEW items. - * Non-owning. + * Implement an non-owning R-tree for fast spatial indexing of VIEW items. */ class VIEW_RTREE : public VIEW_RTREE_BASE { public: - /** - * Function Insert() - * Inserts an item into the tree. Item's bounding box is taken via its ViewBBox() method. + * Insert an item into the tree. + * + * Item's bounding box is taken via its ViewBBox() method. */ void Insert( VIEW_ITEM* aItem ) { @@ -56,9 +56,9 @@ public: } /** - * Function Remove() - * Removes an item from the tree. Removal is done by comparing pointers, attepmting to remove a copy - * of the item will fail. + * Remove an item from the tree. + * + * Removal is done by comparing pointers, attempting to remove a copy of the item will fail. */ void Remove( VIEW_ITEM* aItem ) { @@ -72,9 +72,8 @@ public: } /** - * Function Query() - * Executes a function object aVisitor for each item whose bounding box intersects - * with aBounds. + * Execute a function object \a aVisitor for each item whose bounding box intersects + * with \a aBounds. */ template void Query( const BOX2I& aBounds, Visitor& aVisitor ) const diff --git a/include/view/wx_view_controls.h b/include/view/wx_view_controls.h index 70967c4178..58711c4e12 100644 --- a/include/view/wx_view_controls.h +++ b/include/view/wx_view_controls.h @@ -3,6 +3,8 @@ * * Copyright (C) 2012 Torsten Hueter, torstenhtr gmx.de * Copyright (C) 2013 CERN + * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors. + * * @author Tomasz Wlostowski * * This program is free software; you can redistribute it and/or @@ -43,8 +45,7 @@ namespace KIGFX class ZOOM_CONTROLLER; /** - * WX_VIEW_CONTROLS - * is a specific implementation of class VIEW_CONTROLS for wxWidgets library. + * An implementation of class #VIEW_CONTROLS for wxWidgets library. */ class WX_VIEW_CONTROLS : public VIEW_CONTROLS, public wxEvtHandler { @@ -65,120 +66,121 @@ public: void onScroll( wxScrollWinEvent& aEvent ); /** - * Function SetGrabMouse() - * Enables/disables mouse cursor grabbing (limits the movement field only to the panel area). + * Enable or disable mouse cursor grabbing (limits the movement field only to the panel area). * * @param aEnabled says whether the option should be enabled or disabled. */ void SetGrabMouse( bool aEnabled ) override; - /// @copydoc VIEW_CONTROLS::GetMousePosition() + ///< @copydoc VIEW_CONTROLS::GetMousePosition() VECTOR2D GetMousePosition( bool aWorldCoordinates = true ) const override; using VIEW_CONTROLS::GetCursorPosition; - /// @copydoc VIEW_CONTROLS::GetCursorPosition() + ///< @copydoc VIEW_CONTROLS::GetCursorPosition() VECTOR2D GetCursorPosition( bool aSnappingEnabled ) const override; - /// @copydoc VIEW_CONTROLS::GetRawCursorPosition() + ///< @copydoc VIEW_CONTROLS::GetRawCursorPosition() VECTOR2D GetRawCursorPosition( bool aSnappingEnabled = true ) const override; void SetCursorPosition( const VECTOR2D& aPosition, bool warpView, bool aTriggeredByArrows, long aArrowCommand ) override; - /// @copydoc VIEW_CONTROLS::SetCrossHairCursorPosition() + ///< @copydoc VIEW_CONTROLS::SetCrossHairCursorPosition() void SetCrossHairCursorPosition( const VECTOR2D& aPosition, bool aWarpView ) override; - /// @copydoc VIEW_CONTROLS::CursorWarp() + ///< @copydoc VIEW_CONTROLS::CursorWarp() void WarpCursor( const VECTOR2D& aPosition, bool aWorldCoordinates = false, bool aWarpView = false ) override; - /// @copydoc VIEW_CONTROLS::CenterOnCursor() + ///< @copydoc VIEW_CONTROLS::CenterOnCursor() void CenterOnCursor() const override; - /// Adjusts the scrollbars position to match the current viewport. + ///< Adjusts the scrollbars position to match the current viewport. void UpdateScrollbars(); - void ForceCursorPosition( bool aEnabled, const VECTOR2D& aPosition = VECTOR2D( 0, 0 ) ) override; + void ForceCursorPosition( bool aEnabled, + const VECTOR2D& aPosition = VECTOR2D( 0, 0 ) ) override; - ///> Applies VIEW_CONTROLS settings from the program COMMON_SETTINGS + ///< Applies VIEW_CONTROLS settings from the program COMMON_SETTINGS void LoadSettings() override; - /// Event that forces mouse move event in the dispatcher (eg. used in autopanning, when mouse - /// cursor does not move in screen coordinates, but does in world coordinates) + ///< Event that forces mouse move event in the dispatcher (eg. used in autopanning, when + ///< mouse cursor does not move in screen coordinates, but does in world coordinates) static const wxEventType EVT_REFRESH_MOUSE; private: - /// Possible states for WX_VIEW_CONTROLS + ///< Possible states for WX_VIEW_CONTROLS. enum STATE { - IDLE = 1, /// Nothing is happening - DRAG_PANNING, /// Panning with mouse button pressed - AUTO_PANNING, /// Panning on approaching borders of the frame - DRAG_ZOOMING, /// Zooming with mouse button pressed + IDLE = 1, ///< Nothing is happening. + DRAG_PANNING, ///< Panning with mouse button pressed. + AUTO_PANNING, ///< Panning on approaching borders of the frame. + DRAG_ZOOMING, ///< Zooming with mouse button pressed. }; /** - * Function handleAutoPanning() - * Computes new viewport settings while in autopanning mode. + * Compute new viewport settings while in autopanning mode. * * @param aEvent is an event to be processed and decide if autopanning should happen. * @return true if it is currently autopanning (ie. autopanning is active and mouse cursor - * is in the area that causes autopanning to happen). + * is in the area that causes autopanning to happen). */ bool handleAutoPanning( const wxMouseEvent& aEvent ); /** - * Sends an event to refresh mouse position. It is mostly used for notifying the tools - * that the cursor position in the world coordinates has changed, whereas the screen coordinates - * remained the same (e.g. frame edge autopanning). + * Send an event to refresh mouse position. + * + * It is mostly used for notifying the tools that the cursor position in the world + * coordinates has changed, whereas the screen coordinates remained the same (e.g. + * frame edge autopanning). */ void refreshMouse(); /** - * Gets the cursor position in the screen coordinates. + * Get the cursor position in the screen coordinates. */ wxPoint getMouseScreenPosition() const; - /// Current state of VIEW_CONTROLS + ///< Current state of VIEW_CONTROLS. STATE m_state; - /// Panel that is affected by VIEW_CONTROLS + ///< Panel that is affected by VIEW_CONTROLS. wxScrolledCanvas* m_parentPanel; - /// Stores information about point where dragging has started + ///< Store information about point where dragging has started. VECTOR2D m_dragStartPoint; - /// Stores information about the center of viewport when dragging has started + ///< Stores information about the center of viewport when dragging has started. VECTOR2D m_lookStartPoint; - /// Current direction of panning (only autopanning mode) + ///< Current direction of panning (only autopanning mode). VECTOR2D m_panDirection; - /// Timer repsonsible for handling autopanning + ///< Timer responsible for handling autopanning. wxTimer m_panTimer; - /// Ratio used for scaling world coordinates to scrollbar position. + ///< Ratio used for scaling world coordinates to scrollbar position. VECTOR2D m_scrollScale; - /// Current scrollbar position + ///< Current scrollbar position. VECTOR2I m_scrollPos; - /// The zoom scale when a drag zoom started + ///< The zoom scale when a drag zoom started. double m_initialZoomScale; #ifdef __WXGTK3__ - /// Last event timestamp used to de-bounce mouse wheel + ///< Last event timestamp used to de-bounce mouse wheel. long int m_lastTimestamp; #endif - /// Current cursor position (world coordinates) + ///< Current cursor position (world coordinates). VECTOR2D m_cursorPos; - /// Flag deciding whether the cursor position should be calculated using the mouse position + ///< Flag deciding whether the cursor position should be calculated using the mouse position. bool m_updateCursor; - /// a ZOOM_CONTROLLER that determines zoom steps. This is platform-specific. + ///< A #ZOOM_CONTROLLER that determines zoom steps. This is platform-specific. std::unique_ptr m_zoomController; }; } // namespace KIGFX diff --git a/include/view/zoom_controller.h b/include/view/zoom_controller.h index d3cfb1c68c..03659e6665 100644 --- a/include/view/zoom_controller.h +++ b/include/view/zoom_controller.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2013-2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2013-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -37,7 +37,7 @@ namespace KIGFX { /** - * Class that handles the response of the zoom scale to external inputs + * Handle the response of the zoom scale to external inputs. */ class ZOOM_CONTROLLER { @@ -45,10 +45,11 @@ public: virtual ~ZOOM_CONTROLLER() = default; /** - * Gets the scale factor produced by a given mousewheel rotation - * @param aRotation rotation of the mouse wheel (this comes from - * wxMouseEvent::GetWheelRotation()) - * @return the scale factor to scroll by + * Get the scale factor produced by a given mousewheel rotation. + * + * @param aRotation rotation of the mouse wheel (this comes from + * wxMouseEvent::GetWheelRotation()). + * @return the scale factor to scroll by. */ virtual double GetScaleForRotation( int aRotation ) = 0; }; @@ -60,23 +61,23 @@ public: class ACCELERATING_ZOOM_CONTROLLER : public ZOOM_CONTROLLER { public: - /// The type of the acceleration timeout + ///< The type of the acceleration timeout. using TIMEOUT = std::chrono::milliseconds; - /// The clock used for the timestamp (guaranteed to be monotonic) + ///< The clock used for the timestamp (guaranteed to be monotonic). using CLOCK = std::chrono::steady_clock; - /// The type of the time stamps + ///< The type of the time stamps. using TIME_PT = std::chrono::time_point; - /// The default timeout, after which a another scroll will not be accelerated + ///< The default timeout, after which a another scroll will not be accelerated. static constexpr TIMEOUT DEFAULT_TIMEOUT = std::chrono::milliseconds( 500 ); - /// The default minimum step factor for accelerating controller + ///< The default minimum step factor for accelerating controller. static constexpr double DEFAULT_ACCELERATION_SCALE = 5.0; /* - * A class interface that provides timestamps for events + * A class interface that provides timestamps for events. */ class TIMESTAMP_PROVIDER { @@ -84,7 +85,7 @@ public: virtual ~TIMESTAMP_PROVIDER() = default; /* - * @return the timestamp at the current time + * @return the timestamp at the current time. */ virtual TIME_PT GetTimestamp() = 0; }; @@ -92,9 +93,9 @@ public: /** * @param aAccTimeout the timeout - if a scroll happens within this timeframe, * the zoom will be faster - * @param aTimestampProv a provider for timestamps. If null, a default will - * be provided, which is the main steady_clock (this is probably what you - * want for real usage) + * @param aTimestampProv a provider for timestamps. If null, a default will be provided, + * which is the main steady_clock (this is probably what you want + * for real usage) */ ACCELERATING_ZOOM_CONTROLLER( double aScale = DEFAULT_ACCELERATION_SCALE, const TIMEOUT& aAccTimeout = DEFAULT_TIMEOUT, @@ -113,15 +114,16 @@ public: } private: - /// The timestamp provider to use (might be provided externally) + ///< The timestamp provider to use (might be provided externally). TIMESTAMP_PROVIDER* m_timestampProv; - /// Any provider owned by this class (the default one, if used) + ///< Any provider owned by this class (the default one, if used). std::unique_ptr m_ownTimestampProv; - /// The timestamp of the last event + ///< The timestamp of the last event. TIME_PT m_lastTimestamp; - /// The timeout value + + ///< The timeout value. TIMEOUT m_accTimeout; /// A multiplier for the minimum zoom step size @@ -130,31 +132,31 @@ private: /** - * A ZOOM_CONTROLLER that zooms by a fixed factor based only on the magnitude - * of the scroll wheel rotation. + * A #ZOOM_CONTROLLER that zooms by a fixed factor based only on the magnitude of the scroll + * wheel rotation. */ class CONSTANT_ZOOM_CONTROLLER : public ZOOM_CONTROLLER { public: /** - * @param aScale a scaling parameter that adjusts the magnitude of the - * scroll. This factor might be dependent on the platform for comfort. + * @param aScale a scaling parameter that adjusts the magnitude of the scroll. This factor + * might be dependent on the platform for comfort. */ CONSTANT_ZOOM_CONTROLLER( double aScale ); double GetScaleForRotation( int aRotation ) override; - /// A suitable (magic) scale factor for GTK3 systems + ///< A suitable (magic) scale factor for GTK3 systems. static constexpr double GTK3_SCALE = 0.002; - /// A suitable (magic) scale factor for Mac systems + ///< A suitable (magic) scale factor for Mac systems. static constexpr double MAC_SCALE = 0.01; - /// Multipler for manual scale ssetting + ///< Multiplier for manual scale ssetting. static constexpr double MANUAL_SCALE_FACTOR = 0.001; private: - /// The scale factor set by the constructor. + ///< The scale factor set by the constructor. double m_scale; };