#include "sch_tool_utils.h"
#include <sch_text.h>
#include <sch_field.h>
#include <sch_pin.h>
#include <sch_reference_list.h>
#include <sch_symbol.h>
#include <sch_table.h>
#include <sch_tablecell.h>
#include <sch_textbox.h>
#include <schematic.h>
#include <sch_sheet_path.h>
#include <sch_sheet.h>
#include <sch_sheet_pin.h>
#include <sch_screen.h>
#include <sch_group.h>
#include <kiid.h>
#include <algorithm>
#include <limits>
#include <wx/arrstr.h>

Functions
wxString	GetSchItemAsText (const SCH_ITEM &aItem)

wxString	GetSelectedItemsAsText (const SELECTION &aSel)

template<typename T>
static std::vector< SCH_ITEM * >	flattenGroups (const T &aItems)

std::vector< SCH_ITEM * >	FlattenGroups (const EDA_ITEMS &aItems)
	Return the given items with the members of any group added, recursively.

std::vector< SCH_ITEM * >	FlattenGroups (const std::deque< EDA_ITEM * > &aItems)

bool	IsUnannotatedUnitOccupied (const SCH_REFERENCE_LIST &aRefs, const wxString &aRef, const LIB_ID &aLibId, int aUnit)
	Decide whether aUnit of an unannotated multi-unit symbol is already placed.

std::set< int >	GetUnplacedUnitsForSymbol (const SCH_SYMBOL &aSym)
	Get a list of unplaced (i.e.

std::optional< SCH_REFERENCE >	FindSymbolByRefAndUnit (const SCHEMATIC &aSchematic, const wxString &aRef, int aUnit)
	Find a symbol by reference and unit.

std::vector< SCH_SYMBOL * >	GetSameSymbolMultiUnitSelection (const SELECTION &aSel)
	Validates and gathers a selection containing multiple symbol units that all belong to the same reference designator and originate from the same library symbol (LIB_ID).

bool	SwapPinGeometry (SCH_PIN aFirst, SCH_PIN aSecond)
	Swap the positions/lengths/etc.

bool	SymbolHasSheetInstances (const SCH_SYMBOL &aSymbol, const wxString &aCurrentProject, std::set< wxString > aSheetPaths, std::set< wxString > aProjectNames)
	Returns true when the given symbol has instances, e.g.

std::set< wxString >	GetSheetNamesFromPaths (const std::set< wxString > &aSheetPaths, const SCHEMATIC &aSchematic)
	Get human-readable sheet names from a set of sheet paths, e.g.

wxString	UniqueSheetName (SCH_SCREEN *aScreen, const wxString &aBaseName)
	Return aBaseName, or aBaseName + smallest free integer if a sheet with that name already exists on aScreen.

std::vector< SCH_HIERLABEL * >	GetUnplacedSheetPinLabels (const SCH_SHEET &aSheet)
	Return one sheet hierarchical label per name that does not already have a sheet pin.

void	AutoPlaceSheetPins (SCH_SHEET aSheet, const std::vector< SCH_HIERLABEL > &aLabels)
	Import and auto-place sheet pins for the given labels, growing the sheet as needed.

wxString	UniqueGroupName (SCH_SCREEN *aScreen, const wxString &aBaseName)
	Return aBaseName, or aBaseName + smallest free integer if a group with that name already exists on aScreen.

void	PrunePastedSymbolInstances (SCH_SYMBOL *aSymbol, const SCHEMATIC &aSchematic)
	Discard the instance data a paste dragged in from somewhere else, keyed by path rather than project name since that field is empty in files written before KiCad 7.

Function Documentation

◆ AutoPlaceSheetPins()

void AutoPlaceSheetPins	(	SCH_SHEET *	aSheet,
		const std::vector< SCH_HIERLABEL * > &	aLabels )

Import and auto-place sheet pins for the given labels, growing the sheet as needed.

Outputs go on the right edge, and all other pins go on the left.

The labels should come from GetUnplacedSheetPinLabels(). Caller must save the sheet for undo before calling this on an existing sheet.

Definition at line 525 of file sch_tool_utils.cpp.

References SCH_SHEET::AddPin(), AUTOPLACE_AUTO, SCH_ITEM::GetParentScreen(), SCH_SHEET::GetPins(), SCH_SHEET::GetPosition(), SCH_SHEET::GetSize(), EDA_TEXT::GetText(), grid, KiROUND(), L_OUTPUT, LEFT, SCHEMATIC_SETTINGS::m_DefaultTextSize, pin, SCH_SHEET::Resize(), RIGHT, SCH_ITEM::Schematic(), schIUScale, SCHEMATIC::Settings(), VECTOR2< T >::x, and VECTOR2< T >::y.

Referenced by SCH_DRAWING_TOOLS::AutoPlaceAllSheetPins(), and SCH_DRAWING_TOOLS::DrawSheet().

◆ FindSymbolByRefAndUnit()

std::optional< SCH_REFERENCE > FindSymbolByRefAndUnit	(	const SCHEMATIC &	aSheet,
		const wxString &	aRef,
		int	aUnit )

Find a symbol by reference and unit.

Returns: A SCH_REFERENCE to the found symbol, or std::nullopt if not found.

Definition at line 243 of file sch_tool_utils.cpp.

References SCH_SHEET_LIST::GetSymbols(), SCHEMATIC::Hierarchy(), and SYMBOL_FILTER_ALL.

Referenced by SCH_EDIT_FRAME::SelectUnit().

◆ FlattenGroups() [1/2]

std::vector< SCH_ITEM * > FlattenGroups ( const EDA_ITEMS & aItems )

Return the given items with the members of any group added, recursively.

Anchor logic needs this. A group has no connection points, and its position is its bounding box centre, which is rarely on grid.

Definition at line 167 of file sch_tool_utils.cpp.

References flattenGroups().

Referenced by SCH_DRAWING_TOOLS::ImportSheet(), and SCH_EDITOR_CONTROL::Paste().

◆ FlattenGroups() [2/2]

std::vector< SCH_ITEM * > FlattenGroups ( const std::deque< EDA_ITEM * > & aItems )

Definition at line 173 of file sch_tool_utils.cpp.

References flattenGroups().

◆ flattenGroups()

template<typename T>

static std::vector< SCH_ITEM * > flattenGroups ( const T & aItems )

static

Definition at line 142 of file sch_tool_utils.cpp.

References SCH_GROUP_T, T, and EDA_ITEM::Type().

Referenced by FlattenGroups(), and FlattenGroups().

◆ GetSameSymbolMultiUnitSelection()

std::vector< SCH_SYMBOL * > GetSameSymbolMultiUnitSelection ( const SELECTION & aSel )

Validates and gathers a selection containing multiple symbol units that all belong to the same reference designator and originate from the same library symbol (LIB_ID).

Used by gate label swap.

Returns: a SELECTION of SCH_SYMBOL* if valid, or an empty vector if not valid.

Definition at line 261 of file sch_tool_utils.cpp.

References SCHEMATIC::CurrentSheet(), SELECTION::GetItemsSortedBySelectionOrder(), SCH_SYMBOL::GetLibId(), SCH_SYMBOL::GetLibSymbolRef(), SCH_SYMBOL::GetPins(), SCH_SYMBOL::GetRef(), SELECTION::GetSize(), LIB_SYMBOL::GetUnitCount(), SELECTION::OnlyContains(), result, and SCH_ITEM::Schematic().

Referenced by SCH_SELECTION_TOOL::Init(), and SCH_EDIT_TOOL::SwapUnitLabels().

◆ GetSchItemAsText()

wxString GetSchItemAsText ( const SCH_ITEM & aItem )

Definition at line 43 of file sch_tool_utils.cpp.

References FOR_CANVAS, SCH_FIELD::GetShownText(), SCH_TABLECELL::GetShownText(), SCH_TEXTBOX::GetShownText(), pin, SCH_DIRECTIVE_LABEL_T, SCH_FIELD_T, SCH_GLOBAL_LABEL_T, SCH_HIER_LABEL_T, SCH_LABEL_T, SCH_PIN_T, SCH_SHEET_PIN_T, SCH_TABLE_T, SCH_TABLECELL_T, SCH_TEXT_T, SCH_TEXTBOX_T, table, text, and EDA_ITEM::Type().

Referenced by GetSelectedItemsAsText().

◆ GetSelectedItemsAsText()

wxString GetSelectedItemsAsText ( const SELECTION & aSel )

Definition at line 119 of file sch_tool_utils.cpp.

References GetSchItemAsText().

Referenced by SCH_EDITOR_CONTROL::CopyAsText(), and SYMBOL_EDITOR_EDIT_TOOL::CopyAsText().

◆ GetSheetNamesFromPaths()

std::set< wxString > GetSheetNamesFromPaths	(	const std::set< wxString > &	aSheetPaths,
		const SCHEMATIC &	aSchematic )

Get human-readable sheet names from a set of sheet paths, e.g.

the SHEETNAME field

Parameters

aSheetPaths	set of sheet paths to convert
aSchematic	the schematic to search for sheet names

Returns: a set of human-readable sheet names, or the original sheet path if no name can be resolved in this schmatic (this happens when sheets are shared across projects)

Definition at line 410 of file sch_tool_utils.cpp.

References FOR_NETNAME, SCH_SHEET::GetField(), SCH_FIELD::GetShownText(), SCHEMATIC::Hierarchy(), name, and SHEET_NAME.

Referenced by BACK_ANNOTATE::applyPinSwaps(), and SCH_EDIT_TOOL::SwapPins().

◆ GetUnplacedSheetPinLabels()

std::vector< SCH_HIERLABEL * > GetUnplacedSheetPinLabels ( const SCH_SHEET & aSheet )

Return one sheet hierarchical label per name that does not already have a sheet pin.

Definition at line 502 of file sch_tool_utils.cpp.

References SCH_SHEET::GetPins(), SCH_SHEET::GetScreen(), EDA_TEXT::GetText(), SCH_SCREEN::Items(), EE_RTREE::OfType(), pin, and SCH_HIER_LABEL_T.

Referenced by SCH_DRAWING_TOOLS::AutoPlaceAllSheetPins(), and SCH_DRAWING_TOOLS::DrawSheet().

◆ GetUnplacedUnitsForSymbol()

std::set< int > GetUnplacedUnitsForSymbol ( const SCH_SYMBOL & aSym )

Get a list of unplaced (i.e.

not in schamtic) unit numbers for a symbol.

Definition at line 202 of file sch_tool_utils.cpp.

References SCHEMATIC::CurrentSheet(), SCH_SYMBOL::GetLibId(), SCH_SYMBOL::GetRef(), SCH_SHEET_LIST::GetSymbols(), SCH_SYMBOL::GetUnitCount(), SCHEMATIC::Hierarchy(), SCH_ITEM::Schematic(), and SYMBOL_FILTER_ALL.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), SCH_DRAWING_TOOLS::PlaceNextSymbolUnit(), and SYMBOL_UNIT_MENU::update().

◆ IsUnannotatedUnitOccupied()

bool IsUnannotatedUnitOccupied	(	const SCH_REFERENCE_LIST &	aRefs,
		const wxString &	aRef,
		const LIB_ID &	aLibId,
		int	aUnit )

Decide whether aUnit of an unannotated multi-unit symbol is already placed.

Pre-annotation references all share the same "U?" form regardless of which library symbol they originate from, so two different multi-unit parts that share a reference prefix would otherwise be collapsed into one logical component. This helper restricts the occupancy check to references whose backing symbol shares aLibId and reference designator aRef.

Parameters

aRefs	Pre-built reference list of every symbol on the sheet.
aRef	Unitless reference designator of the candidate (typically "U?").
aLibId	LIB_ID of the candidate symbol; identifies the underlying library part.
aUnit	Unit number being tested.

Returns: true when an existing same-LIB_ID, same-reference symbol already occupies aUnit.

Definition at line 179 of file sch_tool_utils.cpp.

References SCH_REFERENCE_LIST::GetCount(), SCH_SYMBOL::GetLibId(), SCH_REFERENCE::GetRef(), SCH_REFERENCE::GetSymbol(), and SCH_REFERENCE::GetUnit().

Referenced by BOOST_AUTO_TEST_CASE(), and SCH_DRAWING_TOOLS::PlaceSymbol().

◆ PrunePastedSymbolInstances()

void PrunePastedSymbolInstances	(	SCH_SYMBOL *	aSymbol,
		const SCHEMATIC &	aSchematic )

Discard the instance data a paste dragged in from somewhere else, keyed by path rather than project name since that field is empty in files written before KiCad 7.

Warning: Only call this when cleaning up after a paste; it can clobber symbol instances for schematics shared across projects otherwise.

Parameters

aSymbol	is the pasted symbol whose instances are reconciled.
aSchematic	is the schematic the paste target belongs to.

Definition at line 633 of file sch_tool_utils.cpp.

References SCH_SYMBOL::GetInstances(), PROJECT::GetProjectName(), SCHEMATIC::IsInstancePathInProject(), SCHEMATIC::IsValid(), path, SCHEMATIC::Project(), SCH_SYMBOL::RemoveInstance(), and SCH_SYMBOL::SetInstanceProjectName().

Referenced by BOOST_FIXTURE_TEST_CASE(), BOOST_FIXTURE_TEST_CASE(), BOOST_FIXTURE_TEST_CASE(), BOOST_FIXTURE_TEST_CASE(), and SCH_EDITOR_CONTROL::prunePastedSymbolInstances().

◆ SwapPinGeometry()

bool SwapPinGeometry	(	SCH_PIN *	aFirst,
		SCH_PIN *	aSecond )

Swap the positions/lengths/etc.

between two pins in a symbol in such a way that connectivity is maintained.

The swap operates on the owning library pins when available so that callers may refresh symbol instances afterwards via SCH_SYMBOL::UpdatePins().

Returns: true if the swap touched a shared library pin.

Definition at line 330 of file sch_tool_utils.cpp.

References SCH_PIN::GetLength(), SCH_PIN::GetLibPin(), SCH_PIN::GetLocalPosition(), SCH_PIN::GetOperatingPoint(), SCH_PIN::GetOrientation(), SCH_PIN::SetLength(), SCH_PIN::SetOperatingPoint(), SCH_PIN::SetOrientation(), and SCH_PIN::SetPosition().

Referenced by BACK_ANNOTATE::applyPinSwaps(), and SCH_EDIT_TOOL::SwapPins().

◆ SymbolHasSheetInstances()

bool SymbolHasSheetInstances	(	const SCH_SYMBOL &	aSymbol,
		const wxString &	aCurrentProject,
		std::set< wxString > *	aSheetPaths = nullptr,
		std::set< wxString > *	aProjectNames = nullptr )

Returns true when the given symbol has instances, e.g.

is used by more than one sheet instance in this project or by more than one project.

Parameters

[in]	aSymbol	is the SCH_SYMBOL object to test for shared instances.
[in]	aCurrentProject
[out]	aSheetPaths	if not nullptr, will be filled with the sheet paths that have instances of aSymbol.
[out]	aProjectNames	if not nullptr, will be filled with the names of other projects that have instances of aSymbol.