KiCad PCB EDA Suite
SCH_SHEET_PATH Class Reference

Handle access to a stack of flattened SCH_SHEET objects by way of a path for creating a flattened schematic hierarchy. More...

#include <sch_sheet_path.h>

Public Member Functions

 SCH_SHEET_PATH ()
 
 SCH_SHEET_PATH (const SCH_SHEET_PATH &aOther)
 
SCH_SHEET_PATHoperator= (const SCH_SHEET_PATH &aOther)
 
 ~SCH_SHEET_PATH ()=default
 
SCH_SHEETat (size_t aIndex) const
 Forwarded method from std::vector. More...
 
void clear ()
 Forwarded method from std::vector. More...
 
bool empty () const
 Forwarded method from std::vector. More...
 
void pop_back ()
 Forwarded method from std::vector. More...
 
void push_back (SCH_SHEET *aSheet)
 Forwarded method from std::vector. More...
 
size_t size () const
 Forwarded method from std::vector. More...
 
void Rehash ()
 
size_t GetCurrentHash () const
 
void SetVirtualPageNumber (int aPageNumber)
 Set the sheet instance virtual page number. More...
 
int GetVirtualPageNumber () const
 
void SetPageNumber (const wxString &aPageNumber)
 Set the sheet instance user definable page number. More...
 
wxString GetPageNumber () const
 
const SCH_SHEETGetSheet (unsigned aIndex) const
 
bool IsFullPath () const
 
int Cmp (const SCH_SHEET_PATH &aSheetPathToTest) const
 Compare if this is the same sheet path as aSheetPathToTest. More...
 
int ComparePageNum (const SCH_SHEET_PATH &aSheetPathToTest) const
 Compare sheets by their page number. More...
 
bool IsContainedWithin (const SCH_SHEET_PATH &aSheetPathToTest) const
 Check if this path is contained inside aSheetPathToTest. More...
 
SCH_SHEETLast () const
 Return a pointer to the last SCH_SHEET of the list. More...
 
SCH_SCREENLastScreen ()
 
SCH_SCREENLastScreen () const
 
wxString PathAsString () const
 Return the path of time stamps which do not changes even when editing sheet parameters. More...
 
KIID_PATH Path () const
 Get the sheet path as an KIID_PATH. More...
 
KIID_PATH PathWithoutRootUuid () const
 Get the sheet path as an KIID_PATH without the root sheet UUID prefix. More...
 
wxString PathHumanReadable (bool aUseShortRootName=true) const
 Return the sheet path in a human readable form made from the sheet names. More...
 
void UpdateAllScreenReferences ()
 Update all the symbol references for this sheet path. More...
 
void AppendSymbol (SCH_REFERENCE_LIST &aReferences, SCH_SYMBOL *aSymbol, bool aIncludePowerSymbols=true, bool aForceIncludeOrphanSymbols=false) const
 Append a SCH_REFERENCE object to aReferences based on aSymbol. More...
 
void GetSymbols (SCH_REFERENCE_LIST &aReferences, bool aIncludePowerSymbols=true, bool aForceIncludeOrphanSymbols=false) const
 Adds SCH_REFERENCE object to aReferences for each symbol in the sheet. More...
 
void AppendMultiUnitSymbol (SCH_MULTI_UNIT_REFERENCE_MAP &aRefList, SCH_SYMBOL *aSymbol, bool aIncludePowerSymbols=true) const
 Append a SCH_REFERENCE_LIST object to aRefList based on aSymbol, storing same-reference set of multi-unit parts together. More...
 
void GetMultiUnitSymbols (SCH_MULTI_UNIT_REFERENCE_MAP &aRefList, bool aIncludePowerSymbols=true) const
 Add a SCH_REFERENCE_LIST object to aRefList for each same-reference set of multi-unit parts in the sheet. More...
 
bool TestForRecursion (const wxString &aSrcFileName, const wxString &aDestFileName)
 Test the SCH_SHEET_PATH file names to check adding the sheet stored in the file aSrcFileName to the sheet stored in file aDestFileName will cause a sheet path recursion. More...
 
void MakeFilePathRelativeToParentSheet ()
 Make the sheet file name relative to its parent sheet. More...
 
bool operator== (const SCH_SHEET_PATH &d1) const
 
bool operator!= (const SCH_SHEET_PATH &d1) const
 
bool operator< (const SCH_SHEET_PATH &d1) const
 

Protected Attributes

std::vector< SCH_SHEET * > m_sheets
 
size_t m_current_hash
 
int m_virtualPageNumber
 
std::map< std::pair< wxString, wxString >, bool > m_recursion_test_cache
 Page numbers are maintained by the sheet load order. More...
 

Private Member Functions

void initFromOther (const SCH_SHEET_PATH &aOther)
 

Detailed Description

Handle access to a stack of flattened SCH_SHEET objects by way of a path for creating a flattened schematic hierarchy.

The SCH_SHEET objects are stored in a list from first (usually the root sheet) to a given sheet in last position. The last sheet is usually the sheet we want to select or reach (which is what the function Last() returns). Others sheets constitute the "path" from the first to the last sheet.

Definition at line 128 of file sch_sheet_path.h.

Constructor & Destructor Documentation

◆ SCH_SHEET_PATH() [1/2]

SCH_SHEET_PATH::SCH_SHEET_PATH ( )

Definition at line 98 of file sch_sheet_path.cpp.

99 {
101  m_current_hash = 0;
102 }

References m_current_hash, and m_virtualPageNumber.

◆ SCH_SHEET_PATH() [2/2]

SCH_SHEET_PATH::SCH_SHEET_PATH ( const SCH_SHEET_PATH aOther)

Definition at line 105 of file sch_sheet_path.cpp.

106 {
107  initFromOther( aOther );
108 }
void initFromOther(const SCH_SHEET_PATH &aOther)

References initFromOther().

◆ ~SCH_SHEET_PATH()

SCH_SHEET_PATH::~SCH_SHEET_PATH ( )
default

Member Function Documentation

◆ AppendMultiUnitSymbol()

void SCH_SHEET_PATH::AppendMultiUnitSymbol ( SCH_MULTI_UNIT_REFERENCE_MAP aRefList,
SCH_SYMBOL aSymbol,
bool  aIncludePowerSymbols = true 
) const

Append a SCH_REFERENCE_LIST object to aRefList based on aSymbol, storing same-reference set of multi-unit parts together.

The map key for each element will be the reference designator.

Parameters
aRefListMap of reference designators to reference lists
aSymbolA symbol to add to aRefList
aIncludePowerSymbolsSet to false to only get normal symbols.

Definition at line 350 of file sch_sheet_path.cpp.

353 {
354  // Skip pseudo-symbols, which have a reference starting with #. This mainly
355  // affects power symbols.
356  if( !aIncludePowerSymbols && aSymbol->GetRef( this )[0] == wxT( '#' ) )
357  return;
358 
359  LIB_SYMBOL* symbol = aSymbol->GetLibSymbolRef().get();
360 
361  if( symbol && symbol->GetUnitCount() > 1 )
362  {
363  SCH_REFERENCE schReference = SCH_REFERENCE( aSymbol, symbol, *this );
364  schReference.SetSheetNumber( m_virtualPageNumber );
365  wxString reference_str = schReference.GetRef();
366 
367  // Never lock unassigned references
368  if( reference_str[reference_str.Len() - 1] == '?' )
369  return;
370 
371  aRefList[reference_str].AddItem( schReference );
372  }
373 }
void SetSheetNumber(int aSheetNumber)
const wxString GetRef(const SCH_SHEET_PATH *aSheet, bool aIncludeUnit=false) const
Return the reference for the given sheet path.
Definition: sch_symbol.cpp:443
Define a library symbol object.
Definition: lib_symbol.h:96
std::unique_ptr< LIB_SYMBOL > & GetLibSymbolRef()
Definition: sch_symbol.h:164
wxString GetRef() const
int GetUnitCount() const override
For items with units, return the number of units.
A helper to define a symbol's reference designator in a schematic.

References SCH_SYMBOL::GetLibSymbolRef(), SCH_REFERENCE::GetRef(), SCH_SYMBOL::GetRef(), LIB_SYMBOL::GetUnitCount(), m_virtualPageNumber, and SCH_REFERENCE::SetSheetNumber().

Referenced by EE_SELECTION::GetMultiUnitSymbols(), and GetMultiUnitSymbols().

◆ AppendSymbol()

void SCH_SHEET_PATH::AppendSymbol ( SCH_REFERENCE_LIST aReferences,
SCH_SYMBOL aSymbol,
bool  aIncludePowerSymbols = true,
bool  aForceIncludeOrphanSymbols = false 
) const

Append a SCH_REFERENCE object to aReferences based on aSymbol.

Parameters
aReferencesList of references to populate.
aSymbolA symbol to add to aReferences
aIncludePowerSymbolsset to false to only get normal symbols.
aForceIncludeOrphanSymbolsset to true to include symbols having no symbol found in lib. The normal option is false, and set to true only to build the full list of symbols.

Definition at line 318 of file sch_sheet_path.cpp.

321 {
322  // Skip pseudo-symbols, which have a reference starting with #. This mainly
323  // affects power symbols.
324  if( aIncludePowerSymbols || aSymbol->GetRef( this )[0] != wxT( '#' ) )
325  {
326  LIB_SYMBOL* symbol = aSymbol->GetLibSymbolRef().get();
327 
328  if( symbol || aForceIncludeOrphanSymbols )
329  {
330  SCH_REFERENCE schReference( aSymbol, symbol, *this );
331 
332  schReference.SetSheetNumber( m_virtualPageNumber );
333  aReferences.AddItem( schReference );
334  }
335  }
336 }
void AddItem(const SCH_REFERENCE &aItem)
const wxString GetRef(const SCH_SHEET_PATH *aSheet, bool aIncludeUnit=false) const
Return the reference for the given sheet path.
Definition: sch_symbol.cpp:443
Define a library symbol object.
Definition: lib_symbol.h:96
std::unique_ptr< LIB_SYMBOL > & GetLibSymbolRef()
Definition: sch_symbol.h:164
A helper to define a symbol's reference designator in a schematic.

References SCH_REFERENCE_LIST::AddItem(), SCH_SYMBOL::GetLibSymbolRef(), SCH_SYMBOL::GetRef(), m_virtualPageNumber, and SCH_REFERENCE::SetSheetNumber().

Referenced by SCH_SEXPR_PLUGIN::Format(), EE_SELECTION::GetSymbols(), and GetSymbols().

◆ at()

SCH_SHEET* SCH_SHEET_PATH::at ( size_t  aIndex) const
inline

Forwarded method from std::vector.

Definition at line 140 of file sch_sheet_path.h.

140 { return m_sheets.at( aIndex ); }
std::vector< SCH_SHEET * > m_sheets

References m_sheets.

Referenced by Cmp(), GetSheet(), SCH_EDIT_FRAME::GetUniqueFilenameForCurrentSheet(), IsContainedWithin(), PathAsString(), PathHumanReadable(), PathWithoutRootUuid(), and TestForRecursion().

◆ clear()

void SCH_SHEET_PATH::clear ( )
inline

Forwarded method from std::vector.

Definition at line 143 of file sch_sheet_path.h.

144  {
145  m_sheets.clear();
146  Rehash();
147  }
std::vector< SCH_SHEET * > m_sheets

References m_sheets, and Rehash().

Referenced by SCH_EDIT_FRAME::doCloseWindow(), TEST_SCH_SHEET_LIST_FIXTURE::loadSchematic(), SCHEMATIC::Reset(), SCHEMATIC::SetRoot(), and HIERARCHY_NAVIG_DLG::UpdateHierarchyTree().

◆ Cmp()

int SCH_SHEET_PATH::Cmp ( const SCH_SHEET_PATH aSheetPathToTest) const

Compare if this is the same sheet path as aSheetPathToTest.

Parameters
aSheetPathToTestis the sheet path to compare.
Returns
1 if this sheet path has more sheets than aSheetPathToTest, -1 if this sheet path has fewer sheets than aSheetPathToTest, or 0 if same

Definition at line 144 of file sch_sheet_path.cpp.

145 {
146  if( size() > aSheetPathToTest.size() )
147  return 1;
148 
149  if( size() < aSheetPathToTest.size() )
150  return -1;
151 
152  //otherwise, same number of sheets.
153  for( unsigned i = 0; i < size(); i++ )
154  {
155  if( at( i )->m_Uuid < aSheetPathToTest.at( i )->m_Uuid )
156  return -1;
157 
158  if( at( i )->m_Uuid != aSheetPathToTest.at( i )->m_Uuid )
159  return 1;
160  }
161 
162  return 0;
163 }
size_t size() const
Forwarded method from std::vector.
const KIID m_Uuid
Definition: eda_item.h:474
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References at(), EDA_ITEM::m_Uuid, and size().

Referenced by SCH_REFERENCE_LIST::sortByTimeStamp().

◆ ComparePageNum()

int SCH_SHEET_PATH::ComparePageNum ( const SCH_SHEET_PATH aSheetPathToTest) const

Compare sheets by their page number.

If the actual page number is equal, use virtual page numbers to compare.

Returns
-1 if aSheetPathToTest is greater than this (should appear later in the sort order) 0 if aSheetPathToTest is equal to this 1 if aSheetPathToTest is less than this (should appear earlier in the sort order)

Definition at line 166 of file sch_sheet_path.cpp.

167 {
168  wxString pageA = GetPageNumber();
169  wxString pageB = aSheetPathToTest.GetPageNumber();
170 
171  int pageNumComp = SCH_SHEET::ComparePageNum( pageA, pageB );
172 
173  if( pageNumComp == 0 )
174  {
175  int virtualPageA = GetVirtualPageNumber();
176  int virtualPageB = aSheetPathToTest.GetVirtualPageNumber();
177 
178  return virtualPageA > virtualPageB ? 1 : -1;
179  }
180  else
181  {
182  return pageNumComp;
183  }
184 }
static int ComparePageNum(const wxString &aPageNumberA, const wxString &aPageNumberB)
Compares page numbers of schematic sheets.
Definition: sch_sheet.cpp:1200
int GetVirtualPageNumber() const
wxString GetPageNumber() const

References SCH_SHEET::ComparePageNum(), GetPageNumber(), and GetVirtualPageNumber().

Referenced by SCH_EDITOR_CONTROL::FindNext(), HIERARCHY_TREE::OnCompareItems(), and SCH_SHEET_LIST::SortByPageNumbers().

◆ empty()

bool SCH_SHEET_PATH::empty ( ) const
inline

Forwarded method from std::vector.

Definition at line 150 of file sch_sheet_path.h.

150 { return m_sheets.empty(); }
std::vector< SCH_SHEET * > m_sheets

References m_sheets.

Referenced by Last(), and PathHumanReadable().

◆ GetCurrentHash()

size_t SCH_SHEET_PATH::GetCurrentHash ( ) const
inline

Definition at line 171 of file sch_sheet_path.h.

171 { return m_current_hash; }

References m_current_hash.

Referenced by SCH_EDITOR_CONTROL::FindNext(), and operator==().

◆ GetMultiUnitSymbols()

void SCH_SHEET_PATH::GetMultiUnitSymbols ( SCH_MULTI_UNIT_REFERENCE_MAP aRefList,
bool  aIncludePowerSymbols = true 
) const

Add a SCH_REFERENCE_LIST object to aRefList for each same-reference set of multi-unit parts in the sheet.

The map key for each element will be the reference designator.

Parameters
aRefListMap of reference designators to reference lists
aIncludePowerSymbolsSet to false to only get normal symbols.

Definition at line 339 of file sch_sheet_path.cpp.

341 {
342  for( SCH_ITEM* item : LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
343  {
344  SCH_SYMBOL* symbol = static_cast<SCH_SYMBOL*>( item );
345  AppendMultiUnitSymbol( aRefList, symbol, aIncludePowerSymbols );
346  }
347 }
void AppendMultiUnitSymbol(SCH_MULTI_UNIT_REFERENCE_MAP &aRefList, SCH_SYMBOL *aSymbol, bool aIncludePowerSymbols=true) const
Append a SCH_REFERENCE_LIST object to aRefList based on aSymbol, storing same-reference set of multi-...
Schematic symbol object.
Definition: sch_symbol.h:78
SCH_SCREEN * LastScreen()
Base class for any item which can be embedded within the SCHEMATIC container class,...
Definition: sch_item.h:182

References AppendMultiUnitSymbol(), LastScreen(), and SCH_SYMBOL_T.

Referenced by SCH_EDIT_FRAME::AnnotateSymbols().

◆ GetPageNumber()

wxString SCH_SHEET_PATH::GetPageNumber ( ) const

Definition at line 463 of file sch_sheet_path.cpp.

464 {
465  SCH_SHEET* sheet = Last();
466 
467  wxCHECK( sheet, wxEmptyString );
468 
469  return sheet->GetPageNumber( *this );
470 }
SCH_SHEET * Last() const
Return a pointer to the last SCH_SHEET of the list.
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54
wxString GetPageNumber(const SCH_SHEET_PATH &aInstance) const
Return the sheet page number for aInstance.
Definition: sch_sheet.cpp:1163

References SCH_SHEET::GetPageNumber(), and Last().

Referenced by ComparePageNum(), SCH_FIELD::DoHypertextMenu(), SCH_EDIT_TOOL::EditPageNumber(), SCH_EDITOR_CONTROL::FindNext(), SCH_NAVIGATE_TOOL::HypertextCommand(), SCH_SHEET_LIST::PageNumberExists(), SCHEMATIC::ResolveTextVar(), and SCH_GLOBALLABEL::ResolveTextVar().

◆ GetSheet()

const SCH_SHEET* SCH_SHEET_PATH::GetSheet ( unsigned  aIndex) const
inline

Definition at line 195 of file sch_sheet_path.h.

196  {
197  SCH_SHEET* retv = nullptr;
198 
199  if( aIndex < size() )
200  retv = at( aIndex );
201 
202  return retv;
203  }
size_t size() const
Forwarded method from std::vector.
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References at(), and size().

Referenced by IsFullPath(), and SCH_SHEET_LIST::TestForRecursion().

◆ GetSymbols()

void SCH_SHEET_PATH::GetSymbols ( SCH_REFERENCE_LIST aReferences,
bool  aIncludePowerSymbols = true,
bool  aForceIncludeOrphanSymbols = false 
) const

Adds SCH_REFERENCE object to aReferences for each symbol in the sheet.

Parameters
aReferencesList of references to populate.
aIncludePowerSymbolsset to false to only get normal symbols.
aForceIncludeOrphanSymbolsset to true to include symbols having no symbol found in lib. The normal option is false, and set to true only to build the full list of symbols.

Definition at line 307 of file sch_sheet_path.cpp.

309 {
310  for( SCH_ITEM* item : LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
311  {
312  SCH_SYMBOL* symbol = static_cast<SCH_SYMBOL*>( item );
313  AppendSymbol( aReferences, symbol, aIncludePowerSymbols, aForceIncludeOrphanSymbols );
314  }
315 }
void AppendSymbol(SCH_REFERENCE_LIST &aReferences, SCH_SYMBOL *aSymbol, bool aIncludePowerSymbols=true, bool aForceIncludeOrphanSymbols=false) const
Append a SCH_REFERENCE object to aReferences based on aSymbol.
Schematic symbol object.
Definition: sch_symbol.h:78
SCH_SCREEN * LastScreen()
Base class for any item which can be embedded within the SCHEMATIC container class,...
Definition: sch_item.h:182

References AppendSymbol(), LastScreen(), and SCH_SYMBOL_T.

Referenced by SCH_EDIT_FRAME::AnnotateSymbols(), SCH_EDIT_FRAME::CheckAnnotate(), CollectOtherUnits(), SCH_SHEET_LIST::GetSymbols(), SCH_SHEET_LIST::GetSymbolsWithinPath(), SCH_EDITOR_CONTROL::Paste(), and SCH_EDITOR_CONTROL::updatePastedSheet().

◆ GetVirtualPageNumber()

int SCH_SHEET_PATH::GetVirtualPageNumber ( ) const
inline

Definition at line 184 of file sch_sheet_path.h.

184 { return m_virtualPageNumber; }

References m_virtualPageNumber.

Referenced by ComparePageNum().

◆ initFromOther()

void SCH_SHEET_PATH::initFromOther ( const SCH_SHEET_PATH aOther)
private

Definition at line 118 of file sch_sheet_path.cpp.

119 {
120  m_sheets = aOther.m_sheets;
123 
124  // Note: don't copy m_recursion_test_cache as it is slow and we want SCH_SHEET_PATHS to be
125  // very fast to construct for use in the connectivity algorithm.
126 }
std::vector< SCH_SHEET * > m_sheets

References m_current_hash, m_sheets, and m_virtualPageNumber.

Referenced by operator=(), and SCH_SHEET_PATH().

◆ IsContainedWithin()

bool SCH_SHEET_PATH::IsContainedWithin ( const SCH_SHEET_PATH aSheetPathToTest) const

Check if this path is contained inside aSheetPathToTest.

Parameters
aSheetPathToTestis the sheet path to compare against.
Returns
true if this path is contained inside or equal to aSheetPathToTest.

Definition at line 187 of file sch_sheet_path.cpp.

188 {
189  if( aSheetPathToTest.size() > size() )
190  return false;
191 
192  for( size_t i = 0; i < aSheetPathToTest.size(); ++i )
193  {
194  if( at( i )->m_Uuid != aSheetPathToTest.at( i )->m_Uuid )
195  return false;
196  }
197 
198  return true;
199 }
size_t size() const
Forwarded method from std::vector.
const KIID m_Uuid
Definition: eda_item.h:474
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References at(), EDA_ITEM::m_Uuid, and size().

Referenced by SCH_SHEET_LIST::GetSheetsWithinPath(), and SCH_SHEET_LIST::GetSymbolsWithinPath().

◆ IsFullPath()

bool SCH_SHEET_PATH::IsFullPath ( ) const

Definition at line 129 of file sch_sheet_path.cpp.

130 {
131  return GetSheet( 0 ) && GetSheet( 0 )->IsRootSheet();
132 }
bool IsRootSheet() const
Definition: sch_sheet.cpp:204
const SCH_SHEET * GetSheet(unsigned aIndex) const

References GetSheet(), and SCH_SHEET::IsRootSheet().

Referenced by SCH_SHEET::AddInstance(), SCH_SHEET::GetPageNumber(), and SCH_SHEET::SetPageNumber().

◆ Last()

◆ LastScreen() [1/2]

SCH_SCREEN * SCH_SHEET_PATH::LastScreen ( )

Returns
the SCH_SCREEN relative to the last sheet in list.
the SCH_SCREEN relative to the last sheet in list.

Definition at line 211 of file sch_sheet_path.cpp.

212 {
213  SCH_SHEET* lastSheet = Last();
214 
215  if( lastSheet )
216  return lastSheet->GetScreen();
217 
218  return nullptr;
219 }
SCH_SHEET * Last() const
Return a pointer to the last SCH_SHEET of the list.
SCH_SCREEN * GetScreen() const
Definition: sch_sheet.h:105
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54

References SCH_SHEET::GetScreen(), and Last().

Referenced by SCH_SHEET_LIST::AnnotatePowerSymbols(), SCH_EDIT_FRAME::AnnotateSymbols(), BACK_ANNOTATE::applyChangelist(), HIERARCHY_NAVIG_DLG::buildHierarchyTree(), SCH_SHEET_LIST::BuildSheetList(), SCH_EDIT_FRAME::CheckSheetForRecursion(), SCH_SHEET_LIST::ClearModifyStatus(), DIALOG_PLOT_SCHEMATIC::createDXFFiles(), DIALOG_PLOT_SCHEMATIC::createHPGLFiles(), DIALOG_PLOT_SCHEMATIC::createPDFFile(), DIALOG_PLOT_SCHEMATIC::createPSFiles(), DIALOG_PLOT_SCHEMATIC::createSVGFiles(), SCH_EDIT_FRAME::DisplayCurrentSheet(), SCH_DRAWING_TOOLS::DrawSheet(), SCH_EDIT_TOOL::EditPageNumber(), CONNECTION_GRAPH::ercCheckBusToBusConflicts(), CONNECTION_GRAPH::ercCheckBusToBusEntryConflicts(), CONNECTION_GRAPH::ercCheckBusToNetConflicts(), CONNECTION_GRAPH::ercCheckFloatingWires(), CONNECTION_GRAPH::ercCheckLabels(), CONNECTION_GRAPH::ercCheckMultipleDrivers(), CONNECTION_GRAPH::ercCheckNoConnects(), SCH_SHEET_LIST::FillItemMap(), SCH_SHEET_LIST::FindAllSheetsForScreen(), NETLIST_EXPORTER_BASE::findNextSymbol(), SCH_SHEET_LIST::FindSheetForScreen(), SCH_EDIT_FRAME::FixupJunctions(), SCH_SHEET_LIST::GetItem(), GetMultiUnitSymbols(), SCH_EDIT_FRAME::GetScreen(), GetSymbols(), DIALOG_EDIT_SYMBOLS_LIBID::initDlg(), SCH_SHEET_LIST::IsModified(), MakeFilePathRelativeToParentSheet(), NETLIST_EXPORTER_XML::makeSymbols(), SCH_PRINTOUT::OnPrintPage(), DIALOG_ERC::OnRunERCClick(), DIALOG_SHEET_PROPERTIES::onSheetFilenameChanged(), SCH_EDITOR_CONTROL::Paste(), DIALOG_GLOBAL_EDIT_TEXT_AND_GRAPHICS::processItem(), NETLIST_EXPORTER_PSPICE::ProcessNetlist(), BACK_ANNOTATE::processNetNameChange(), DIALOG_CHANGE_SYMBOLS::processSymbol(), RESCUER::RESCUER(), SCH_EDIT_FRAME::ResolveERCExclusions(), SCHEMATIC::ResolveTextVar(), SCH_EDIT_FRAME::SaveSymbolToSchematic(), SCH_EDIT_FRAME::SetCurrentSheet(), TestForRecursion(), ERC_TESTER::TestMultiunitFootprints(), ERC_TESTER::TestMultUnitPinConflicts(), ERC_TESTER::TestPinToPin(), ERC_TESTER::TestSimilarLabels(), DIALOG_SHEET_PROPERTIES::TransferDataFromWindow(), UpdateAllScreenReferences(), CONNECTION_GRAPH::updateItemConnectivity(), SCH_EDITOR_CONTROL::UpdateNetHighlighting(), and NETLIST_EXPORTER_ORCADPCB2::WriteNetlist().

◆ LastScreen() [2/2]

SCH_SCREEN * SCH_SHEET_PATH::LastScreen ( ) const

Definition at line 222 of file sch_sheet_path.cpp.

223 {
224  SCH_SHEET* lastSheet = Last();
225 
226  if( lastSheet )
227  return lastSheet->GetScreen();
228 
229  return nullptr;
230 }
SCH_SHEET * Last() const
Return a pointer to the last SCH_SHEET of the list.
SCH_SCREEN * GetScreen() const
Definition: sch_sheet.h:105
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54

References SCH_SHEET::GetScreen(), and Last().

◆ MakeFilePathRelativeToParentSheet()

void SCH_SHEET_PATH::MakeFilePathRelativeToParentSheet ( )

Make the sheet file name relative to its parent sheet.

This should only be called when changing the parent sheet path such performing a save as or a new schematic without a project in stand alone mode. The sheet file name is only made relative if the current file name is relative. Absolute sheet file name paths are a user choice so do not change them.

Sheet file name paths are set according to the following criteria:

  • If the sheet file name path is in the same as the parent sheet file name path, set the sheet file name to just the file name and extension with no path.
  • If the sheet file name path can be made relative to the parent sheet file name path, set the sheet file name using the relative path.
  • If the sheet file name path cannot be converted to a relative path, then fall back to the absolute file name path.

Definition at line 483 of file sch_sheet_path.cpp.

484 {
485  wxCHECK( m_sheets.size() > 1, /* void */ );
486 
487  wxFileName sheetFileName = Last()->GetFileName();
488 
489  // If the sheet file name is absolute, then the user requested is so don't make it relative.
490  if( sheetFileName.IsAbsolute() )
491  return;
492 
493  SCH_SCREEN* screen = LastScreen();
494  SCH_SCREEN* parentScreen = m_sheets[ m_sheets.size() - 2 ]->GetScreen();
495 
496  wxCHECK( screen && parentScreen, /* void */ );
497 
498  wxFileName fileName = screen->GetFileName();
499  wxFileName parentFileName = parentScreen->GetFileName();
500 
501  // SCH_SCREEN file names must be absolute. If they are not, someone set them incorrectly
502  // on load or on creation.
503  wxCHECK( fileName.IsAbsolute() && parentFileName.IsAbsolute(), /* void */ );
504 
505  if( fileName.GetPath() == parentFileName.GetPath() )
506  {
507  Last()->SetFileName( fileName.GetFullName() );
508  }
509  else if( fileName.MakeRelativeTo( parentFileName.GetPath() ) )
510  {
511  Last()->SetFileName( fileName.GetFullPath() );
512  }
513  else
514  {
515  Last()->SetFileName( screen->GetFileName() );
516  }
517 
518  wxLogTrace( tracePathsAndFiles,
519  wxT( "\n File name: '%s'"
520  "\n parent file name '%s',"
521  "\n sheet '%s' file name '%s'." ),
522  screen->GetFileName(), parentScreen->GetFileName(), PathHumanReadable(),
523  Last()->GetFileName() );
524 }
const wxString & GetFileName() const
Definition: sch_screen.h:145
SCH_SHEET * Last() const
Return a pointer to the last SCH_SHEET of the list.
void SetFileName(const wxString &aFilename)
Definition: sch_sheet.h:323
wxString PathHumanReadable(bool aUseShortRootName=true) const
Return the sheet path in a human readable form made from the sheet names.
const wxChar *const tracePathsAndFiles
Flag to enable path and file name debug output.
std::vector< SCH_SHEET * > m_sheets
wxString GetFileName() const
Return the filename corresponding to this sheet.
Definition: sch_sheet.h:317
SCH_SCREEN * LastScreen()

References SCH_SCREEN::GetFileName(), SCH_SHEET::GetFileName(), Last(), LastScreen(), m_sheets, PathHumanReadable(), SCH_SHEET::SetFileName(), and tracePathsAndFiles.

◆ operator!=()

bool SCH_SHEET_PATH::operator!= ( const SCH_SHEET_PATH d1) const
inline

Definition at line 370 of file sch_sheet_path.h.

370 { return !( *this == d1 ) ; }

◆ operator<()

bool SCH_SHEET_PATH::operator< ( const SCH_SHEET_PATH d1) const
inline

Definition at line 372 of file sch_sheet_path.h.

372 { return m_sheets < d1.m_sheets; }
std::vector< SCH_SHEET * > m_sheets

References m_sheets.

◆ operator=()

SCH_SHEET_PATH & SCH_SHEET_PATH::operator= ( const SCH_SHEET_PATH aOther)

Definition at line 111 of file sch_sheet_path.cpp.

112 {
113  initFromOther( aOther );
114  return *this;
115 }
void initFromOther(const SCH_SHEET_PATH &aOther)

References initFromOther().

◆ operator==()

bool SCH_SHEET_PATH::operator== ( const SCH_SHEET_PATH d1) const

Definition at line 376 of file sch_sheet_path.cpp.

377 {
378  return m_current_hash == d1.GetCurrentHash();
379 }
size_t GetCurrentHash() const

References GetCurrentHash(), and m_current_hash.

◆ Path()

KIID_PATH SCH_SHEET_PATH::Path ( ) const

Get the sheet path as an KIID_PATH.

Note
This KIID_PATH includes the root sheet UUID prefixed to the path.

Definition at line 248 of file sch_sheet_path.cpp.

249 {
250  KIID_PATH path;
251 
252  for( const SCH_SHEET* sheet : m_sheets )
253  path.push_back( sheet->m_Uuid );
254 
255  return path;
256 }
std::vector< SCH_SHEET * > m_sheets
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54

References m_sheets, and path.

Referenced by SCH_EDIT_FRAME::AnnotateSymbols(), SCH_SYMBOL::ClearAnnotation(), SCH_SYMBOL::GetFootprint(), SCH_SHEET_LIST::GetPaths(), SCH_SYMBOL::GetRef(), SCH_SYMBOL::GetUnitSelection(), SCH_SYMBOL::GetValue(), SCH_SYMBOL::IsAnnotated(), SCH_REFERENCE::IsSameInstance(), SCH_EAGLE_PLUGIN::loadSchematic(), SCH_EDIT_FRAME::mapExistingAnnotation(), SCH_SYMBOL::SetFootprint(), SCH_SYMBOL::SetRef(), SCH_EDIT_FRAME::SetSheetNumberAndCount(), SCH_SYMBOL::SetUnitSelection(), and SCH_SYMBOL::SetValue().

◆ PathAsString()

wxString SCH_SHEET_PATH::PathAsString ( ) const

Return the path of time stamps which do not changes even when editing sheet parameters.

A path is something like / (root) or /34005677 or /34005677/00AE4523.

Definition at line 233 of file sch_sheet_path.cpp.

234 {
235  wxString s;
236 
237  s = wxT( "/" ); // This is the root path
238 
239  // Start at 1 to avoid the root sheet, which does not need to be added to the path.
240  // Its timestamp changes anyway.
241  for( unsigned i = 1; i < size(); i++ )
242  s += at( i )->m_Uuid.AsString() + "/";
243 
244  return s;
245 }
wxString AsString() const
Definition: kiid.cpp:230
size_t size() const
Forwarded method from std::vector.
const KIID m_Uuid
Definition: eda_item.h:474
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References KIID::AsString(), at(), EDA_ITEM::m_Uuid, and size().

Referenced by SCH_REFERENCE::GetPath(), SCH_EAGLE_PLUGIN::loadInstance(), NETLIST_EXPORTER_XML::makeSymbols(), and NETLIST_EXPORTER_ORCADPCB2::WriteNetlist().

◆ PathHumanReadable()

wxString SCH_SHEET_PATH::PathHumanReadable ( bool  aUseShortRootName = true) const

Return the sheet path in a human readable form made from the sheet names.

The "normal" path instead uses the KIID objects in the path that do not change even when editing sheet parameters.

Definition at line 270 of file sch_sheet_path.cpp.

271 {
272  wxString s;
273  wxString fileName;
274 
275  if( !empty() && at( 0 )->GetScreen() )
276  fileName = at( 0 )->GetScreen()->GetFileName();
277 
278  wxFileName fn = fileName;
279 
280  if( aUseShortRootName )
281  s = wxT( "/" ); // Use only the short name in netlists
282  else
283  s = fn.GetName() + wxT( "/" );
284 
285  // Start at 1 since we've already processed the root sheet.
286  for( unsigned i = 1; i < size(); i++ )
287  s = s + at( i )->GetFields()[ SHEETNAME ].GetShownText() + wxT( "/" );
288 
289  return s;
290 }
const wxString & GetFileName() const
Definition: sch_screen.h:145
SCH_SCREEN * GetScreen() const
Definition: sch_sheet.h:105
std::vector< SCH_FIELD > & GetFields()
Definition: sch_sheet.h:90
size_t size() const
Forwarded method from std::vector.
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.
bool empty() const
Forwarded method from std::vector.

References at(), empty(), SCH_SHEET::GetFields(), SCH_SCREEN::GetFileName(), SCH_SHEET::GetScreen(), SHEETNAME, and size().

Referenced by SCH_EDIT_TOOL::EditPageNumber(), SCH_EDIT_FRAME::GetScreenDesc(), inheritNetclass(), MakeFilePathRelativeToParentSheet(), NETLIST_EXPORTER_XML::makeSymbols(), DIALOG_SHEET_PROPERTIES::OnUpdateUI(), SCH_CONNECTION::recacheName(), and SCHEMATIC::ResolveTextVar().

◆ PathWithoutRootUuid()

KIID_PATH SCH_SHEET_PATH::PathWithoutRootUuid ( ) const

Get the sheet path as an KIID_PATH without the root sheet UUID prefix.

Note
This KIID_PATH does not include the root sheet UUID prefixed to the path.

Definition at line 259 of file sch_sheet_path.cpp.

260 {
261  KIID_PATH path;
262 
263  for( size_t i = 1; i < size(); i++ )
264  path.push_back( at( i )->m_Uuid );
265 
266  return path;
267 }
size_t size() const
Forwarded method from std::vector.
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References at(), path, and size().

Referenced by SCH_SHEET::AddInstance(), SCH_SEXPR_PLUGIN::Format(), SCH_SHEET::GetPageNumber(), and SCH_SHEET::SetPageNumber().

◆ pop_back()

void SCH_SHEET_PATH::pop_back ( )
inline

Forwarded method from std::vector.

Definition at line 153 of file sch_sheet_path.h.

154  {
155  m_sheets.pop_back();
156  Rehash();
157  }
std::vector< SCH_SHEET * > m_sheets

References m_sheets, and Rehash().

Referenced by HIERARCHY_NAVIG_DLG::buildHierarchyTree(), SCH_SHEET_LIST::BuildSheetList(), SCH_EDIT_TOOL::EditPageNumber(), SCH_NAVIGATE_TOOL::LeaveSheet(), SCH_EDITOR_CONTROL::LeaveSheet(), and SCH_SHEET::LocatePathOfScreen().

◆ push_back()

◆ Rehash()

void SCH_SHEET_PATH::Rehash ( )

Definition at line 135 of file sch_sheet_path.cpp.

136 {
137  m_current_hash = 0;
138 
139  for( auto sheet : m_sheets )
140  boost::hash_combine( m_current_hash, sheet->m_Uuid.Hash() );
141 }
static void hash_combine(std::size_t &seed)
This is a dummy function to take the final case of hash_combine below.
Definition: hash_eda.h:67
std::vector< SCH_SHEET * > m_sheets

References hash_combine(), m_current_hash, and m_sheets.

Referenced by clear(), pop_back(), and push_back().

◆ SetPageNumber()

void SCH_SHEET_PATH::SetPageNumber ( const wxString &  aPageNumber)

Set the sheet instance user definable page number.

Note
User definable page numbers can be any string devoid of white space characters.

Definition at line 473 of file sch_sheet_path.cpp.

474 {
475  SCH_SHEET* sheet = Last();
476 
477  wxCHECK( sheet, /* void */ );
478 
479  sheet->SetPageNumber( *this, aPageNumber );
480 }
SCH_SHEET * Last() const
Return a pointer to the last SCH_SHEET of the list.
void SetPageNumber(const SCH_SHEET_PATH &aInstance, const wxString &aPageNumber)
Set the page number for the sheet instance aInstance.
Definition: sch_sheet.cpp:1183
Sheet symbol placed in a schematic, and is the entry point for a sub schematic.
Definition: sch_sheet.h:54

References Last(), and SCH_SHEET::SetPageNumber().

Referenced by SCH_EDIT_TOOL::EditPageNumber().

◆ SetVirtualPageNumber()

void SCH_SHEET_PATH::SetVirtualPageNumber ( int  aPageNumber)
inline

Set the sheet instance virtual page number.

Virtual page numbers are incremental integers set automatically when the sheet path hierarchy is created (

See also
SCH_SHEET_LIST::BuildSheetList). The virtual page numbering is ordered by the X and Y position of the sheet in a schematic which mimics the page numbering code prior to the addition of actual user definable page numbers. Virtual page numbers should only be use when annotating schematics.

Definition at line 182 of file sch_sheet_path.h.

182 { m_virtualPageNumber = aPageNumber; }

References m_virtualPageNumber.

Referenced by SCH_SHEET_LIST::BuildSheetList(), SCH_EDIT_FRAME::SetSheetNumberAndCount(), and SCH_SHEET_LIST::SortByPageNumbers().

◆ size()

size_t SCH_SHEET_PATH::size ( ) const
inline

◆ TestForRecursion()

bool SCH_SHEET_PATH::TestForRecursion ( const wxString &  aSrcFileName,
const wxString &  aDestFileName 
)

Test the SCH_SHEET_PATH file names to check adding the sheet stored in the file aSrcFileName to the sheet stored in file aDestFileName will cause a sheet path recursion.

Parameters
aSrcFileNameis the source file name of the sheet add to aDestFileName.
aDestFileNameis the file name of the destination sheet for aSrcFileName.
Returns
true if aFileName will cause recursion in the sheet path. Otherwise false.
Todo:
Store sheet file names with full path, either relative to project path or absolute path. The current design always assumes subsheet files are located in the project folder which may or may not be desirable.

Definition at line 382 of file sch_sheet_path.cpp.

383 {
384  auto pair = std::make_pair( aSrcFileName, aDestFileName );
385 
386  if( m_recursion_test_cache.count( pair ) )
387  return m_recursion_test_cache.at( pair );
388 
389  SCHEMATIC* sch = LastScreen()->Schematic();
390 
391  wxCHECK_MSG( sch, false, "No SCHEMATIC found in SCH_SHEET_PATH::TestForRecursion!" );
392 
393  wxFileName rootFn = sch->GetFileName();
394  wxFileName srcFn = aSrcFileName;
395  wxFileName destFn = aDestFileName;
396 
397  if( srcFn.IsRelative() )
398  srcFn.MakeAbsolute( rootFn.GetPath() );
399 
400  if( destFn.IsRelative() )
401  destFn.MakeAbsolute( rootFn.GetPath() );
402 
403 
404  // The source and destination sheet file names cannot be the same.
405  if( srcFn == destFn )
406  {
407  m_recursion_test_cache[pair] = true;
408  return true;
409  }
410 
414  unsigned i = 0;
415 
416  while( i < size() )
417  {
418  wxFileName cmpFn = at( i )->GetFileName();
419 
420  if( cmpFn.IsRelative() )
421  cmpFn.MakeAbsolute( rootFn.GetPath() );
422 
423  // Test if the file name of the destination sheet is in anywhere in this sheet path.
424  if( cmpFn == destFn )
425  break;
426 
427  i++;
428  }
429 
430  // The destination sheet file name was not found in the sheet path or the destination
431  // sheet file name is the root sheet so no recursion is possible.
432  if( i >= size() || i == 0 )
433  {
434  m_recursion_test_cache[pair] = false;
435  return false;
436  }
437 
438  // Walk back up to the root sheet to see if the source file name is already a parent in
439  // the sheet path. If so, recursion will occur.
440  do
441  {
442  i -= 1;
443 
444  wxFileName cmpFn = at( i )->GetFileName();
445 
446  if( cmpFn.IsRelative() )
447  cmpFn.MakeAbsolute( rootFn.GetPath() );
448 
449  if( cmpFn == srcFn )
450  {
451  m_recursion_test_cache[pair] = true;
452  return true;
453  }
454 
455  } while( i != 0 );
456 
457  // The source sheet file name is not a parent of the destination sheet file name.
458  m_recursion_test_cache[pair] = false;
459  return false;
460 }
Holds all the data relating to one schematic.
Definition: schematic.h:59
std::map< std::pair< wxString, wxString >, bool > m_recursion_test_cache
Page numbers are maintained by the sheet load order.
size_t size() const
Forwarded method from std::vector.
wxString GetFileName() const override
Helper to retrieve the filename from the root sheet screen.
Definition: schematic.cpp:161
wxString GetFileName() const
Return the filename corresponding to this sheet.
Definition: sch_sheet.h:317
SCH_SCREEN * LastScreen()
SCHEMATIC * Schematic() const
Definition: sch_screen.cpp:92
SCH_SHEET * at(size_t aIndex) const
Forwarded method from std::vector.

References at(), SCHEMATIC::GetFileName(), SCH_SHEET::GetFileName(), LastScreen(), m_recursion_test_cache, SCH_SCREEN::Schematic(), and size().

Referenced by SCH_SHEET_LIST::BuildSheetList().

◆ UpdateAllScreenReferences()

void SCH_SHEET_PATH::UpdateAllScreenReferences ( )

Update all the symbol references for this sheet path.

Mandatory in complex hierarchies because sheets may use the same screen (basic schematic) more than once but with different references and units according to the displayed sheet.

Definition at line 293 of file sch_sheet_path.cpp.

294 {
295  for( SCH_ITEM* item : LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
296  {
297  SCH_SYMBOL* symbol = static_cast<SCH_SYMBOL*>( item );
298  symbol->GetField( REFERENCE_FIELD )->SetText( symbol->GetRef( this ) );
299  symbol->GetField( VALUE_FIELD )->SetText( symbol->GetValue( this, false ) );
300  symbol->GetField( FOOTPRINT_FIELD )->SetText( symbol->GetFootprint( this, false ) );
301  symbol->UpdateUnit( symbol->GetUnitSelection( this ) );
302  }
303 }
Field Reference of part, i.e. "IC21".
SCH_FIELD * GetField(MANDATORY_FIELD_T aFieldType)
Return a mandatory field in this symbol.
Definition: sch_symbol.cpp:677
const wxString GetRef(const SCH_SHEET_PATH *aSheet, bool aIncludeUnit=false) const
Return the reference for the given sheet path.
Definition: sch_symbol.cpp:443
void UpdateUnit(int aUnit)
Change the unit number to aUnit without setting any internal flags.
Definition: sch_symbol.cpp:343
Field Value of part, i.e. "3.3K".
virtual void SetText(const wxString &aText)
Definition: eda_text.cpp:124
int GetUnitSelection(const SCH_SHEET_PATH *aSheet) const
Return the instance-specific unit selection for the given sheet path.
Definition: sch_symbol.cpp:533
const wxString GetValue(const SCH_SHEET_PATH *sheet, bool aResolve) const
Return the instance-specific value for the given sheet path.
Definition: sch_symbol.cpp:575
Schematic symbol object.
Definition: sch_symbol.h:78
SCH_SCREEN * LastScreen()
const wxString GetFootprint(const SCH_SHEET_PATH *sheet, bool aResolve) const
Return the instance-specific footprint assignment for the given sheet path.
Definition: sch_symbol.cpp:626
Base class for any item which can be embedded within the SCHEMATIC container class,...
Definition: sch_item.h:182
Field Name Module PCB, i.e. "16DIP300".

References FOOTPRINT_FIELD, SCH_SYMBOL::GetField(), SCH_SYMBOL::GetFootprint(), SCH_SYMBOL::GetRef(), SCH_SYMBOL::GetUnitSelection(), SCH_SYMBOL::GetValue(), LastScreen(), REFERENCE_FIELD, SCH_SYMBOL_T, EDA_TEXT::SetText(), SCH_SYMBOL::UpdateUnit(), and VALUE_FIELD.

Referenced by SCH_EDIT_FRAME::AnnotateSymbols(), DIALOG_PLOT_SCHEMATIC::createDXFFiles(), DIALOG_PLOT_SCHEMATIC::createHPGLFiles(), DIALOG_PLOT_SCHEMATIC::createPDFFile(), DIALOG_PLOT_SCHEMATIC::createPSFiles(), DIALOG_PLOT_SCHEMATIC::createSVGFiles(), SCH_EDIT_FRAME::DeleteAnnotation(), SCH_EDIT_FRAME::DisplayCurrentSheet(), SCH_EDITOR_CONTROL::FindNext(), SCH_EDIT_FRAME::FixupJunctions(), DIALOG_MIGRATE_BUSES::onItemSelected(), SCH_PRINTOUT::OnPrintPage(), DIALOG_UPDATE_FROM_PCB::OnUpdateClick(), SCH_EDIT_FRAME::OpenProjectFiles(), SCH_EDITOR_CONTROL::Paste(), DIALOG_CHANGE_SYMBOLS::processMatchingSymbols(), SCH_EDITOR_CONTROL::ReplaceAll(), SCH_EDITOR_CONTROL::ReplaceAndFindNext(), and DIALOG_PLOT_SCHEMATIC::restoreEnvironment().

Member Data Documentation

◆ m_current_hash

size_t SCH_SHEET_PATH::m_current_hash
protected

Definition at line 380 of file sch_sheet_path.h.

Referenced by GetCurrentHash(), initFromOther(), operator==(), Rehash(), and SCH_SHEET_PATH().

◆ m_recursion_test_cache

std::map<std::pair<wxString, wxString>, bool> SCH_SHEET_PATH::m_recursion_test_cache
protected

Page numbers are maintained by the sheet load order.

Definition at line 384 of file sch_sheet_path.h.

Referenced by TestForRecursion().

◆ m_sheets

std::vector< SCH_SHEET* > SCH_SHEET_PATH::m_sheets
protected

◆ m_virtualPageNumber

int SCH_SHEET_PATH::m_virtualPageNumber
protected

The documentation for this class was generated from the following files: