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) 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 <macros.h>
33 #include <sch_sheet_path.h>
34 #include <sch_symbol.h>
35 #include <sch_text.h>
36 #include <erc_settings.h>
37 
46 {
47 public:
49  m_sheetPath()
50  {
52  m_libPart = NULL;
53  m_unit = 0;
54  m_isNew = false;
55  m_numRef = 0;
56  m_flag = 0;
57  m_sheetNum = 0;
58  }
59 
60  SCH_REFERENCE( SCH_SYMBOL* aSymbol, LIB_SYMBOL* aLibSymbol, const SCH_SHEET_PATH& aSheetPath );
61 
62  SCH_SYMBOL* GetSymbol() const { return m_rootSymbol; }
63 
64  LIB_SYMBOL* GetLibPart() const { return m_libPart; }
65 
66  const SCH_SHEET_PATH& GetSheetPath() const { return m_sheetPath; }
67 
69 
70  int GetUnit() const { return m_unit; }
71  void SetUnit( int aUnit ) { m_unit = aUnit; }
72 
73  const wxString GetValue() const { return m_value; }
74  void SetValue( const wxString& aValue ) { m_value = aValue; }
75 
76  const wxString GetFootprint() const { return m_footprint; }
77  void SetFootprint( const wxString& aFP ) { m_footprint = aFP; }
78 
79  void SetSheetNumber( int aSheetNumber ) { m_sheetNum = aSheetNumber; }
80 
81  const wxString GetPath() const
82  {
84  }
85 
89  void Annotate();
90 
98  void Split();
99 
100  void SetRef( const wxString& aReference ) { m_ref = aReference; }
101  wxString GetRef() const { return m_ref; }
102 
103  void SetRefStr( const std::string& aReference ) { m_ref = aReference; }
104  const char* GetRefStr() const { return m_ref.c_str(); }
105 
107  wxString GetFullRef()
108  {
109  if( GetSymbol()->GetUnitCount() > 1 )
110  return GetRef() + LIB_SYMBOL::SubReference( GetUnit() );
111  else
112  return GetRef();
113  }
114 
115  wxString GetRefNumber() const
116  {
117  wxString ref;
118 
119  if( m_numRef < 0 )
120  return wxT( "?" );
121 
122  // To avoid a risk of duplicate, for power symbols the ref number is 0nnn instead of nnn.
123  // Just because sometimes only power symbols are annotated
124  if( GetLibPart() && GetLibPart()->IsPower() )
125  ref = wxT( "0" );
126 
127  return ref << m_numRef;
128  }
129 
130  int CompareValue( const SCH_REFERENCE& item ) const
131  {
132  return m_value.Cmp( item.m_value );
133  }
134 
135  int CompareRef( const SCH_REFERENCE& item ) const
136  {
137  return m_ref.compare( item.m_ref );
138  }
139 
140  int CompareLibName( const SCH_REFERENCE& item ) const
141  {
144  }
145 
150  bool IsSameInstance( const SCH_REFERENCE& other ) const
151  {
152  // Only compare symbol and path.
153  // We may have changed the unit number or the designator but
154  // can still be referencing the same instance.
155  return GetSymbol() == other.GetSymbol()
156  && GetSheetPath().Path() == other.GetSheetPath().Path();
157  }
158 
160  {
161  if( m_libPart )
162  return m_libPart->UnitsLocked();
163  else
164  return true; // Assume units locked when we don't have a library
165  }
166 
167 private:
168  friend class SCH_REFERENCE_LIST;
169 
171  UTF8 m_ref; // it's private, use the accessors please
174  wxPoint m_symbolPos;
175  int m_unit;
177  wxString m_value;
179  wxString m_footprint;
181  bool m_isNew;
184  int m_numRef;
185  int m_flag;
186 };
187 
188 
192 typedef std::function<void( ERCE_T aType, const wxString& aMsg, SCH_REFERENCE* aItemA,
194 
195 
204 {
205 
206 private:
207  std::vector<SCH_REFERENCE> flatList;
208 
209 public:
211  {
212  }
213 
214  SCH_REFERENCE& operator[]( int aIndex )
215  {
216  return flatList[ aIndex ];
217  }
218 
219  const SCH_REFERENCE& operator[]( int aIndex ) const
220  {
221  return flatList[ aIndex ];
222  }
223 
224  void Clear()
225  {
226  flatList.clear();
227  }
228 
229  size_t GetCount() const { return flatList.size(); }
230 
231  SCH_REFERENCE& GetItem( int aIdx ) { return flatList[aIdx]; }
232  const SCH_REFERENCE& GetItem( int aIdx ) const { return flatList[aIdx]; }
233 
234  void AddItem( const SCH_REFERENCE& aItem ) { flatList.push_back( aItem ); }
235 
241  void RemoveItem( unsigned int aIndex );
242 
248  bool Contains( const SCH_REFERENCE& aItem );
249 
250  /* Sort functions:
251  * Sort functions are used to sort symbols for annotation or BOM generation. Because
252  * sorting depends on what we want to do, there are many sort functions.
253  * Note:
254  * When creating BOM, symbols are fully annotated. References are something like U3,
255  * U5 or R4, R8. When annotating, some or all symbols are not annotated, i.e. ref is
256  * only U or R, with no number.
257  */
258 
267  {
268  for( unsigned ii = 0; ii < GetCount(); ii++ )
269  flatList[ii].Split();
270  }
271 
281  {
282  /* update the reference numbers */
283  for( unsigned ii = 0; ii < GetCount(); ii++ )
284  flatList[ii].Annotate();
285  }
286 
293  void ReannotateDuplicates( const SCH_REFERENCE_LIST& aAdditionalReferences );
294 
316  void Annotate( bool aUseSheetNum, int aSheetIntervalId, int aStartNumber,
317  SCH_MULTI_UNIT_REFERENCE_MAP aLockedUnitMap,
318  const SCH_REFERENCE_LIST& aAdditionalRefs, bool aStartAtCurrent = false );
319 
332  int CheckAnnotation( ANNOTATION_ERROR_HANDLER aErrorHandler );
333 
345  {
346  sort( flatList.begin(), flatList.end(), sortByXPosition );
347  }
348 
360  {
361  sort( flatList.begin(), flatList.end(), sortByYPosition );
362  }
363 
370  {
371  sort( flatList.begin(), flatList.end(), sortByTimeStamp );
372  }
373 
386  {
387  sort( flatList.begin(), flatList.end(), sortByRefAndValue );
388  }
389 
398  {
399  sort( flatList.begin(), flatList.end(), sortByReferenceOnly );
400  }
401 
405  int FindRef( const wxString& aPath ) const;
406 
415  int FindUnit( size_t aIndex, int aUnit ) const;
416 
423  int FindRefByPath( const wxString& aPath ) const;
424 
433  void GetRefsInUse( int aIndex, std::vector< int >& aIdList, int aMinRefId ) const;
434 
442  int GetLastReference( int aIndex, int aMinValue ) const;
443 
444  std::vector<SYMBOL_INSTANCE_REFERENCE> GetSymbolInstances() const;
445 
446 #if defined(DEBUG)
447  void Show( const char* aPrefix = "" )
448  {
449  printf( "%s\n", aPrefix );
450 
451  for( unsigned i=0; i < flatList.size(); ++i )
452  {
453  SCH_REFERENCE& schref = flatList[i];
454 
455  printf( " [%-2d] ref:%-8s num:%-3d lib_part:%s\n",
456  i,
457  schref.m_ref.c_str(),
458  schref.m_numRef,
459  TO_UTF8( schref.GetLibPart()->GetName() ) );
460  }
461  }
462 #endif
463 
468  static wxString Shorthand( std::vector<SCH_REFERENCE> aList );
469 
470  friend class BACK_ANNOTATION;
471 
472 private:
473  static bool sortByRefAndValue( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
474 
475  static bool sortByXPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
476 
477  static bool sortByYPosition( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
478 
479  static bool sortByTimeStamp( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
480 
481  static bool sortByReferenceOnly( const SCH_REFERENCE& item1, const SCH_REFERENCE& item2 );
482 
495  int CreateFirstFreeRefId( std::vector<int>& aIdList, int aFirstValue );
496 
497  // Used for sorting static sortByTimeStamp function
498  friend class BACK_ANNOTATE;
499 };
500 
501 #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
const SCH_REFERENCE & operator[](int aIndex) const
void RemoveItem(unsigned int aIndex)
Remove an item from the list of references.
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.
LIB_SYMBOL * m_libPart
The source symbol from a library.
const SCH_SHEET_PATH & GetSheetPath() const
void SetUnit(int aUnit)
wxString GetName() const override
Definition: lib_symbol.h:133
void ReannotateDuplicates(const SCH_REFERENCE_LIST &aAdditionalReferences)
Replace any duplicate reference designators with the next available number after the present number.
wxPoint m_symbolPos
The physical position of the symbol in schematic used to annotate by X or Y position.
KIID_PATH Path() const
Get the sheet path as an KIID_PATH.
int m_sheetNum
The sheet number for the reference.
std::vector< SYMBOL_INSTANCE_REFERENCE > GetSymbolInstances() const
wxString AsString() const
Definition: kiid.cpp:218
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.
void AddItem(const SCH_REFERENCE &aItem)
int GetUnit() const
static wxString SubReference(int aUnit, bool aAddSeparator=true)
Definition: lib_symbol.cpp:447
const wxString GetPath() const
SCH_SYMBOL * GetSymbol() const
wxString GetRefNumber() const
Define a library symbol object.
Definition: lib_symbol.h:96
int GetLastReference(int aIndex, int aMinValue) const
Return the last used (greatest) reference number in the reference list for the prefix used by the sym...
const SCH_REFERENCE & GetItem(int aIdx) 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.
This file contains miscellaneous commonly used macros and functions.
void SetRefStr(const std::string &aReference)
const char * c_str() const
Definition: utf8.h:102
int FindUnit(size_t aIndex, int aUnit) const
Search the sorted list of symbols for a another symbol with the same reference and a given part unit.
int m_unit
The unit number for symbol with multiple parts per package.
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 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 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 current object state.
KIID m_symbolUuid
UUID of the symbol.
size_t GetCount() const
const wxString GetFootprint() const
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
bool Contains(const SCH_REFERENCE &aItem)
Return true if aItem exists in this list.
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.
bool UnitsLocked() const
Check whether symbol units are interchangeable.
Definition: lib_symbol.h:241
const KIID m_Uuid
Definition: eda_item.h:475
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)
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.
const char * GetRefStr() const
Return reference name with unit altogether.
Schematic symbol object.
Definition: sch_symbol.h:78
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
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)
int CreateFirstFreeRefId(std::vector< int > &aIdList, int aFirstValue)
Search for the first free reference number in aListId of reference numbers in use.
LIB_SYMBOL * GetLibPart() const
void SetRef(const wxString &aReference)
const wxString GetValue() const
void SetValue(const wxString &aValue)
std::vector< SCH_REFERENCE > flatList
Definition of the SCH_SHEET_PATH and SCH_SHEET_LIST classes for Eeschema.
SCH_SYMBOL * m_rootSymbol
The symbol associated the reference object.
A helper to define a symbol's reference designator in a schematic.
static bool sortByXPosition(const SCH_REFERENCE &item1, const SCH_REFERENCE &item2)
const LIB_ID & GetLibId() const
Definition: sch_symbol.h:147