KiCad PCB EDA Suite
sch_reference_list.h
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 1992-2011 jean-pierre Charras <[email protected]>
5 * Copyright (C) 2011 Wayne Stambaugh <[email protected]>
6 * Copyright (C) 1992-2022 KiCad Developers, see AUTHORS.txt for contributors.
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation; either version 2
11 * of the License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, you may find one here:
20 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
21 * or you may search the http://www.gnu.org website for the version 2 license,
22 * or you may write to the Free Software Foundation, Inc.,
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
24 */
25
26#ifndef _SCH_REFERENCE_LIST_H_
27#define _SCH_REFERENCE_LIST_H_
28
29#include <map>
30
31#include <lib_symbol.h>
32#include <macros.h>
33#include <sch_sheet_path.h>
34#include <sch_symbol.h>
35#include <sch_text.h>
36#include <erc_settings.h>
37
38
41{
45};
46
47
50{
53 UNSORTED,
55};
56
57
60{
66};
67
68
77{
78public:
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 }
90
91 SCH_REFERENCE( SCH_SYMBOL* aSymbol, LIB_SYMBOL* aLibSymbol, const SCH_SHEET_PATH& aSheetPath );
92
93 SCH_SYMBOL* GetSymbol() const { return m_rootSymbol; }
94
95 LIB_SYMBOL* GetLibPart() const { return m_libPart; }
96
97 const SCH_SHEET_PATH& GetSheetPath() const { return m_sheetPath; }
98
100
101 int GetUnit() const { return m_unit; }
102 void SetUnit( int aUnit ) { m_unit = aUnit; }
103
104 const wxString GetValue() const { return m_value; }
105 void SetValue( const wxString& aValue ) { m_value = aValue; }
106
107 const wxString GetFootprint() const { return m_footprint; }
108 void SetFootprint( const wxString& aFP ) { m_footprint = aFP; }
109
110 void SetSheetNumber( int aSheetNumber ) { m_sheetNum = aSheetNumber; }
111
112 const wxString GetPath() const
113 {
114 return m_sheetPath.PathAsString();
115 }
116
120 void Annotate();
121
129 void Split();
130
136 bool IsSplitNeeded();
137
138 void SetRef( const wxString& aReference ) { m_ref = aReference; }
139 wxString GetRef() const { return m_ref; }
140
141 void SetRefStr( const std::string& aReference ) { m_ref = aReference; }
142 const char* GetRefStr() const { return m_ref.c_str(); }
143
145 wxString GetFullRef() const
146 {
147 if( GetSymbol()->GetUnitCount() > 1 )
149 else
150 return GetRef() + GetRefNumber();
151 }
152
153 wxString GetRefNumber() const
154 {
155 wxString ref;
156
157 if( m_numRef < 0 )
158 return wxT( "?" );
159
160 // To avoid a risk of duplicate, for power symbols the ref number is 0nnn instead of nnn.
161 // Just because sometimes only power symbols are annotated
162 if( GetLibPart() && GetLibPart()->IsPower() )
163 ref = wxT( "0" );
164
165 return ref << m_numRef;
166 }
167
168 int CompareValue( const SCH_REFERENCE& item ) const
169 {
170 return m_value.Cmp( item.m_value );
171 }
172
173 int CompareRef( const SCH_REFERENCE& item ) const
174 {
175 return m_ref.CmpNoCase( item.m_ref );
176 }
177
178 int CompareLibName( const SCH_REFERENCE& item ) const
179 {
182 }
183
188 bool IsSameInstance( const SCH_REFERENCE& other ) const
189 {
190 // Only compare symbol and path.
191 // We may have changed the unit number or the designator but
192 // can still be referencing the same instance.
193 return GetSymbol() == other.GetSymbol()
194 && GetSheetPath().Path() == other.GetSheetPath().Path();
195 }
196
198 {
199 if( m_libPart )
200 return m_libPart->UnitsLocked();
201 else
202 return true; // Assume units locked when we don't have a library
203 }
204
205private:
206 friend class SCH_REFERENCE_LIST;
207
209 wxString m_ref; // it's private, use the accessors please
214 int m_unit;
216 wxString m_value;
217 wxString m_footprint;
219 bool m_isNew;
224};
225
226
230typedef std::function<void( ERCE_T aType, const wxString& aMsg, SCH_REFERENCE* aItemA,
232
233
242{
243
244private:
245 std::vector<SCH_REFERENCE> flatList;
246
247public:
249 {
250 }
251
253 {
254 return flatList[ aIndex ];
255 }
256
257 const SCH_REFERENCE& operator[]( int aIndex ) const
258 {
259 return flatList[ aIndex ];
260 }
261
262 void Clear()
263 {
264 flatList.clear();
265 }
266
267 size_t GetCount() const { return flatList.size(); }
268
269 SCH_REFERENCE& GetItem( int aIdx ) { return flatList[aIdx]; }
270 const SCH_REFERENCE& GetItem( int aIdx ) const { return flatList[aIdx]; }
271
272 void AddItem( const SCH_REFERENCE& aItem ) { flatList.push_back( aItem ); }
273
279 void RemoveItem( unsigned int aIndex );
280
286 bool Contains( const SCH_REFERENCE& aItem ) const;
287
288 /* Sort functions:
289 * Sort functions are used to sort symbols for annotation or BOM generation. Because
290 * sorting depends on what we want to do, there are many sort functions.
291 * Note:
292 * When creating BOM, symbols are fully annotated. References are something like U3,
293 * U5 or R4, R8. When annotating, some or all symbols are not annotated, i.e. ref is
294 * only U or R, with no number.
295 */
296
305 {
306 for( unsigned ii = 0; ii < GetCount(); ii++ )
307 flatList[ii].Split();
308 }
309
315 void RemoveAnnotation( bool aIncludePowerSymbols )
316 {
317 for( unsigned ii = 0; ii < GetCount(); ii++ )
318 {
319 if( !flatList[ii].m_libPart->IsPower() || aIncludePowerSymbols )
320 flatList[ii].m_isNew = true;
321 }
322 }
323
333 {
334 /* update the reference numbers */
335 for( unsigned ii = 0; ii < GetCount(); ii++ )
336 flatList[ii].Annotate();
337 }
338
353 void ReannotateByOptions( ANNOTATE_ORDER_T aSortOption,
354 ANNOTATE_ALGO_T aAlgoOption,
355 int aStartNumber,
356 const SCH_REFERENCE_LIST& aAdditionalRefs,
357 bool aStartAtCurrent,
358 SCH_SHEET_LIST* aHierarchy );
359
369 void ReannotateDuplicates( const SCH_REFERENCE_LIST& aAdditionalReferences );
370
386 void AnnotateByOptions( enum ANNOTATE_ORDER_T aSortOption,
387 enum ANNOTATE_ALGO_T aAlgoOption,
388 int aStartNumber,
389 SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap,
390 const SCH_REFERENCE_LIST& aAdditionalRefs,
391 bool aStartAtCurrent );
392
414 void Annotate( bool aUseSheetNum, int aSheetIntervalId, int aStartNumber,
415 SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap,
416 const SCH_REFERENCE_LIST& aAdditionalRefs, bool aStartAtCurrent = false );
417
430 int CheckAnnotation( ANNOTATION_ERROR_HANDLER aErrorHandler );
431
443 {
444 sort( flatList.begin(), flatList.end(), sortByXPosition );
445 }
446
458 {
459 sort( flatList.begin(), flatList.end(), sortByYPosition );
460 }
461
468 {
469 sort( flatList.begin(), flatList.end(), sortByTimeStamp );
470 }
471
484 {
485 sort( flatList.begin(), flatList.end(), sortByRefAndValue );
486 }
487
496 {
497 sort( flatList.begin(), flatList.end(), sortByReferenceOnly );
498 }
499
503 int FindRef( const wxString& aPath ) const;
504
514 int FindUnit( size_t aIndex, int aUnit, bool aIncludeNew = false ) const;
515
522 int FindRefByPath( const wxString& aPath ) const;
523
532 void GetRefsInUse( int aIndex, std::vector<int>& aIdList, int aMinRefId ) const;
533
540 std::vector<int> GetUnitsMatchingRef( const SCH_REFERENCE& aRef ) const;
541
550 int FindFirstUnusedReference( const SCH_REFERENCE& aRef, int aMinValue,
551 const std::vector<int>& aRequiredUnits ) const;
552
553 std::vector<SYMBOL_INSTANCE_REFERENCE> GetSymbolInstances() const;
554
555#if defined(DEBUG)
556 void Show( const char* aPrefix = "" )
557 {
558 printf( "%s\n", aPrefix );
559
560 for( unsigned i=0; i < flatList.size(); ++i )
561 {
562 SCH_REFERENCE& schref = flatList[i];
563
564 printf( " [%-2d] ref:%-8s num:%-3d lib_part:%s\n",
565 i,
566 schref.m_ref.ToStdString().c_str(),
567 schref.m_numRef,
568 TO_UTF8( schref.GetLibPart()->GetName() ) );
569 }
570 }
571#endif
572
577 static wxString Shorthand( std::vector<SCH_REFERENCE> aList );
578
579 friend class BACK_ANNOTATION;
580
581private:
582 static bool sortByRefAndValue( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
583
584 static bool sortByXPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
585
586 static bool sortByYPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
587
588 static bool sortByTimeStamp( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
589
590 static bool sortByReferenceOnly( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
591
604 static int createFirstFreeRefId( std::vector<int>& aIdList, int aFirstValue );
605
606 // Used for sorting static sortByTimeStamp function
607 friend class BACK_ANNOTATE;
608};
609
610#endif // _SCH_REFERENCE_LIST_H_
Back annotation algorithm class used to receive, check, and apply a NETLIST from Pcbnew.
Definition: backannotate.h:56
Definition: kiid.h:47
const UTF8 & GetLibItemName() const
Definition: lib_id.h:101
Define a library symbol object.
Definition: lib_symbol.h:98
bool UnitsLocked() const
Check whether symbol units are interchangeable.
Definition: lib_symbol.h:253
wxString GetName() const override
Definition: lib_symbol.h:136
static wxString SubReference(int aUnit, bool aAddSeparator=true)
Definition: lib_symbol.cpp:588
Container to create a flattened list of symbols because in a complex hierarchy, a symbol can be used ...
std::vector< SYMBOL_INSTANCE_REFERENCE > GetSymbolInstances() const
void SortByReferenceOnly()
Sort the list of references by reference.
int FindRefByPath(const wxString &aPath) const
Search the list for a symbol with the given KIID path.
void ReannotateByOptions(ANNOTATE_ORDER_T aSortOption, ANNOTATE_ALGO_T aAlgoOption, int aStartNumber, const SCH_REFERENCE_LIST &aAdditionalRefs, bool aStartAtCurrent, SCH_SHEET_LIST *aHierarchy)
Forces reannotation of the provided references.
static int createFirstFreeRefId(std::vector< int > &aIdList, int aFirstValue)
Search for the first free reference number in aListId of reference numbers in use.
static wxString Shorthand(std::vector< SCH_REFERENCE > aList)
Return a shorthand string representing all the references in the list.
static bool sortByRefAndValue(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
std::vector< SCH_REFERENCE > flatList
bool Contains(const SCH_REFERENCE &aItem) const
Return true if aItem exists in this list.
void SortByYCoordinate()
Sort the list of references by Y position.
const SCH_REFERENCE & operator[](int aIndex) const
void SortByTimeStamp()
Sort the flat list by Time Stamp (sheet path + timestamp).
void AnnotateByOptions(enum ANNOTATE_ORDER_T aSortOption, enum ANNOTATE_ALGO_T aAlgoOption, int aStartNumber, SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap, const SCH_REFERENCE_LIST &aAdditionalRefs, bool aStartAtCurrent)
Annotate the references by the provided options.
static bool sortByTimeStamp(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
int FindRef(const wxString &aPath) const
Search the list for a symbol with a given reference.
void Annotate(bool aUseSheetNum, int aSheetIntervalId, int aStartNumber, SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap, const SCH_REFERENCE_LIST &aAdditionalRefs, bool aStartAtCurrent=false)
Set the reference designators in the list that have not been annotated.
void SortByXCoordinate()
Sort the list of references by X position.
int FindUnit(size_t aIndex, int aUnit, bool aIncludeNew=false) const
Search the sorted list of symbols for a another symbol with the same reference and a given part unit.
static bool sortByXPosition(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
size_t GetCount() const
friend class BACK_ANNOTATION
const SCH_REFERENCE & GetItem(int aIdx) const
int FindFirstUnusedReference(const SCH_REFERENCE &aRef, int aMinValue, const std::vector< int > &aRequiredUnits) const
Return the first unused reference number from the properties given in aRef, ensuring all of the units...
void SplitReferences()
Attempt to split all reference designators into a name (U) and number (1).
SCH_REFERENCE & GetItem(int aIdx)
void SortByRefAndValue()
Sort the list of references by value.
std::vector< int > GetUnitsMatchingRef(const SCH_REFERENCE &aRef) const
Return all the unit numbers for a given reference, comparing library reference, value,...
static bool sortByReferenceOnly(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
void GetRefsInUse(int aIndex, std::vector< int > &aIdList, int aMinRefId) const
Add all the reference designator numbers greater than aMinRefId to aIdList skipping the reference at ...
void ReannotateDuplicates(const SCH_REFERENCE_LIST &aAdditionalReferences)
Convenience function for the Paste Unique functionality.
void AddItem(const SCH_REFERENCE &aItem)
void RemoveItem(unsigned int aIndex)
Remove an item from the list of references.
static bool sortByYPosition(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
void RemoveAnnotation(bool aIncludePowerSymbols)
Treat all symbols in this list as non-annotated.
SCH_REFERENCE & operator[](int aIndex)
void UpdateAnnotation()
Update the symbol references for the schematic project (or the current sheet).
int CheckAnnotation(ANNOTATION_ERROR_HANDLER aErrorHandler)
Check for annotations errors.
A helper to define a symbol's reference designator in a schematic.
const SCH_SHEET_PATH & GetSheetPath() const
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.
wxString m_footprint
The footprint assigned.
int CompareLibName(const SCH_REFERENCE &item) const
wxString GetFullRef() const
void SetValue(const wxString &aValue)
int CompareRef(const SCH_REFERENCE &item) const
void SetRef(const wxString &aReference)
const wxString GetFootprint() const
SCH_SHEET_PATH & GetSheetPath()
bool m_isNew
True if not yet annotated.
void SetUnit(int aUnit)
void Split()
Attempt to split the reference designator into a name (U) and number (1).
bool IsSplitNeeded()
Determine if this reference needs to be split or if it likely already has been.
SCH_SYMBOL * GetSymbol() const
void SetFootprint(const wxString &aFP)
wxString m_ref
Symbol reference prefix, without number (for IC1, this is IC) )
wxString GetRef() const
int m_sheetNum
The sheet number for the reference.
void SetRefStr(const std::string &aReference)
int m_numRef
The numeric part of the reference designator.
LIB_SYMBOL * GetLibPart() const
const wxString GetValue() const
void SetSheetNumber(int aSheetNumber)
const char * GetRefStr() const
Return reference name with unit altogether.
bool IsSameInstance(const SCH_REFERENCE &other) const
Return whether this reference refers to the same symbol instance (symbol and sheet) as another.
KIID m_symbolUuid
UUID of the symbol.
int GetUnit() const
LIB_SYMBOL * m_libPart
The source symbol from a library.
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.
const wxString GetPath() const
wxString GetRefNumber() const
int CompareValue(const SCH_REFERENCE &item) const
void Annotate()
Update the annotation of the symbol according the current object state.
A container for handling SCH_SHEET_PATH objects in a flattened hierarchy.
Handle access to a stack of flattened SCH_SHEET objects by way of a path for creating a flattened sch...
KIID_PATH Path() const
Get the sheet path as an KIID_PATH.
wxString PathAsString() const
Return the path of time stamps which do not changes even when editing sheet parameters.
Schematic symbol object.
Definition: sch_symbol.h:80
const LIB_ID & GetLibId() const
Definition: sch_symbol.h:178
int compare(const std::string &s) const
Definition: utf8.h:111
ERCE_T
ERC error codes.
Definition: erc_settings.h:37
This file contains miscellaneous commonly used macros and functions.
#define TO_UTF8(wxstring)
Convert a wxString to a UTF8 encoded C string for all wxWidgets build modes.
Definition: macros.h:96
std::function< void(ERCE_T aType, const wxString &aMsg, SCH_REFERENCE *aItemA, SCH_REFERENCE *aItemB)> ANNOTATION_ERROR_HANDLER
Define a standard error handler for annotation errors.
ANNOTATE_ORDER_T
Schematic annotation order options.
@ UNSORTED
Annotate by position of symbol in the schematic sheet object list.
@ SORT_BY_X_POSITION
Annotate by X position from left to right.
@ SORT_BY_Y_POSITION
Annotate by Y position from top to bottom.
ANNOTATE_SCOPE_T
Schematic annotation scope options.
@ ANNOTATE_SELECTION
Annotate the selection.
@ ANNOTATE_CURRENT_SHEET
Annotate the current sheet.
@ ANNOTATE_ALL
Annotate the full schematic.
ANNOTATE_ALGO_T
Schematic annotation type options.
@ SHEET_NUMBER_X_1000
Annotate using the first free reference number starting at the sheet number * 1000.
@ INCREMENTAL_BY_REF
Annotate incrementally using the first free reference number.
@ SHEET_NUMBER_X_100
Annotate using the first free reference number starting at the sheet number * 100.
Definition of the SCH_SHEET_PATH and SCH_SHEET_LIST classes for Eeschema.
std::map< wxString, SCH_REFERENCE_LIST > SCH_MULTI_UNIT_REFERENCE_MAP
Container to map reference designators for multi-unit parts.