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-2023 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
115 const wxString GetPath() const
116 {
117 return m_sheetPath.PathAsString();
118 }
119
123 const wxString GetFullPath() const
124 {
126 }
127
131 void Annotate();
132
139 bool AlwaysAnnotate() const;
140
148 void Split();
149
155 bool IsSplitNeeded();
156
157 void SetRef( const wxString& aReference ) { m_ref = aReference; }
158 wxString GetRef() const { return m_ref; }
159
160 void SetRefStr( const std::string& aReference ) { m_ref = aReference; }
161 const char* GetRefStr() const { return m_ref.c_str(); }
162
164 wxString GetFullRef() const
165 {
166 if( GetSymbol()->GetUnitCount() > 1 )
168 else
169 return GetRef() + GetRefNumber();
170 }
171
172 wxString GetRefNumber() const
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 }
186
187 int CompareValue( const SCH_REFERENCE& item ) const
188 {
189 return m_value.Cmp( item.m_value );
190 }
191
192 int CompareRef( const SCH_REFERENCE& item ) const
193 {
194 return m_ref.CmpNoCase( item.m_ref );
195 }
196
197 int CompareLibName( const SCH_REFERENCE& item ) const
198 {
201 }
202
207 bool IsSameInstance( const SCH_REFERENCE& other ) const
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 }
215
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 }
223
224private:
225 friend class SCH_REFERENCE_LIST;
226
228 wxString m_ref; // it's private, use the accessors please
233 int m_unit;
235 wxString m_value;
236 wxString m_footprint;
238 bool m_isNew;
243};
244
245
249typedef std::function<void( ERCE_T aType, const wxString& aMsg, SCH_REFERENCE* aItemA,
251
252
261{
262public:
264 {
265 }
266
268 {
269 return m_flatList[ aIndex ];
270 }
271
272 const SCH_REFERENCE& operator[]( int aIndex ) const
273 {
274 return m_flatList[ aIndex ];
275 }
276
277 void Clear()
278 {
279 m_flatList.clear();
280 }
281
282 size_t GetCount() const { return m_flatList.size(); }
283
284 SCH_REFERENCE& GetItem( int aIdx ) { return m_flatList[aIdx]; }
285 const SCH_REFERENCE& GetItem( int aIdx ) const { return m_flatList[aIdx]; }
286
287 void AddItem( const SCH_REFERENCE& aItem ) { m_flatList.push_back( aItem ); }
288
294 void RemoveItem( unsigned int aIndex );
295
301 bool Contains( const SCH_REFERENCE& aItem ) const;
302
303 /* Sort functions:
304 * Sort functions are used to sort symbols for annotation or BOM generation. Because
305 * sorting depends on what we want to do, there are many sort functions.
306 * Note:
307 * When creating BOM, symbols are fully annotated. References are something like U3,
308 * U5 or R4, R8. When annotating, some or all symbols are not annotated, i.e. ref is
309 * only U or R, with no number.
310 */
311
320 {
321 for( unsigned ii = 0; ii < GetCount(); ii++ )
322 m_flatList[ii].Split();
323 }
324
331 {
332 for( unsigned ii = 0; ii < GetCount(); ii++ )
333 m_flatList[ii].m_isNew = true;
334 }
335
345 {
346 /* update the reference numbers */
347 for( unsigned ii = 0; ii < GetCount(); ii++ )
348 m_flatList[ii].Annotate();
349 }
350
365 void ReannotateByOptions( ANNOTATE_ORDER_T aSortOption,
366 ANNOTATE_ALGO_T aAlgoOption,
367 int aStartNumber,
368 const SCH_REFERENCE_LIST& aAdditionalRefs,
369 bool aStartAtCurrent,
370 SCH_SHEET_LIST* aHierarchy );
371
381 void ReannotateDuplicates( const SCH_REFERENCE_LIST& aAdditionalReferences );
382
398 void AnnotateByOptions( enum ANNOTATE_ORDER_T aSortOption,
399 enum ANNOTATE_ALGO_T aAlgoOption,
400 int aStartNumber,
401 SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap,
402 const SCH_REFERENCE_LIST& aAdditionalRefs,
403 bool aStartAtCurrent );
404
426 void Annotate( bool aUseSheetNum, int aSheetIntervalId, int aStartNumber,
427 SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap,
428 const SCH_REFERENCE_LIST& aAdditionalRefs, bool aStartAtCurrent = false );
429
442 int CheckAnnotation( ANNOTATION_ERROR_HANDLER aErrorHandler );
443
455 {
456 sort( m_flatList.begin(), m_flatList.end(), sortByXPosition );
457 }
458
470 {
471 sort( m_flatList.begin(), m_flatList.end(), sortByYPosition );
472 }
473
480 {
481 sort( m_flatList.begin(), m_flatList.end(), sortByTimeStamp );
482 }
483
496 {
497 sort( m_flatList.begin(), m_flatList.end(), sortByRefAndValue );
498 }
499
508 {
509 sort( m_flatList.begin(), m_flatList.end(), sortByReferenceOnly );
510 }
511
515 int FindRef( const wxString& aPath ) const;
516
526 int FindUnit( size_t aIndex, int aUnit, bool aIncludeNew = false ) const;
527
534 int FindRefByFullPath( const wxString& aFullPath ) const;
535
544 void GetRefsInUse( int aIndex, std::vector<int>& aIdList, int aMinRefId ) const;
545
552 std::vector<int> GetUnitsMatchingRef( const SCH_REFERENCE& aRef ) const;
553
562 int FindFirstUnusedReference( const SCH_REFERENCE& aRef, int aMinValue,
563 const std::vector<int>& aRequiredUnits ) const;
564
565 std::vector<SCH_SYMBOL_INSTANCE> GetSymbolInstances() const;
566
567#if defined(DEBUG)
568 void Show( const char* aPrefix = "" )
569 {
570 printf( "%s\n", aPrefix );
571
572 for( unsigned i=0; i < m_flatList.size(); ++i )
573 {
574 SCH_REFERENCE& schref = m_flatList[i];
575
576 printf( " [%-2d] ref:%-8s num:%-3d lib_part:%s\n",
577 i,
578 schref.m_ref.ToStdString().c_str(),
579 schref.m_numRef,
580 TO_UTF8( schref.GetLibPart()->GetName() ) );
581 }
582 }
583#endif
584
589 static wxString Shorthand( std::vector<SCH_REFERENCE> aList );
590
591 friend class BACK_ANNOTATION;
592
593private:
594 static bool sortByRefAndValue( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
595
596 static bool sortByXPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
597
598 static bool sortByYPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
599
600 static bool sortByTimeStamp( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
601
602 static bool sortByReferenceOnly( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
603
616 static int createFirstFreeRefId( std::vector<int>& aIdList, int aFirstValue );
617
618 // Used for sorting static sortByTimeStamp function
619 friend class BACK_ANNOTATE;
620
621 std::vector<SCH_REFERENCE> m_flatList;
622};
623
624#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:48
wxString AsString() const
Definition: kiid.cpp:257
const UTF8 & GetLibItemName() const
Definition: lib_id.h:102
Define a library symbol object.
Definition: lib_symbol.h:99
bool UnitsLocked() const
Check whether symbol units are interchangeable.
Definition: lib_symbol.h:258
wxString GetName() const override
Definition: lib_symbol.h:138
static wxString SubReference(int aUnit, bool aAddSeparator=true)
Definition: lib_symbol.cpp:584
Container to create a flattened list of symbols because in a complex hierarchy, a symbol can be used ...
void SortByReferenceOnly()
Sort the list of references by reference.
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)
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,...
std::vector< SCH_REFERENCE > m_flatList
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.
int FindRefByFullPath(const wxString &aFullPath) const
Search the list for a symbol with the given KIID path (as string).
void RemoveAnnotation()
Treat all symbols in this list as non-annotated.
std::vector< SCH_SYMBOL_INSTANCE > GetSymbolInstances() const
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)
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
const wxString GetFullPath() const
bool AlwaysAnnotate() const
Verify the reference should always be automatically annotated.
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:81
const LIB_ID & GetLibId() const
Definition: sch_symbol.h:175
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.