KiCad PCB EDA Suite
SCH_REFERENCE Class Reference

A helper to define a symbol's reference designator in a schematic. More...

#include <sch_reference_list.h>

Public Member Functions

 SCH_REFERENCE ()
 
 SCH_REFERENCE (SCH_SYMBOL *aSymbol, LIB_SYMBOL *aLibSymbol, const SCH_SHEET_PATH &aSheetPath)
 
SCH_SYMBOLGetSymbol () const
 
LIB_SYMBOLGetLibPart () const
 
const SCH_SHEET_PATHGetSheetPath () const
 
SCH_SHEET_PATHGetSheetPath ()
 
int GetUnit () const
 
void SetUnit (int aUnit)
 
const wxString GetValue () const
 
void SetValue (const wxString &aValue)
 
const wxString GetFootprint () const
 
void SetFootprint (const wxString &aFP)
 
void SetSheetNumber (int aSheetNumber)
 
const wxString GetPath () const
 
const wxString GetFullPath () const
 
void Annotate ()
 Update the annotation of the symbol according the current object state. More...
 
bool AlwaysAnnotate () const
 Verify the reference should always be automatically annotated. More...
 
void Split ()
 Attempt to split the reference designator into a name (U) and number (1). More...
 
bool IsSplitNeeded ()
 Determine if this reference needs to be split or if it likely already has been. More...
 
void SetRef (const wxString &aReference)
 
wxString GetRef () const
 
void SetRefStr (const std::string &aReference)
 
const char * GetRefStr () const
 Return reference name with unit altogether. More...
 
wxString GetFullRef () const
 
wxString GetRefNumber () const
 
int CompareValue (const SCH_REFERENCE &item) const
 
int CompareRef (const SCH_REFERENCE &item) const
 
int CompareLibName (const SCH_REFERENCE &item) const
 
bool IsSameInstance (const SCH_REFERENCE &other) const
 Return whether this reference refers to the same symbol instance (symbol and sheet) as another. More...
 
bool IsUnitsLocked ()
 

Private Attributes

wxString m_ref
 Symbol reference prefix, without number (for IC1, this is IC) ) More...
 
SCH_SYMBOLm_rootSymbol
 The symbol associated the reference object. More...
 
LIB_SYMBOLm_libPart
 The source symbol from a library. More...
 
VECTOR2I m_symbolPos
 The physical position of the symbol in schematic used to annotate by X or Y position. More...
 
int m_unit
 The unit number for symbol with multiple parts per package. More...
 
wxString m_value
 The symbol value. More...
 
wxString m_footprint
 The footprint assigned. More...
 
SCH_SHEET_PATH m_sheetPath
 The sheet path for this reference. More...
 
bool m_isNew
 True if not yet annotated. More...
 
int m_sheetNum
 The sheet number for the reference. More...
 
KIID m_symbolUuid
 UUID of the symbol. More...
 
int m_numRef
 The numeric part of the reference designator. More...
 
int m_flag
 

Friends

class SCH_REFERENCE_LIST
 

Detailed Description

A helper to define a symbol's reference designator in a schematic.

This helper is required in a complex hierarchy because a symbol can be used more than once and its reference depends on the sheet path. This class is used to flatten the schematic hierarchy for annotation, net list generation, and bill of material generation.

Definition at line 76 of file sch_reference_list.h.

Constructor & Destructor Documentation

◆ SCH_REFERENCE() [1/2]

SCH_REFERENCE::SCH_REFERENCE ( )
inline

Definition at line 79 of file sch_reference_list.h.

79 :
81 {
82 m_rootSymbol = nullptr;
83 m_libPart = nullptr;
84 m_unit = 0;
85 m_isNew = false;
86 m_numRef = 0;
87 m_flag = 0;
88 m_sheetNum = 0;
89 }
SCH_SYMBOL * m_rootSymbol
The symbol associated the reference object.
int m_unit
The unit number for symbol with multiple parts per package.
SCH_SHEET_PATH m_sheetPath
The sheet path for this reference.
bool m_isNew
True if not yet annotated.
int m_sheetNum
The sheet number for the reference.
int m_numRef
The numeric part of the reference designator.
LIB_SYMBOL * m_libPart
The source symbol from a library.

References m_flag, m_isNew, m_libPart, m_numRef, m_rootSymbol, m_sheetNum, and m_unit.

◆ SCH_REFERENCE() [2/2]

SCH_REFERENCE::SCH_REFERENCE ( SCH_SYMBOL aSymbol,
LIB_SYMBOL aLibSymbol,
const SCH_SHEET_PATH aSheetPath 
)

Definition at line 814 of file sch_reference_list.cpp.

816{
817 wxASSERT( aSymbol != nullptr );
818
819 m_rootSymbol = aSymbol;
820 m_libPart = aLibSymbol; // Warning: can be nullptr for orphan symbols
821 // (i.e. with a symbol library not found)
822 m_unit = aSymbol->GetUnitSelection( &aSheetPath );
823 m_footprint = aSymbol->GetFootprintFieldText( true );
824 m_sheetPath = aSheetPath;
825 m_isNew = false;
826 m_flag = 0;
827 m_symbolUuid = aSymbol->m_Uuid;
828 m_symbolPos = aSymbol->GetPosition();
829 m_sheetNum = 0;
830
831 if( aSymbol->GetRef( &aSheetPath ).IsEmpty() )
832 aSymbol->SetRef( &aSheetPath, wxT( "DefRef?" ) );
833
834 wxString ref = aSymbol->GetRef( &aSheetPath );
835 SetRef( ref );
836
837 m_numRef = -1;
838
839 if( aSymbol->GetValueFieldText( false ).IsEmpty() )
840 aSymbol->SetValueFieldText( wxT( "~" ) );
841
842 m_value = aSymbol->GetValueFieldText( false );
843}
const KIID m_Uuid
Definition: eda_item.h:492
wxString m_footprint
The footprint assigned.
void SetRef(const wxString &aReference)
KIID m_symbolUuid
UUID of the symbol.
wxString m_value
The symbol value.
VECTOR2I m_symbolPos
The physical position of the symbol in schematic used to annotate by X or Y position.
void SetValueFieldText(const wxString &aValue)
Definition: sch_symbol.cpp:844
const wxString GetRef(const SCH_SHEET_PATH *aSheet, bool aIncludeUnit=false) const
Return the reference for the given sheet path.
Definition: sch_symbol.cpp:674
void SetRef(const SCH_SHEET_PATH *aSheet, const wxString &aReference)
Set the reference for the given sheet path for this symbol.
Definition: sch_symbol.cpp:716
const wxString GetFootprintFieldText(bool aResolve) const
Definition: sch_symbol.cpp:850
VECTOR2I GetPosition() const override
Definition: sch_symbol.h:712
const wxString GetValueFieldText(bool aResolve) const
Definition: sch_symbol.cpp:835
int GetUnitSelection(const SCH_SHEET_PATH *aSheet) const
Return the instance-specific unit selection for the given sheet path.
Definition: sch_symbol.cpp:793

References SCH_SYMBOL::GetFootprintFieldText(), SCH_SYMBOL::GetPosition(), SCH_SYMBOL::GetRef(), SCH_SYMBOL::GetUnitSelection(), SCH_SYMBOL::GetValueFieldText(), m_flag, m_footprint, m_isNew, m_libPart, m_numRef, m_rootSymbol, m_sheetNum, m_sheetPath, m_symbolPos, m_symbolUuid, m_unit, EDA_ITEM::m_Uuid, m_value, SCH_SYMBOL::SetRef(), SetRef(), and SCH_SYMBOL::SetValueFieldText().

Member Function Documentation

◆ AlwaysAnnotate()

bool SCH_REFERENCE::AlwaysAnnotate ( ) const

Verify the reference should always be automatically annotated.

Returns
true if the symbol reference should always be automatically annotated otherwise false.

Definition at line 859 of file sch_reference_list.cpp.

860{
862 && !m_rootSymbol->GetRef( &m_sheetPath ).IsEmpty(), false );
863
864 return m_rootSymbol->GetLibSymbolRef()->IsPower()
865 || m_rootSymbol->GetRef( &m_sheetPath )[0] == wxUniChar( '#' );
866}
std::unique_ptr< LIB_SYMBOL > & GetLibSymbolRef()
Definition: sch_symbol.h:192

References SCH_SYMBOL::GetLibSymbolRef(), SCH_SYMBOL::GetRef(), m_rootSymbol, and m_sheetPath.

Referenced by SCH_DRAWING_TOOLS::PlaceSymbol().

◆ Annotate()

void SCH_REFERENCE::Annotate ( )

Update the annotation of the symbol according the current object state.

Definition at line 846 of file sch_reference_list.cpp.

847{
848 if( m_numRef < 0 )
849 m_ref += '?';
850 else
851 m_ref = TO_UTF8( GetRef() << GetRefNumber() );
852
856}
wxString m_ref
Symbol reference prefix, without number (for IC1, this is IC) )
wxString GetRef() const
wxString GetRefNumber() const
void SetUnit(int aUnit)
Change the unit number to aUnit.
Definition: sch_symbol.cpp:388
void SetUnitSelection(const SCH_SHEET_PATH *aSheet, int aUnitSelection)
Set the selected unit of this symbol on one sheet.
Definition: sch_symbol.cpp:809
#define TO_UTF8(wxstring)
Convert a wxString to a UTF8 encoded C string for all wxWidgets build modes.
Definition: macros.h:96
static wxString FROM_UTF8(const char *cstring)
Convert a UTF8 encoded C string to a wxString for all wxWidgets build modes.
Definition: macros.h:110

References FROM_UTF8(), GetRef(), GetRefNumber(), m_numRef, m_ref, m_rootSymbol, m_sheetPath, m_unit, SCH_SYMBOL::SetRef(), SCH_SYMBOL::SetUnit(), SCH_SYMBOL::SetUnitSelection(), and TO_UTF8.

Referenced by SCH_EDIT_FRAME::AnnotateSymbols().

◆ CompareLibName()

int SCH_REFERENCE::CompareLibName ( const SCH_REFERENCE item) const
inline

Definition at line 197 of file sch_reference_list.h.

198 {
201 }
const UTF8 & GetLibItemName() const
Definition: lib_id.h:102
const LIB_ID & GetLibId() const
Definition: sch_symbol.h:175
int compare(const std::string &s) const
Definition: utf8.h:111

References UTF8::compare(), SCH_SYMBOL::GetLibId(), LIB_ID::GetLibItemName(), and m_rootSymbol.

Referenced by SCH_REFERENCE_LIST::Annotate().

◆ CompareRef()

int SCH_REFERENCE::CompareRef ( const SCH_REFERENCE item) const
inline

◆ CompareValue()

int SCH_REFERENCE::CompareValue ( const SCH_REFERENCE item) const
inline

Definition at line 187 of file sch_reference_list.h.

188 {
189 return m_value.Cmp( item.m_value );
190 }

References m_value.

Referenced by SCH_REFERENCE_LIST::Annotate(), SCH_REFERENCE_LIST::CheckAnnotation(), and SCH_REFERENCE_LIST::sortByRefAndValue().

◆ GetFootprint()

const wxString SCH_REFERENCE::GetFootprint ( ) const
inline

Definition at line 107 of file sch_reference_list.h.

107{ return m_footprint; }

References m_footprint.

Referenced by BACK_ANNOTATE::applyChangelist(), and ERC_TESTER::TestMultiunitFootprints().

◆ GetFullPath()

const wxString SCH_REFERENCE::GetFullPath ( ) const
inline
Returns
the full patb of the symbol item

Definition at line 123 of file sch_reference_list.h.

124 {
126 }
wxString AsString() const
Definition: kiid.cpp:257
wxString PathAsString() const
Return the path of time stamps which do not changes even when editing sheet parameters.

References KIID::AsString(), m_sheetPath, m_symbolUuid, and SCH_SHEET_PATH::PathAsString().

◆ GetFullRef()

wxString SCH_REFERENCE::GetFullRef ( ) const
inline

Definition at line 164 of file sch_reference_list.h.

165 {
166 if( GetSymbol()->GetUnitCount() > 1 )
168 else
169 return GetRef() + GetRefNumber();
170 }
static wxString SubReference(int aUnit, bool aAddSeparator=true)
Definition: lib_symbol.cpp:581
SCH_SYMBOL * GetSymbol() const
int GetUnit() const

References GetRef(), GetRefNumber(), GetSymbol(), GetUnit(), and LIB_SYMBOL::SubReference().

Referenced by FIELDS_EDITOR_GRID_DATA_MODEL::RebuildRows().

◆ GetLibPart()

LIB_SYMBOL * SCH_REFERENCE::GetLibPart ( ) const
inline

Definition at line 95 of file sch_reference_list.h.

95{ return m_libPart; }

References m_libPart.

Referenced by SCH_REFERENCE_LIST::CheckAnnotation(), GetRefNumber(), and ERC_TESTER::TestMissingUnits().

◆ GetPath()

const wxString SCH_REFERENCE::GetPath ( ) const
inline
Returns
the sheet path containing the symbol item

Definition at line 115 of file sch_reference_list.h.

116 {
117 return m_sheetPath.PathAsString();
118 }

References m_sheetPath, and SCH_SHEET_PATH::PathAsString().

◆ GetRef()

◆ GetRefNumber()

wxString SCH_REFERENCE::GetRefNumber ( ) const
inline

Definition at line 172 of file sch_reference_list.h.

173 {
174 wxString ref;
175
176 if( m_numRef < 0 )
177 return wxT( "?" );
178
179 // To avoid a risk of duplicate, for power symbols the ref number is 0nnn instead of nnn.
180 // Just because sometimes only power symbols are annotated
181 if( GetLibPart() && GetLibPart()->IsPower() )
182 ref = wxT( "0" );
183
184 return ref << m_numRef;
185 }
LIB_SYMBOL * GetLibPart() const

References GetLibPart(), and m_numRef.

Referenced by Annotate(), buildFullReference(), findSymbolsAndPins(), GetFullRef(), sheetContainsOnlyWantedItems(), and FIELDS_EDITOR_GRID_DATA_MODEL::unitMatch().

◆ GetRefStr()

const char * SCH_REFERENCE::GetRefStr ( ) const
inline

Return reference name with unit altogether.

Definition at line 161 of file sch_reference_list.h.

References m_ref.

Referenced by IsSplitNeeded(), and Split().

◆ GetSheetPath() [1/2]

SCH_SHEET_PATH & SCH_REFERENCE::GetSheetPath ( )
inline

Definition at line 99 of file sch_reference_list.h.

99{ return m_sheetPath; }

References m_sheetPath.

◆ GetSheetPath() [2/2]

◆ GetSymbol()

◆ GetUnit()

int SCH_REFERENCE::GetUnit ( ) const
inline

◆ GetValue()

const wxString SCH_REFERENCE::GetValue ( ) const
inline

Definition at line 104 of file sch_reference_list.h.

104{ return m_value; }

References m_value.

Referenced by BACK_ANNOTATE::applyChangelist().

◆ IsSameInstance()

bool SCH_REFERENCE::IsSameInstance ( const SCH_REFERENCE other) const
inline

Return whether this reference refers to the same symbol instance (symbol and sheet) as another.

Definition at line 207 of file sch_reference_list.h.

208 {
209 // Only compare symbol and path.
210 // We may have changed the unit number or the designator but
211 // can still be referencing the same instance.
212 return GetSymbol() == other.GetSymbol()
213 && GetSheetPath().Path() == other.GetSheetPath().Path();
214 }
const SCH_SHEET_PATH & GetSheetPath() const
KIID_PATH Path() const
Get the sheet path as an KIID_PATH.

References GetSheetPath(), GetSymbol(), and SCH_SHEET_PATH::Path().

Referenced by SCH_REFERENCE_LIST::Annotate().

◆ IsSplitNeeded()

bool SCH_REFERENCE::IsSplitNeeded ( )

Determine if this reference needs to be split or if it likely already has been.

Returns
true if this reference hasn't been split yet

Definition at line 915 of file sch_reference_list.cpp.

916{
917 std::string refText = GetRefStr();
918
919 int ll = refText.length() - 1;
920
921 return ( refText[ll] == '?' ) || isdigit( refText[ll] );
922}
const char * GetRefStr() const
Return reference name with unit altogether.

References GetRefStr().

Referenced by findSymbolsAndPins(), and sheetContainsOnlyWantedItems().

◆ IsUnitsLocked()

bool SCH_REFERENCE::IsUnitsLocked ( )
inline

Definition at line 216 of file sch_reference_list.h.

217 {
218 if( m_libPart )
219 return m_libPart->UnitsLocked();
220 else
221 return true; // Assume units locked when we don't have a library
222 }
bool UnitsLocked() const
Check whether symbol units are interchangeable.
Definition: lib_symbol.h:258

References m_libPart, and LIB_SYMBOL::UnitsLocked().

◆ SetFootprint()

void SCH_REFERENCE::SetFootprint ( const wxString &  aFP)
inline

Definition at line 108 of file sch_reference_list.h.

108{ m_footprint = aFP; }

References m_footprint.

◆ SetRef()

void SCH_REFERENCE::SetRef ( const wxString &  aReference)
inline

Definition at line 157 of file sch_reference_list.h.

157{ m_ref = aReference; }

References m_ref.

Referenced by SCH_REFERENCE().

◆ SetRefStr()

void SCH_REFERENCE::SetRefStr ( const std::string &  aReference)
inline

Definition at line 160 of file sch_reference_list.h.

160{ m_ref = aReference; }

References m_ref.

Referenced by Split().

◆ SetSheetNumber()

void SCH_REFERENCE::SetSheetNumber ( int  aSheetNumber)
inline

◆ SetUnit()

void SCH_REFERENCE::SetUnit ( int  aUnit)
inline

Definition at line 102 of file sch_reference_list.h.

102{ m_unit = aUnit; }

References m_unit.

◆ SetValue()

void SCH_REFERENCE::SetValue ( const wxString &  aValue)
inline

Definition at line 105 of file sch_reference_list.h.

105{ m_value = aValue; }

References m_value.

◆ Split()

void SCH_REFERENCE::Split ( )

Attempt to split the reference designator into a name (U) and number (1).

If the last character is '?' or not a digit, the reference is tagged as not annotated. For symbols with multiple parts per package that are not already annotated, keeps the unit number the same. E.g. U?A or U?B

Definition at line 869 of file sch_reference_list.cpp.

870{
871 std::string refText = GetRefStr();
872
873 m_numRef = -1;
874
875 int ll = refText.length() - 1;
876
877 if( refText[ll] == '?' )
878 {
879 m_isNew = true;
880
881 refText.erase( ll ); // delete last char
882
883 SetRefStr( refText );
884 }
885 else if( isdigit( refText[ll] ) == 0 )
886 {
887 m_isNew = true;
888 }
889 else
890 {
891 while( ll >= 0 )
892 {
893 if( (refText[ll] <= ' ' ) || isdigit( refText[ll] ) )
894 ll--;
895 else
896 {
897 if( isdigit( refText[ll + 1] ) )
898 {
899 // null terminated C string into cp
900 const char* cp = refText.c_str() + ll + 1;
901
902 m_numRef = atoi( cp );
903 }
904
905 refText.erase( ll+1 ); // delete from ll+1 to end
906 break;
907 }
908 }
909
910 SetRefStr( refText );
911 }
912}
void SetRefStr(const std::string &aReference)

References GetRefStr(), m_isNew, m_numRef, and SetRefStr().

Referenced by SCH_REFERENCE_LIST::Annotate(), findSymbolsAndPins(), and sheetContainsOnlyWantedItems().

Friends And Related Function Documentation

◆ SCH_REFERENCE_LIST

friend class SCH_REFERENCE_LIST
friend

Definition at line 225 of file sch_reference_list.h.

Member Data Documentation

◆ m_flag

int SCH_REFERENCE::m_flag
private

Definition at line 242 of file sch_reference_list.h.

Referenced by SCH_REFERENCE().

◆ m_footprint

wxString SCH_REFERENCE::m_footprint
private

The footprint assigned.

Definition at line 236 of file sch_reference_list.h.

Referenced by GetFootprint(), SCH_REFERENCE(), and SetFootprint().

◆ m_isNew

bool SCH_REFERENCE::m_isNew
private

True if not yet annotated.

Definition at line 238 of file sch_reference_list.h.

Referenced by SCH_REFERENCE_LIST::Annotate(), SCH_REFERENCE_LIST::ReannotateByOptions(), SCH_REFERENCE(), and Split().

◆ m_libPart

LIB_SYMBOL* SCH_REFERENCE::m_libPart
private

The source symbol from a library.

Definition at line 230 of file sch_reference_list.h.

Referenced by GetLibPart(), IsUnitsLocked(), and SCH_REFERENCE().

◆ m_numRef

int SCH_REFERENCE::m_numRef
private

The numeric part of the reference designator.

Definition at line 241 of file sch_reference_list.h.

Referenced by Annotate(), SCH_REFERENCE_LIST::CheckAnnotation(), GetRefNumber(), SCH_REFERENCE_LIST::GetUnitsMatchingRef(), SCH_REFERENCE(), and Split().

◆ m_ref

wxString SCH_REFERENCE::m_ref
private

Symbol reference prefix, without number (for IC1, this is IC) )

Definition at line 228 of file sch_reference_list.h.

Referenced by Annotate(), CompareRef(), GetRef(), GetRefStr(), SetRef(), and SetRefStr().

◆ m_rootSymbol

SCH_SYMBOL* SCH_REFERENCE::m_rootSymbol
private

The symbol associated the reference object.

Definition at line 229 of file sch_reference_list.h.

Referenced by AlwaysAnnotate(), Annotate(), CompareLibName(), GetSymbol(), and SCH_REFERENCE().

◆ m_sheetNum

int SCH_REFERENCE::m_sheetNum
private

◆ m_sheetPath

SCH_SHEET_PATH SCH_REFERENCE::m_sheetPath
private

The sheet path for this reference.

Definition at line 237 of file sch_reference_list.h.

Referenced by AlwaysAnnotate(), Annotate(), GetFullPath(), GetPath(), GetSheetPath(), SCH_REFERENCE(), and SCH_REFERENCE_LIST::sortByTimeStamp().

◆ m_symbolPos

VECTOR2I SCH_REFERENCE::m_symbolPos
private

The physical position of the symbol in schematic used to annotate by X or Y position.

Definition at line 231 of file sch_reference_list.h.

Referenced by SCH_REFERENCE(), SCH_REFERENCE_LIST::sortByRefAndValue(), SCH_REFERENCE_LIST::sortByXPosition(), and SCH_REFERENCE_LIST::sortByYPosition().

◆ m_symbolUuid

◆ m_unit

◆ m_value

wxString SCH_REFERENCE::m_value
private

The symbol value.

Definition at line 235 of file sch_reference_list.h.

Referenced by SCH_REFERENCE_LIST::CheckAnnotation(), CompareValue(), GetValue(), SCH_REFERENCE(), and SetValue().


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