haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Commenting.

This commit is contained in:
Jeff Young 2022-08-22 11:58:09 +01:00
parent 6fad25f8ed
commit 03454684fa
2 changed files with 105 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
eeschema/tools/ee_selection_tool.h
View File

@ -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<KICAD_T>& 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<KICAD_T>& 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<KICAD_T>& 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;

83
pcbnew/tools/pcb_selection_tool.h
View File

@ -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,7 +301,7 @@ 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<BOARD_CONNECTED_ITEM*>& aStartItems,
STOP_CONDITION aStopCondition );
@ -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;
/**