From 03454684fad10a551c07d03d8d8b202f638f6450 Mon Sep 17 00:00:00 2001 From: Jeff Young Date: Mon, 22 Aug 2022 11:58:09 +0100 Subject: [PATCH] Commenting. --- eeschema/tools/ee_selection_tool.h | 106 ++++++++++++++++------------- pcbnew/tools/pcb_selection_tool.h | 85 +++++++++++++---------- 2 files changed, 105 insertions(+), 86 deletions(-) diff --git a/eeschema/tools/ee_selection_tool.h b/eeschema/tools/ee_selection_tool.h index 353e3c2010..3c64d84da4 100644 --- a/eeschema/tools/ee_selection_tool.h +++ b/eeschema/tools/ee_selection_tool.h @@ -74,34 +74,34 @@ public: void OnIdle( wxIdleEvent& aEvent ); /** - * Return the set of currently selected items. + * @return the set of currently selected items. */ EE_SELECTION& GetSelection(); /** - * Return either an existing selection (filtered), or the selection at the current - * cursor if the existing selection is empty. + * Return either an existing selection (filtered), or the selection at the current cursor + * position if the existing selection is empty. * - * @param aScanTypes an optional type filter indicating the legal KICAD_Ts to be returned. + * @param aScanTypes [optional] List of item types that are acceptable for selection. * @return either the current selection or, if empty, the selection at the cursor. */ EE_SELECTION& RequestSelection( const std::vector& aScanTypes = { SCH_LOCATE_ANY_T } ); /** - * This overload of SelectPoint will create an EE_COLLECTOR and collect hits at location aWhere - * before calling the primary SelectPoint method. + * Perform a click-type selection at a point (usually the cursor position). * - * @param aWhere is the location where the item(s) should be collected - * @param aScanTypes is a list of items that are acceptable for collection - * @param aItem is set to the newly selected item if only one was selected, otherwise is + * @param aWhere Point from which the selection should be made. + * @param aScanTypes [optional] List of item types that are acceptable for selection. + * @param aItem [out, optional] The newly selected item if only one was selected, otherwise * unchanged. - * @param aSelectionCancelledFlag allows the function to inform its caller that a selection - * was canceled (for instance, by clicking outside of the - * disambiguation menu). - * @param aCheckLocked indicates if locked items should be excluded. - * @param aAdd indicates if found item(s) should be added to the selection - * @param aSubtract indicates if found item(s) should be subtracted from the selection - * @param aExclusiveOr indicates if found item(s) should be toggle in the selection + * @param aSelectionCancelledFlag [out] Allows the function to inform its caller that a + * selection was canceled (for instance, by clicking outside of + * the disambiguation menu). + * @param aCheckLocked Indicates if locked items should be excluded. + * @param aAdd Indicates if found item(s) should be added to the selection. + * @param aSubtract Indicates if found item(s) should be subtracted from the selection. + * @param aExclusiveOr Indicates if found item(s) should be toggle in the selection. + * @return true if the selection was modified. */ bool SelectPoint( const VECTOR2I& aWhere, const std::vector& aScanTypes = { SCH_LOCATE_ANY_T }, @@ -109,13 +109,24 @@ public: bool aCheckLocked = false, bool aAdd = false, bool aSubtract = false, bool aExclusiveOr = false ); - ///< Find (but don't select) node under cursor + /** + * Finds a connected item at a point (usually the cursor position). Iterative process with a + * decreasing slop factor. + * @param aPosition Cursor position from which the search should be made. + * @return a connected item or nullptr. + */ EDA_ITEM* GetNode( VECTOR2I aPosition ); - ///< Select node under cursor + /** + * Selects the connected item at the current cursor position. Iterative process with a + * decreasing slop factor. + */ int SelectNode( const TOOL_EVENT& aEvent ); - ///< If node selected then expand to connection, otherwise select connection under cursor + /** + * If a connected item is selected then expand the selection to the entire connection, + * otherwise select connection under the current cursor position. + */ int SelectConnection( const TOOL_EVENT& aEvent ); ///< Clear current selection event handler. @@ -149,14 +160,12 @@ public: void RebuildSelection(); /** - * Select one or more items at the location given by parameter aWhere. + * Collect one or more items at a given point. This method does not attempt to disambiguate + * multiple items and is simply "collecting". * - * This method does not attempt to disambiguate multiple items and is simply "collecting" - * - * @param aCollector is the collector object that will store found item(s) - * @param aWhere is the place where the item should be selected. - * @param aScanTypes is a list of items that are acceptable for collection - * @param aCheckLocked indicates if locked items should be excluded. + * @param aCollector [in, out] Provides collection conditions and stores collected items. + * @param aWhere Point from which the collection should be made. + * @param aScanTypes [optional] A list of item types that are acceptable for collection. */ bool CollectHits( EE_COLLECTOR& aCollector, const VECTOR2I& aWhere, const std::vector& aScanTypes = { SCH_LOCATE_ANY_T } ); @@ -171,27 +180,26 @@ private: * Apply rules to narrow the collection down to selectable objects, and then heuristics * to try and narrow it to a single object. * - * @param collector EE_COLLECTOR with elements to filter + * @param aCollector [in, out] Provides collection conditions and stores collected items. * @param aWhere point where we should narrow (if relevant) * @param aCheckLocked If false, remove locked elements from #collector */ void narrowSelection( EE_COLLECTOR& collector, const VECTOR2I& aWhere, bool aCheckLocked ); /** - * This is the primary SelectPoint method that will prompt the user with a menu to disambiguate - * multiple selections and then finish by adding, subtracting or toggling the item(s) to the - * actual selection group. + * Perform a click-type selection at a point (usually the cursor position). * - * @param aCollector is an EE_COLLECTOR that already has collected items - * @param aWhere position of the selected point - * @param aItem is set to the newly selected item if only one was selected, otherwise is + * @param aCollector [in, out] Provides collection conditions and stores collected items. + * @param aWhere Point from which the selection should be made. + * @param aItem [out, optional] The newly selected item if only one was selected, otherwise * unchanged. - * @param aSelectionCancelledFlag allows the function to inform its caller that a selection - * was canceled (for instance, by clicking outside of the - * disambiguation menu). - * @param aAdd indicates if found item(s) should be added to the selection - * @param aSubtract indicates if found item(s) should be subtracted from the selection - * @param aExclusiveOr indicates if found item(s) should be toggle in the selection + * @param aSelectionCancelledFlag [out] Allows the function to inform its caller that a + * selection was canceled (for instance, by clicking outside of + * the disambiguation menu). + * @param aAdd Indicates if found item(s) should be added to the selection. + * @param aSubtract Indicates if found item(s) should be subtracted from the selection. + * @param aExclusiveOr Indicates if found item(s) should be toggle in the selection. + * @return true if the selection was modified. */ bool selectPoint( EE_COLLECTOR& aCollector, const VECTOR2I& aWhere, EDA_ITEM** aItem = nullptr, bool* aSelectionCancelledFlag = nullptr, bool aAdd = false, @@ -210,34 +218,34 @@ private: int disambiguateCursor( const TOOL_EVENT& aEvent ); /** - * Take necessary action mark an item as selected. + * Take necessary action to mark an item as selected. * - * @param aItem is an item to be selected. + * @param aItem The item to be selected. */ void select( EDA_ITEM* aItem ) override; /** - * Take necessary action mark an item as unselected. + * Take necessary action to mark an item as unselected. * - * @param aItem is an item to be unselected. + * @param aItem The item to be unselected. */ void unselect( EDA_ITEM* aItem ) override; /** * Highlight the item visually. * - * @param aItem is an item to be be highlighted. - * @param aHighlightMode should be either SELECTED or BRIGHTENED - * @param aGroup is the group to add the item to in the BRIGHTENED mode. + * @param aItem The item to be highlighted. + * @param aHighlightMode Either SELECTED or BRIGHTENED + * @param aGroup [otpional] A group to add the item to. */ void highlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override; /** * Unhighlight the item visually. * - * @param aItem is an item to be be highlighted. + * @param aItem is an item to be highlighted. * @param aHighlightMode should be either SELECTED or BRIGHTENED - * @param aGroup is the group to remove the item from. + * @param aGroup [optional] A group to remove the item from. */ void unhighlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override; @@ -247,7 +255,7 @@ private: void updateReferencePoint(); /** - * @return True if the given point is contained in any of selected items' bounding box. + * @return true if the given point is contained in any of selected items' bounding boxes. */ bool selectionContains( const VECTOR2I& aPoint ) const; diff --git a/pcbnew/tools/pcb_selection_tool.h b/pcbnew/tools/pcb_selection_tool.h index 47136a7b4c..9fa6cd2ef4 100644 --- a/pcbnew/tools/pcb_selection_tool.h +++ b/pcbnew/tools/pcb_selection_tool.h @@ -86,17 +86,18 @@ public: int Main( const TOOL_EVENT& aEvent ); /** - * Return the set of currently selected items. + * @return the set of currently selected items. */ PCB_SELECTION& GetSelection(); /** - * Return the current selection set, filtered according to aFlags and aClientFilter. + * Return the current selection, filtered according to aClientFilter. * * If the set is empty, performs the legacy-style hover selection. * - * @param aConfirmLockedItems if true the user will be prompted if they want to drop locked - * items from the selection or override the locks. + * @param aClientFilter A callback to allow tool- or action-specific filtering. + * @param aConfirmLockedItems [optional] Signals that the user shall be asked if they want + * to drop locked items from the selection or override the locks. */ PCB_SELECTION& RequestSelection( CLIENT_SELECTION_FILTER aClientFilter, bool aConfirmLockedItems = false ); @@ -112,24 +113,21 @@ public: int SelectAll( const TOOL_EVENT& aEvent ); /** - * Handle finding an item. Does not do the actual searching, is called - * by the find dialog. + * Take necessary actions to mark an item as found. * - * @param aItem Item that was found and needs to be handled. + * @param aItem The item that was found and needs to be highlighted/focused/etc. */ void FindItem( BOARD_ITEM* aItem ); /** * Take necessary action mark an item as selected. * - * @param aItem is an item to be selected. + * @param aItem The item to be selected. */ void select( EDA_ITEM* aItem ) override; /** - * Check conditions for an item to be selected. - * - * @return True if the item fulfills conditions to be selected. + * @return true if an item fulfills conditions to be selected. */ bool Selectable( const BOARD_ITEM* aItem, bool checkVisibilityOnly = false ) const; @@ -137,8 +135,8 @@ public: * Try to guess best selection candidates in case multiple items are clicked, by doing * some brain-dead heuristics. * - * @param aCollector is the collector that has a list of items to be queried. - * @param aWhere is the selection point to consider + * @param aCollector [in, out] The collector that has a list of items to be narrowed. + * @param aWhere The selection point to consider. */ void GuessSelectionCandidates( GENERAL_COLLECTOR& aCollector, const VECTOR2I& aWhere ) const; @@ -164,15 +162,21 @@ public: ///< Zoom the screen to fit the bounding box for cross probing/selection sync. void zoomFitCrossProbeBBox( EDA_RECT bbox ); + /** + * Enter the group at the head of the current selection. + */ void EnterGroup(); /** - * Leave the currently entered group. + * Leave the currently-entered group. * - * @param aSelectGroup when true will select the group after leaving + * @param aSelectGroup [optional] Select the group after leaving. */ void ExitGroup( bool aSelectGroup = false ); + /** + * @return the currently-entered group. + */ PCB_GROUP* GetEnteredGroup() { return m_enteredGroup; } /** @@ -182,14 +186,19 @@ public: void FilterCollectorForHierarchy( GENERAL_COLLECTOR& aCollector, bool aMultiselect ) const; /** - * Check the "allow free pads" setting and if disabled, upgrade any pad selection to the - * selection of its parent footprint. + * Check the "allow free pads" setting and if disabled, replace any pads in the collector + * with their parent footprints. */ void FilterCollectorForFreePads( GENERAL_COLLECTOR& aCollector ) const; + /** + * Drop any PCB_MARKERs from the collector. + */ void FilterCollectorForMarkers( GENERAL_COLLECTOR& aCollector ) const; - ///< Apply the SELECTION_FILTER_OPTIONS to a collection of items + /** + * Apply the SELECTION_FITLER_OPTIONS to the collector. + */ void FilterCollectedItems( GENERAL_COLLECTOR& aCollector, bool aMultiSelect ); protected: @@ -223,7 +232,6 @@ protected: SELECTION& selection() override { return m_selection; } private: - /** * Select an item pointed by the parameter \a aWhere. * @@ -235,20 +243,20 @@ private: * @param aSelectionCancelledFlag allows the function to inform its caller that a selection * was canceled (for instance, by clicking outside of the * disambiguation menu). - * @param aClientFilter allows the client to perform tool- or action-specific filtering. - * @return True if an item was selected, false otherwise. + * @param aClientFilter a callback to allow tool- or action-specific filtering. + * @return whether or not the selection is empty. */ bool selectPoint( const VECTOR2I& aWhere, bool aOnDrag = false, bool* aSelectionCancelledFlag = nullptr, CLIENT_SELECTION_FILTER aClientFilter = nullptr ); /** - * Select an item under the cursor unless there is something already selected or - * \a aSelectAlways is true. + * Select an item under the cursor unless there is something already selected. * - * @param aForceSelect forces to select an item even if there is an item already selected. - * @param aClientFilter allows the client to perform tool- or action-specific filtering. - * @return true if eventually there is an item selected, false otherwise. + * @param aForceSelect [optional] Forces an item to be selected even if there is already a + * selection. + * @param aClientFilter A callback to allow tool- or action-specific filtering. + * @return whether or not the selection is empty. */ bool selectCursor( bool aForceSelect = false, CLIENT_SELECTION_FILTER aClientFilter = nullptr ); @@ -266,12 +274,12 @@ private: int disambiguateCursor( const TOOL_EVENT& aEvent ); /** - * Expand the current track selection to the next boundary (junctions, pads, or all) + * Expand the current connected-item selection to the next boundary (junctions, pads, or all) */ int expandConnection( const TOOL_EVENT& aEvent ); /** - * Select all copper connections belonging to the same net(s) as the items in the selection + * Select all copper connections belonging to the same net(s) as the items in the selection. */ int selectNet( const TOOL_EVENT& aEvent ); @@ -293,10 +301,10 @@ private: /** * Select connected tracks and vias. * - * @param aStopCondition where to stop selecting more items + * @param aStopCondition Indicates where to stop selecting more items. */ void selectAllConnectedTracks( const std::vector& aStartItems, - STOP_CONDITION aStopCondition ); + STOP_CONDITION aStopCondition ); /** * Select all items with the given net code. @@ -347,26 +355,29 @@ private: /** * Highlight the item visually. * - * @param aItem is an item to be be highlighted. - * @param aHighlightMode should be either SELECTED or BRIGHTENED - * @param aGroup is the group to add the item to in the BRIGHTENED mode. + * @param aItem The item to be highlighted. + * @param aHighlightMode Either SELECTED or BRIGHTENED + * @param aGroup [optional A group to add the item to. */ void highlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override; /** * Unhighlight the item visually. * - * @param aItem is an item to be be highlighted. - * @param aHighlightMode should be either SELECTED or BRIGHTENED - * @param aGroup is the group to remove the item from. + * @param aItem The item to be highlighted. + * @param aHighlightMode Either SELECTED or BRIGHTENED + * @param aGroup [optional] A group to remove the item from. */ void unhighlight( EDA_ITEM* aItem, int aHighlightMode, SELECTION* aGroup = nullptr ) override; /** - * @return True if the given point is contained in any of selected items' bounding box. + * @return true if the given point is contained in any of selected items' bounding boxes. */ bool selectionContains( const VECTOR2I& aPoint ) const; + /** + * @return the distance from \a wWhere to \a aItem, up to and including \a aMaxDistance. + */ int hitTestDistance( const wxPoint& aWhere, BOARD_ITEM* aItem, int aMaxDistance ) const; /**