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 <jean-pierre.charras@gipsa-lab.inpg.fr>
5  * Copyright (C) 1992-2011 Wayne Stambaugh <stambaughw@gmail.com>
6  * Copyright (C) 1992-2021 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 <sch_sheet_path.h>
33 #include <sch_symbol.h>
34 #include <sch_text.h>
35 #include <erc_settings.h>
36 
45 {
47  UTF8 m_ref; // it's private, use the accessors please
50  wxPoint m_symbolPos;
51  int m_unit;
53  wxString m_value;
55  wxString m_footprint;
57  bool m_isNew;
58  int m_sheetNum;
60  int m_numRef;
61  int m_flag;
62 
63  friend class SCH_REFERENCE_LIST;
64 
65 public:
66 
68  m_sheetPath()
69  {
71  m_libPart = NULL;
72  m_unit = 0;
73  m_isNew = false;
74  m_numRef = 0;
75  m_flag = 0;
76  m_sheetNum = 0;
77  }
78 
79  SCH_REFERENCE( SCH_COMPONENT* aSymbol, LIB_PART* aLibPart, const SCH_SHEET_PATH& aSheetPath );
80 
81  SCH_COMPONENT* GetSymbol() const { return m_rootSymbol; }
82 
83  LIB_PART* GetLibPart() const { return m_libPart; }
84 
85  const SCH_SHEET_PATH& GetSheetPath() const { return m_sheetPath; }
86 
88 
89  int GetUnit() const { return m_unit; }
90  void SetUnit( int aUnit ) { m_unit = aUnit; }
91 
92  const wxString GetValue() const { return m_value; }
93  void SetValue( const wxString& aValue ) { m_value = aValue; }
94 
95  const wxString GetFootprint() const { return m_footprint; }
96  void SetFootprint( const wxString& aFP ) { m_footprint = aFP; }
97 
98  void SetSheetNumber( int aSheetNumber ) { m_sheetNum = aSheetNumber; }
99 
100  const wxString GetPath() const
101  {
103  }
104 
108  void Annotate();
109 
117  void Split();
118 
119  void SetRef( const wxString& aReference ) { m_ref = aReference; }
120  wxString GetRef() const { return m_ref; }
121 
122  void SetRefStr( const std::string& aReference ) { m_ref = aReference; }
123  const char* GetRefStr() const { return m_ref.c_str(); }
124 
126  wxString GetFullRef()
127  {
128  if( GetSymbol()->GetUnitCount() > 1 )
129  return GetRef() + LIB_PART::SubReference( GetUnit() );
130  else
131  return GetRef();
132  }
133 
134  wxString GetRefNumber() const
135  {
136  wxString ref;
137 
138  if( m_numRef < 0 )
139  return wxT( "?" );
140 
141  // To avoid a risk of duplicate, for power symbols the ref number is 0nnn instead of nnn.
142  // Just because sometimes only power symbols are annotated
143  if( GetLibPart() && GetLibPart()->IsPower() )
144  ref = wxT( "0" );
145 
146  return ref << m_numRef;
147  }
148 
149  int CompareValue( const SCH_REFERENCE& item ) const
150  {
151  return m_value.Cmp( item.m_value );
152  }
153 
154  int CompareRef( const SCH_REFERENCE& item ) const
155  {
156  return m_ref.compare( item.m_ref );
157  }
158 
159  int CompareLibName( const SCH_REFERENCE& item ) const
160  {
163  }
164 
169  bool IsSameInstance( const SCH_REFERENCE& other ) const
170  {
171  // JEY TODO: should this be checking unit as well?
172  return GetSymbol() == other.GetSymbol()
173  && GetSheetPath().Path() == other.GetSheetPath().Path();
174  }
175 
177  {
178  return m_libPart->UnitsLocked();
179  }
180 };
181 
182 
186 typedef std::function<void( ERCE_T aType, const wxString& aMsg, SCH_REFERENCE* aItemA,
188 
189 
197 {
198 
199 private:
200  std::vector<SCH_REFERENCE> flatList;
201 
202 public:
204  {
205  }
206 
207  SCH_REFERENCE& operator[]( int aIndex )
208  {
209  return flatList[ aIndex ];
210  }
211 
212  void Clear()
213  {
214  flatList.clear();
215  }
216 
217  unsigned GetCount() const { return flatList.size(); }
218 
219  SCH_REFERENCE& GetItem( int aIdx ) { return flatList[aIdx]; }
220 
221  void AddItem( SCH_REFERENCE& aItem ) { flatList.push_back( aItem ); }
222 
228  void RemoveItem( unsigned int aIndex );
229 
230  /* Sort functions:
231  * Sort functions are used to sort symbols for annotation or BOM generation. Because
232  * sorting depends on what we want to do, there are many sort functions.
233  * Note:
234  * When creating BOM, symbols are fully annotated. References are something like U3,
235  * U5 or R4, R8. When annotating, some or all symbols are not annotated, i.e. ref is
236  * only U or R, with no number.
237  */
238 
247  {
248  for( unsigned ii = 0; ii < GetCount(); ii++ )
249  flatList[ii].Split();
250  }
251 
261  {
262  /* update the reference numbers */
263  for( unsigned ii = 0; ii < GetCount(); ii++ )
264  flatList[ii].Annotate();
265  }
266 
284  void Annotate( bool aUseSheetNum, int aSheetIntervalId, int aStartNumber,
285  SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap );
286 
301  int CheckAnnotation( ANNOTATION_ERROR_HANDLER aErrorHandler );
302 
317  {
318  sort( flatList.begin(), flatList.end(), sortByXPosition );
319  }
320 
335  {
336  sort( flatList.begin(), flatList.end(), sortByYPosition );
337  }
338 
345  {
346  sort( flatList.begin(), flatList.end(), sortByTimeStamp );
347  }
348 
364  {
365  sort( flatList.begin(), flatList.end(), sortByRefAndValue );
366  }
367 
379  {
380  sort( flatList.begin(), flatList.end(), sortByReferenceOnly );
381  }
382 
386  int FindRef( const wxString& aPath ) const;
387 
396  int FindUnit( size_t aIndex, int aUnit );
397 
404  int FindRefByPath( const wxString& aPath ) const;
405 
414  void GetRefsInUse( int aIndex, std::vector< int >& aIdList, int aMinRefId );
415 
423  int GetLastReference( int aIndex, int aMinValue );
424 
425 #if defined(DEBUG)
426  void Show( const char* aPrefix = "" )
427  {
428  printf( "%s\n", aPrefix );
429 
430  for( unsigned i=0; i < flatList.size(); ++i )
431  {
432  SCH_REFERENCE& schref = flatList[i];
433 
434  printf( " [%-2d] ref:%-8s num:%-3d lib_part:%s\n",
435  i,
436  schref.m_ref.c_str(),
437  schref.m_numRef,
438  TO_UTF8( schref.GetLibPart()->GetName() ) );
439  }
440  }
441 #endif
442 
447  static wxString Shorthand( std::vector<SCH_REFERENCE> aList );
448 
449  friend class BACK_ANNOTATION;
450 
451 private:
452  static bool sortByRefAndValue( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
453 
454  static bool sortByXPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
455 
456  static bool sortByYPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
457 
458  static bool sortByTimeStamp( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
459 
460  static bool sortByReferenceOnly( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
461 
474  int CreateFirstFreeRefId( std::vector<int>& aIdList, int aFirstValue );
475 
476  // Used for sorting static sortByTimeStamp function
477  friend class BACK_ANNOTATE;
478 };
479 
480 #endif // _SCH_REFERENCE_LIST_H_
An 8 bit string that is assuredly encoded in UTF8, and supplies special conversion support to and fro...
Definition: utf8.h:70
void SetSheetNumber(int aSheetNumber)
static bool sortByTimeStamp(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
void SortByYCoordinate()
Sort the list of references by Y position.
SCH_REFERENCE & GetItem(int aIdx)
int compare(const std::string &s) const
Definition: utf8.h:111
const UTF8 & GetLibItemName() const
Definition: lib_id.h:106
void RemoveItem(unsigned int aIndex)
Remove an item from the list of references.
wxString GetName() const override
Definition: lib_symbol.h:129
void Split()
Attempt to split the reference designator into a name (U) and number (1).
int FindRefByPath(const wxString &aPath) const
Search the list for a symbol with the given KIID path.
const SCH_SHEET_PATH & GetSheetPath() const
void SetUnit(int aUnit)
wxPoint m_symbolPos
The physical position of the symbol in schematic.
KIID_PATH Path() const
Get the sheet path as an KIID_PATH.
int m_sheetNum
The sheet number for the reference.
void AddItem(SCH_REFERENCE &aItem)
wxString AsString() const
Definition: kiid.cpp:213
wxString PathAsString() const
Return the path of time stamps which do not changes even when editing sheet parameters.
static wxString Shorthand(std::vector< SCH_REFERENCE > aList)
Return a shorthand string representing all the references in the list.
int GetUnit() const
const wxString GetPath() const
wxString GetRefNumber() const
void SortByRefAndValue()
Sort the list of references by value.
Container to create a flattened list of symbols because in a complex hierarchy, a symbol can be used ...
int FindRef(const wxString &aPath) const
Search the list for a symbol with a given reference.
void SetRefStr(const std::string &aReference)
const char * c_str() const
Definition: utf8.h:102
void GetRefsInUse(int aIndex, std::vector< int > &aIdList, int aMinRefId)
Add all the reference designator numbers greater than aMinRefId to aIdList skipping the reference at ...
int m_unit
The unit number for symbol with multiple parts.
wxString GetRef() const
#define TO_UTF8(wxstring)
Convert a wxString to a UTF8 encoded C string for all wxWidgets build modes.
Definition: macros.h:96
Definition: kiid.h:44
void UpdateAnnotation()
Update the symbol references for the schematic project (or the current sheet).
void SortByTimeStamp()
Sort the flat list by Time Stamp (sheet path + timestamp).
friend class BACK_ANNOTATION
#define NULL
void SortByXCoordinate()
Sort the list of references by X position.
int CompareValue(const SCH_REFERENCE &item) const
int CompareLibName(const SCH_REFERENCE &item) const
static bool sortByRefAndValue(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
bool m_isNew
True if not yet annotated.
wxString m_footprint
The footprint assigned.
void Annotate()
Update the annotation of the symbol according the the current object state.
KIID m_symbolUuid
UUID of the symbol.
Define a library symbol object.
Definition: lib_symbol.h:93
const wxString GetFootprint() const
void Annotate(bool aUseSheetNum, int aSheetIntervalId, int aStartNumber, SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap)
Set the reference designators in the list that have not been annotated.
int FindUnit(size_t aIndex, int aUnit)
Search the sorted list of symbols for a another symbol with the same reference and a given part unit.
SCH_SHEET_PATH & GetSheetPath()
static bool sortByYPosition(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
Handle access to a stack of flattened SCH_SHEET objects by way of a path for creating a flattened sch...
ERCE_T
ERC error codes.
Definition: erc_settings.h:36
wxString m_value
The symbol value.
static bool sortByReferenceOnly(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
std::map< wxString, SCH_REFERENCE_LIST > SCH_MULTI_UNIT_REFERENCE_MAP
Container to map reference designators for multi-unit parts.
SCH_COMPONENT * GetSymbol() const
const KIID m_Uuid
Definition: eda_item.h:524
unsigned GetCount() const
wxString GetFullRef()
int CompareRef(const SCH_REFERENCE &item) const
UTF8 m_ref
Symbol reference prefix, without number (for IC1, this is IC) )
int CheckAnnotation(ANNOTATION_ERROR_HANDLER aErrorHandler)
Check for annotations errors.
SCH_REFERENCE & operator[](int aIndex)
const char * GetRefStr() const
Return reference name with unit altogether.
SCH_SHEET_PATH m_sheetPath
The sheet path for this reference.
void SortByReferenceOnly()
Sort the list of references by reference.
void SplitReferences()
Attempt to split all reference designators into a name (U) and number (1).
int m_numRef
The numeric part of the reference designator.
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.
Back annotation algorithm class used to receive, check, and apply a NETLIST from Pcbnew.
Definition: backannotate.h:55
LIB_PART * GetLibPart() const
bool IsSameInstance(const SCH_REFERENCE &other) const
Return whether this reference refers to the same symbol instance (symbol and sheet) as another.
void SetFootprint(const wxString &aFP)
static wxString SubReference(int aUnit, bool aAddSeparator=true)
Definition: lib_symbol.cpp:447
Schematic symbol object.
Definition: sch_symbol.h:78
LIB_PART * m_libPart
The source symbol from a library.
int CreateFirstFreeRefId(std::vector< int > &aIdList, int aFirstValue)
Search for the first free reference number in aListId of reference numbers in use.
void SetRef(const wxString &aReference)
SCH_COMPONENT * m_rootSymbol
The symbol associated the reference object.
const wxString GetValue() const
void SetValue(const wxString &aValue)
std::vector< SCH_REFERENCE > flatList
int GetLastReference(int aIndex, int aMinValue)
Return the last used (greatest) reference number in the reference list for the prefix used by the sym...
Definition of the SCH_SHEET_PATH and SCH_SHEET_LIST classes for Eeschema.
const LIB_ID & GetLibId() const
Definition: sch_symbol.h:188
bool UnitsLocked() const
Check whether part units are interchangeable.
Definition: lib_symbol.h:237
A helper to define a symbol's reference designator in a schematic.
static bool sortByXPosition(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)