kicad/eeschema/sch_symbol.h

813 lines
30 KiB
C
Raw Normal View History

/*
* This program source code file is part of KiCad, a free EDA CAD application.
*
* Copyright (C) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
* Copyright (C) 2014 Dick Hollenbeck, dick@softplc.com
* Copyright (C) 2015 Wayne Stambaugh <stambaughw@gmail.com>
* Copyright (C) 2022 CERN
* Copyright (C) 1992-2023 KiCad Developers, see AUTHORS.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, you may find one here:
* http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
* or you may search the http://www.gnu.org website for the version 2 license,
* or you may write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
*/
2021-06-10 14:10:55 +00:00
#ifndef __SYMBOL_H__
#define __SYMBOL_H__
2007-05-06 16:03:28 +00:00
#include <eda_item.h>
#include <core/typeinfo.h>
#include <layer_ids.h>
#include <lib_id.h>
#include <widgets/msgpanel.h>
2007-05-06 16:03:28 +00:00
#include <memory>
#include <string>
#include <unordered_map>
#include <vector>
#include <wx/arrstr.h>
#include <wx/chartype.h>
#include <wx/fdrepdlg.h>
#include <wx/gdicmn.h>
#include <wx/string.h>
#include <sch_field.h>
#include <sch_item.h>
#include <sch_pin.h>
#include <sch_sheet_path.h> // SCH_SYMBOL_INSTANCE
#include <symbol_lib_table.h>
#include <transform.h>
2020-11-07 14:31:50 +00:00
struct PICKED_SYMBOL;
class KIID_PATH;
class SCH_SCREEN;
class LIB_ITEM;
class LIB_PIN;
2021-06-10 18:51:46 +00:00
class LIB_SYMBOL;
class NETLIST_OBJECT_LIST;
class SYMBOL_LIB;
class SYMBOL_LIBS;
class EE_COLLECTOR;
class SCH_SCREEN;
class SYMBOL_LIB_TABLE;
/// A container for several SCH_FIELD items
typedef std::vector<SCH_FIELD> SCH_FIELDS;
2021-06-10 18:51:46 +00:00
typedef std::weak_ptr<LIB_SYMBOL> PART_REF;
extern std::string toUTFTildaText( const wxString& txt );
2008-03-20 01:50:21 +00:00
/**
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
* Schematic symbol object.
*/
2021-06-10 14:10:55 +00:00
class SCH_SYMBOL : public SCH_ITEM
2007-05-06 16:03:28 +00:00
{
public:
SCH_SYMBOL();
/**
2021-03-25 21:13:01 +00:00
* Create schematic symbol from library symbol object.
*
* @param aSymbol is the library symbol to create schematic symbol from.
2021-03-25 21:13:01 +00:00
* @param aLibId is the #LIB_ID of alias to create.
* @param aSheet is the schematic sheet the symbol is place into.
* @param aUnit is unit for symbols that have multiple parts per package.
* @param aConvert is the alternate body style for the schematic symbols.
* @param aPosition is the position of the symbol.
*/
2021-06-10 18:51:46 +00:00
SCH_SYMBOL( const LIB_SYMBOL& aSymbol, const LIB_ID& aLibId, const SCH_SHEET_PATH* aSheet,
int aUnit, int aConvert = 0, const VECTOR2I& aPosition = VECTOR2I( 0, 0 ),
EDA_ITEM* aParent = nullptr );
2021-06-10 14:10:55 +00:00
2021-06-10 18:51:46 +00:00
SCH_SYMBOL( const LIB_SYMBOL& aSymbol, const SCH_SHEET_PATH* aSheet, const PICKED_SYMBOL& aSel,
const VECTOR2I& aPosition = VECTOR2I( 0, 0 ), EDA_ITEM* aParent = nullptr );
/**
2021-03-25 21:13:01 +00:00
* Clone \a aSymbol into a new schematic symbol object.
*
* All fields are copied as is except for the linked list management pointers
* which are set to NULL, and the SCH_FIELD's m_Parent pointers which are set
* to the new object.
*
2021-03-25 21:13:01 +00:00
* @param aSymbol is the schematic symbol to clone.
*/
2021-06-10 14:10:55 +00:00
SCH_SYMBOL( const SCH_SYMBOL& aSymbol );
2021-06-10 14:10:55 +00:00
~SCH_SYMBOL() { }
2008-02-26 19:19:54 +00:00
static inline bool ClassOf( const EDA_ITEM* aItem )
{
2021-06-10 14:10:55 +00:00
return aItem && SCH_SYMBOL_T == aItem->Type();
}
2016-09-25 17:06:49 +00:00
wxString GetClass() const override
{
2021-06-10 14:10:55 +00:00
return wxT( "SCH_SYMBOL" );
}
/**
* Check to see if the library symbol is set to the dummy library symbol.
*
* When the library symbol is missing (which technically should not happen now that the
* library symbols are cached in the schematic file), a dummy library symbol is substituted
* for the missing symbol as an indicator that something is amiss. The dummy symbol cannot
* be edited so a check for this symbol must be performed before attempting to edit the
* library symbol with the library editor or it will crash KiCad.
*
* @see dummy()
*
* @return true if the library symbol is missing or false if it is valid.
*/
bool IsMissingLibSymbol() const;
const std::vector<SCH_SYMBOL_INSTANCE>& GetInstances() const
{
return m_instanceReferences;
}
bool GetInstance( SCH_SYMBOL_INSTANCE& aInstance,
2022-12-25 16:04:45 +00:00
const KIID_PATH& aSheetPath, bool aTestFromEnd = false ) const;
void RemoveInstance( const SCH_SHEET_PATH& aInstancePath );
void RemoveInstance( const KIID_PATH& aInstancePath );
void SortInstances( bool ( *aSortFunction )( const SCH_SYMBOL_INSTANCE& aLhs,
const SCH_SYMBOL_INSTANCE& aRhs ) );
void ViewGetLayers( int aLayers[], int& aCount ) const override;
/**
* Return true for items which are moved with the anchor point at mouse cursor
* and false for items moved with no reference to anchor.
*
* Usually return true for small items (labels, junctions) and false for items which can
2021-03-25 21:13:01 +00:00
* be large (hierarchical sheets, symbols).
*
2021-03-25 21:13:01 +00:00
* @note We used to try and be smart about this and return false for symbols in case
* they are big. However, this annoyed some users and we now have a preference which
* controls warping on move in general, so this was switched to true for symbols.
*
* @note We now use this to keep poorly-formed symbols from getting dragged off-grid. If
* the symbol contains off-grid pins we will not allow it to be moved from its anchor.
*/
bool IsMovableFromAnchorPoint() const override;
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
void SetLibId( const LIB_ID& aName );
2020-12-20 18:50:45 +00:00
const LIB_ID& GetLibId() const { return m_lib_id; }
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
/**
* The name of the symbol in the schematic library symbol list.
*
* @note See #SCH_SCREEN::m_libSymbols
*
* The name of the schematic symbol list entry can vary from the item name in the #LIB_ID
* object because the library symbol may have changed so a new name has to be generated
* but the original symbol library link has to be preserved in order to update it from
* the library at some point in the future. If this name is empty, then the library item
* name from #LIB_ID is used.
*/
void SetSchSymbolLibraryName( const wxString& aName ) { m_schLibSymbolName = aName; }
wxString GetSchSymbolLibraryName() const;
bool UseLibIdLookup() const { return m_schLibSymbolName.IsEmpty(); }
std::unique_ptr< LIB_SYMBOL >& GetLibSymbolRef() { return m_part; }
const std::unique_ptr< LIB_SYMBOL >& GetLibSymbolRef() const { return m_part; }
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
/**
* Set this schematic symbol library symbol reference to \a aLibSymbol
*
* The schematic symbol object owns \a aLibSymbol and the pin list will be updated
2021-06-10 18:51:46 +00:00
* accordingly. The #LIB_SYMBOL object can be null to clear the library symbol link
* as well as the pin map. If the #LIB_SYMBOL object is not null, it must be a root
* symbol. Otherwise an assertion will be raised in debug builds and the library
* symbol will be cleared. The new file format will no longer require a cache
* library so all library symbols must be valid.
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
*
* @note This is the only way to publicly set the library symbol for a schematic
2021-06-10 18:51:46 +00:00
* symbol except for the ctors that take a LIB_SYMBOL reference. All previous
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
* public resolvers have been deprecated.
*
* @param aLibSymbol is the library symbol to associate with this schematic symbol.
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
*/
2021-06-10 18:51:46 +00:00
void SetLibSymbol( LIB_SYMBOL* aLibSymbol );
Make the new schematic and symbol library file formats the default. This is a very large and potentially disruptive change so this will be an unusually long and detailed commit message. The new file formats are now the default in both the schematic and symbol library editors. Existing symbol libraries will be saved in their current format until new features are added to library symbols. Once this happens, both the legacy schematic and symbol file formats will be no longer be savable and existing libraries will have to be converted. Saving to the legacy file formats is still available for round robin testing and should not be used for normal editing. When loading the legacy schematic file, it is imperative that the schematic library symbols are rescued and/or remapped to valid library identifiers. Otherwise, there will be no way to link to the original library symbol and the user will be required manually set the library identifier. The cached symbol will be saved in the schematic file so the last library symbol in the cache will still be used but there will be no way to update it from the original library. The next save after loading a legacy schematic file will be converted to the s-expression file format. Schematics with hierarchical sheets will automatically have all sheet file name extensions changed to .kicad_sym and saved to the new format as well. Appending schematics requires that the schematic to append has already been converted to the new file format. This is required to ensure that library symbols are guaranteed to be valid for the appended schematic. The schematic symbol library symbol link resolution has been moved out of the SCH_COMPONENT object and move into the SCH_SCREEN object that owns the symbol. This was done to ensure that there is a single place where the library symbol links get resolved rather than the dozen or so different code paths that previously existed. It also removes the necessity of the SCH_COMPONENT object of requiring any knowledge of the symbol library table and/or the cache library. When opening an s-expression schematic, the legacy cache library is not loaded so any library symbols not rescued cannot be loaded. Broken library symbol links will have to be manually resolved by adding the cache library to the symbol library table and changing the links in the schematic symbol. Now that the library symbols are embedded in the schematic file, the SCH_SCREEN object maintains the list of library symbols for the schematic automatically. No external manipulation of this library cache should ever occur. ADDED: S-expression schematic and symbol library file formats.
2020-04-16 16:43:50 +00:00
/**
* @return the associated LIB_SYMBOL's description field (or wxEmptyString).
*/
wxString GetDescription() const;
/**
* @return the associated LIB_SYMBOL's keywords field (or wxEmptyString).
*/
wxString GetKeyWords() const;
/**
* Return the documentation text for the given part alias
*/
wxString GetDatasheet() const;
int GetUnit() const { return m_unit; }
/**
* Updates the cache of SCH_PIN objects for each pin
*/
void UpdatePins();
/**
* Change the unit number to \a aUnit
*
* This has meaning only for symbols made up of multiple units per package.
*
* @note This also set the modified flag bit
*
* @param aUnit is the new unit to select.
*/
void SetUnit( int aUnit );
/**
* Return true if the given unit \a aUnit has a display name set.
*
* @return true if the display name of a unit is set, otherwise false.
*/
bool HasUnitDisplayName( int aUnit );
/**
* Return the display name for a given unit \a aUnit.
*
* @return the display name of a unit if set, or the ordinal name of the unit otherwise.
*/
wxString GetUnitDisplayName( int aUnit );
/**
* Change the unit number to \a aUnit without setting any internal flags.
* This has meaning only for symbols made up of multiple units per package.
*
* @note This also set the modified flag bit
*
* @param aUnit is the new unit to select.
*/
void UpdateUnit( int aUnit );
int GetConvert() const { return m_convert; }
void SetConvert( int aConvert );
wxString GetPrefix() const { return m_prefix; }
void SetPrefix( const wxString& aPrefix ) { m_prefix = aPrefix; }
/**
* Set the prefix based on the current reference designator.
*/
void UpdatePrefix();
wxString SubReference( int aUnit, bool aAddSeparator = true ) const;
2020-12-20 18:44:13 +00:00
TRANSFORM& GetTransform() { return m_transform; }
const TRANSFORM& GetTransform() const { return m_transform; }
void SetTransform( const TRANSFORM& aTransform );
2008-04-15 19:38:19 +00:00
/**
* Return the number of units per package of the symbol.
*
* @return the number of units per package or zero if the library entry cannot be found.
*/
int GetUnitCount() const;
/**
* Compute the new transform matrix based on \a aOrientation for the symbol which is
* applied to the current transform.
*
* @param aOrientation is the orientation to apply to the transform.
*/
void SetOrientation( int aOrientation );
2010-11-12 15:17:10 +00:00
/**
* Get the display symbol orientation.
*
* Because there are different ways to have a given orientation/mirror,
* the orientation/mirror is not necessary what the user does. For example:
* a mirrorV then a mirrorH returns no mirror but a rotate. This function finds
2021-06-10 14:10:55 +00:00
* a rotation and a mirror value #SYM_MIRROR_X because this is the first mirror
* option tested. This can differs from the orientation made by an user. A
2021-06-10 14:10:55 +00:00
* #SYM_MIRROR_Y is returned as a #SYM_MIRROR_X with an orientation 180 because
* they are equivalent.
*
2021-06-10 14:10:55 +00:00
* @sa SYMBOL_ORIENTATION_T
*
* @return the orientation and mirror of the symbol.
*/
int GetOrientation() const;
/**
* Return the list of system text vars & fields for this symbol.
*/
void GetContextualTextVars( wxArrayString* aVars ) const;
/**
2021-03-25 21:13:01 +00:00
* Resolve any references to system tokens supported by the symbol.
*
* @param aDepth a counter to limit recursion and circular references.
*/
bool ResolveTextVar( const SCH_SHEET_PATH* aPath, wxString* token, int aDepth = 0 ) const;
void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;
2008-04-21 06:34:56 +00:00
/**
2021-03-25 21:13:01 +00:00
* Clear exiting symbol annotation.
*
* For example, IC23 would be changed to IC? and unit number would be reset.
*
* @param aSheetPath is the hierarchical path of the symbol to clear or remove all
* annotations for this symbol if NULL.
* @param[in] aResetPrefix The annotation prefix ('R', 'U', etc.) should be reset to the
* symbol library prefix.
2008-04-21 06:34:56 +00:00
*/
void ClearAnnotation( const SCH_SHEET_PATH* aSheetPath, bool aResetPrefix );
2008-04-21 06:34:56 +00:00
/**
* Add an instance to the alternate references list (m_instanceReferences), if this entry
* does not already exist.
2021-03-25 21:13:01 +00:00
*
* Do nothing if already exists. In symbol lists shared by more than one sheet path, an
* entry for each sheet path must exist to manage references.
*
* @param aSheetPath is the candidate sheet path of the sheet containing the symbol not the
* full symbol sheet path.
* @return false if the alternate reference was existing, true if added.
*/
bool AddSheetPathReferenceEntryIfMissing( const KIID_PATH& aSheetPath );
2022-08-31 09:15:42 +00:00
const BOX2I GetBoundingBox() const override;
/**
* Return a bounding box for the symbol body but not the pins or fields.
*/
2022-08-30 23:28:18 +00:00
BOX2I GetBodyBoundingBox() const;
/**
* Return a bounding box for the symbol body and pins but not the fields.
*/
2022-08-31 09:15:42 +00:00
BOX2I GetBodyAndPinsBoundingBox() const;
//-----<Fields>-----------------------------------------------------------
/**
2021-03-25 21:13:01 +00:00
* Return a mandatory field in this symbol.
*
2021-03-25 21:13:01 +00:00
* @note If you need to fetch a user field, use GetFieldById.
*
* @param aFieldType is one of the mandatory field types (REFERENCE_FIELD, VALUE_FIELD, etc.).
* @return is the field at \a aFieldType or NULL if the field does not exist.
*/
SCH_FIELD* GetField( MANDATORY_FIELD_T aFieldType );
const SCH_FIELD* GetField( MANDATORY_FIELD_T aFieldNdx ) const;
/**
2021-03-25 21:13:01 +00:00
* Return a field in this symbol.
*
* @param aFieldId is the id of the field requested. Note that this id ONLY SOMETIMES equates
2021-03-25 21:13:01 +00:00
* to the field's position in the vector.
* @return is the field at \a aFieldType or NULL if the field does not exist.
*/
SCH_FIELD* GetFieldById( int aFieldId );
2007-09-20 21:06:49 +00:00
/**
* Return a field in this symbol.
*
* @param aFieldName is the name of the field
*
* @return is the field with \a aFieldName or NULL if the field does not exist.
*/
SCH_FIELD* GetFieldByName( const wxString& aFieldName );
const SCH_FIELD* GetFieldByName( const wxString& aFieldName ) const;
/**
2021-03-25 21:13:01 +00:00
* Populate a std::vector with SCH_FIELDs.
*
* @param aVector is the vector to populate.
* @param aVisibleOnly is used to add only the fields that are visible and contain text.
*/
void GetFields( std::vector<SCH_FIELD*>& aVector, bool aVisibleOnly );
/**
2021-03-25 21:13:01 +00:00
* Return a vector of fields from the symbol
*/
2020-11-16 13:15:54 +00:00
std::vector<SCH_FIELD>& GetFields() { return m_fields; }
const std::vector<SCH_FIELD>& GetFields() const { return m_fields; }
2007-09-20 21:06:49 +00:00
/**
* Add a field to the symbol.
*
* @param aField is the field to add to this symbol.
*
* @return the newly inserted field.
*/
SCH_FIELD* AddField( const SCH_FIELD& aField );
/**
2021-03-25 21:13:01 +00:00
* Remove a user field from the symbol.
* @param aFieldName is the user fieldName to remove. Attempts to remove a mandatory
* field or a non-existant field are silently ignored.
*/
void RemoveField( const wxString& aFieldName );
void RemoveField( SCH_FIELD* aField ) { RemoveField( aField->GetName() ); }
/**
* Search for a #SCH_FIELD with \a aFieldName
*
* @param aFieldName is the name of the field to find.
* @param aIncludeDefaultFields searches the library symbol default fields if true.
* @param aCaseInsensitive ignore the filed name case if true.
*
* @return the field if found or NULL if the field was not found.
2007-09-20 21:06:49 +00:00
*/
SCH_FIELD* FindField( const wxString& aFieldName, bool aIncludeDefaultFields = true,
bool aCaseInsensitive = false );
2007-09-20 21:06:49 +00:00
const wxString GetValueFieldText( bool aResolve, const SCH_SHEET_PATH* aPath,
bool aAllowExtraText ) const;
void SetValueFieldText( const wxString& aValue );
const wxString GetFootprintFieldText( bool aResolve, const SCH_SHEET_PATH* aPath,
bool aAllowExtraText ) const;
void SetFootprintFieldText( const wxString& aFootprint );
/**
2021-03-25 21:13:01 +00:00
* Restore fields to the original library values.
*
* @param aUpdateStyle selects whether fields should update the position and text attributes.
* @param aUpdateRef selects whether the reference field should be updated.
* @param aUpdateOtherFields selects whether non-reference fields should be updated.
* @param aResetRef selects whether the reference should be reset to the library value.
* @param aResetOtherFields selects whether non-reference fields should be reset to library
* values.
*/
void UpdateFields( const SCH_SHEET_PATH* aPath, bool aUpdateStyle, bool aUpdateRef,
bool aUpdateOtherFields, bool aResetRef, bool aResetOtherFields );
/**
* Return the number of fields in this symbol.
*/
2020-11-16 13:15:54 +00:00
int GetFieldCount() const { return (int)m_fields.size(); }
2008-02-26 19:19:54 +00:00
/**
2021-03-25 21:13:01 +00:00
* Automatically orient all the fields in the symbol.
*
* @param aScreen is the SCH_SCREEN associated with the current instance of the
2021-03-25 21:13:01 +00:00
* symbol. This can be NULL when aManual is false.
* @param aManual should be true if the autoplace was manually initiated (e.g. by a hotkey
2021-03-25 21:13:01 +00:00
* or a menu item). Some more 'intelligent' routines will be used that would be
* annoying if done automatically during moves.
*/
2020-03-06 20:02:58 +00:00
void AutoplaceFields( SCH_SCREEN* aScreen, bool aManual ) override;
void RunOnChildren( const std::function<void( SCH_ITEM* )>& aFunction ) override;
//-----</Fields>----------------------------------------------------------
/**
* Find a symbol pin by number.
*
* @param number is the number of the pin to find.
* @return Pin object if found, otherwise NULL.
*/
2020-12-20 18:44:13 +00:00
SCH_PIN* GetPin( const wxString& number ) const;
/**
* Populate a vector with all the pins from the library object.
*
* @param aPinsList is the list to populate with all of the pins.
*/
2020-12-20 18:44:13 +00:00
void GetLibPins( std::vector<LIB_PIN*>& aPinsList ) const;
/**
* @return a list of pin pointers for all units / converts. Used primarily for SPICE where
* we want to treat all units together as a single SPICE element.
*/
std::vector<LIB_PIN*> GetAllLibPins() const;
/**
* @return a count of pins for all units.
*/
size_t GetFullPinCount() { return m_part ? m_part->GetPinCount() : 0; }
/**
* @return the SCH_PIN associated with a particular LIB_PIN.
*/
SCH_PIN* GetPin( LIB_PIN* aLibPin ) const;
/**
2021-03-25 21:13:01 +00:00
* Retrieve a list of the SCH_PINs for the given sheet path.
*
* Since a symbol can have a different unit on a different instance of a sheet,
* this list returns the subset of pins that exist on a given sheet.
2021-03-25 21:13:01 +00:00
*
* @return a vector of pointers (non-owning) to SCH_PINs
*/
std::vector<SCH_PIN*> GetPins( const SCH_SHEET_PATH* aSheet = nullptr ) const;
std::vector<std::unique_ptr<SCH_PIN>>& GetRawPins() { return m_pins; }
2018-08-30 19:44:10 +00:00
/**
2021-03-25 21:13:01 +00:00
* Print a symbol.
2017-06-30 07:50:49 +00:00
*
* @param aSettings Render settings controlling output
2022-01-01 18:57:44 +00:00
* @param aOffset is the drawing offset (usually VECTOR2I(0,0), but can be different when
2021-03-25 21:13:01 +00:00
* moving an object)
*/
void Print( const RENDER_SETTINGS* aSettings, const VECTOR2I& aOffset ) override;
/**
* Print only the background parts of a symbol (if any)
*
* @param aSettings Render settings controlling output
* @param aOffset is the drawing offset (usually VECTOR2I(0,0), but can be different when
* moving an object)
*/
void PrintBackground( const RENDER_SETTINGS* aSettings, const VECTOR2I& aOffset ) override;
2016-09-24 18:53:15 +00:00
void SwapData( SCH_ITEM* aItem ) override;
/**
2021-03-25 21:13:01 +00:00
* Test for an acceptable reference string.
*
* An acceptable reference string must support unannotation i.e starts by letter
*
* @param aReferenceString is the reference string to validate
* @return true if reference string is valid.
*/
static bool IsReferenceStringValid( const wxString& aReferenceString );
/**
* Return the reference for the given sheet path.
*
* @return the reference for the sheet.
*/
const wxString GetRef( const SCH_SHEET_PATH* aSheet, bool aIncludeUnit = false ) const;
/**
* Set the reference for the given sheet path for this symbol.
*
* @param aSheet is the hierarchical path of the reference.
* @param aReference is the new reference for the symbol.
*/
void SetRef( const SCH_SHEET_PATH* aSheet, const wxString& aReference );
/**
2021-03-25 21:13:01 +00:00
* Check if the symbol has a valid annotation (reference) for the given sheet path.
*
* @param aSheet is the sheet path to test.
* @return true if the symbol exists on that sheet and has a valid reference.
*/
bool IsAnnotated( const SCH_SHEET_PATH* aSheet );
/**
* Add a full hierarchical reference to this symbol.
*
2021-03-25 21:13:01 +00:00
* @param aPath is the hierarchical path (/&ltsheet timestamp&gt/&ltsymbol
* timestamp&gt like /05678E50/A23EF560).
* @param aRef is the local reference like C45, R56.
* @param aUnit is the unit selection used for symbols with multiple units per package.
2021-03-25 21:13:01 +00:00
* @param aValue is the value used for this instance.
* @param aFootprint is the footprint used for this instance (which might have different
2021-03-25 21:13:01 +00:00
* hole spacing or other board-specific changes from other instances).
*/
void AddHierarchicalReference( const KIID_PATH& aPath,
const wxString& aRef,
int aUnit );
void AddHierarchicalReference( const SCH_SYMBOL_INSTANCE& aInstance );
2021-03-25 21:13:01 +00:00
/// Return the instance-specific unit selection for the given sheet path.
int GetUnitSelection( const SCH_SHEET_PATH* aSheet ) const;
2021-03-25 21:13:01 +00:00
/// Set the selected unit of this symbol on one sheet.
void SetUnitSelection( const SCH_SHEET_PATH* aSheet, int aUnitSelection );
2008-02-26 19:19:54 +00:00
2021-03-25 21:13:01 +00:00
/// Set the selected unit of this symbol for all sheets.
void SetUnitSelection( int aUnitSelection );
// Geometric transforms (used in block operations):
void Move( const VECTOR2I& aMoveVector ) override
{
2022-01-01 18:57:44 +00:00
if( aMoveVector == VECTOR2I( 0, 0 ) )
return;
2020-11-16 13:15:54 +00:00
m_pos += aMoveVector;
2020-11-16 13:15:54 +00:00
for( SCH_FIELD& field : m_fields )
2020-03-06 20:02:58 +00:00
field.Move( aMoveVector );
}
void MirrorHorizontally( int aCenter ) override;
void MirrorVertically( int aCenter ) override;
void Rotate( const VECTOR2I& aCenter ) override;
bool Matches( const EDA_SEARCH_DATA& aSearchData, void* aAuxData ) const override;
2016-09-24 18:53:15 +00:00
void GetEndPoints( std::vector<DANGLING_END_ITEM>& aItemList ) override;
/**
2021-03-25 21:13:01 +00:00
* Test if the symbol's dangling state has changed for all pins.
*
* As a side effect, actually update the dangling status for all pins.
*
* @note This does not test for short circuits.
*
2017-06-30 07:50:49 +00:00
* @param aItemList is list of all #DANGLING_END_ITEM items to be tested.
* @return true if any pin's state has changed.
*/
bool UpdateDanglingState( std::vector<DANGLING_END_ITEM>& aItemList,
const SCH_SHEET_PATH* aPath = nullptr ) override;
VECTOR2I GetPinPhysicalPosition( const LIB_PIN* Pin ) const;
bool IsConnectable() const override { return true; }
bool CanConnect( const SCH_ITEM* aItem ) const override
{
return ( aItem->Type() == SCH_LINE_T && aItem->GetLayer() == LAYER_WIRE ) ||
( aItem->Type() == SCH_NO_CONNECT_T ) ||
( aItem->Type() == SCH_JUNCTION_T ) ||
( aItem->Type() == SCH_SYMBOL_T ) ||
( aItem->Type() == SCH_DIRECTIVE_LABEL_T ) ||
( aItem->Type() == SCH_LABEL_T ) ||
( aItem->Type() == SCH_HIER_LABEL_T ) ||
( aItem->Type() == SCH_GLOBAL_LABEL_T );
}
/**
2021-03-25 21:13:01 +00:00
* @return true if the symbol is in netlist.
*/
bool IsInNetlist() const;
std::vector<VECTOR2I> GetConnectionPoints() const override;
INSPECT_RESULT Visit( INSPECTOR inspector, void* testData,
const std::vector<KICAD_T>& aScanTypes ) override;
/**
2021-03-25 21:13:01 +00:00
* Return the symbol library item at \a aPosition that is part of this symbol.
*
2021-03-25 21:13:01 +00:00
* @param aPosition is the schematic position of the symbol library object.
* @param aType is the type of symbol library object to find or any if set to TYPE_NOT_INIT.
* @return is the symbol library object if found otherwise NULL.
*/
LIB_ITEM* GetDrawItem( const VECTOR2I& aPosition, KICAD_T aType = TYPE_NOT_INIT );
wxString GetItemDescription( UNITS_PROVIDER* aUnitsProvider ) const override;
BITMAPS GetMenuImage() const override;
2016-09-24 18:53:15 +00:00
bool operator <( const SCH_ITEM& aItem ) const override;
2021-06-10 14:10:55 +00:00
bool operator==( const SCH_SYMBOL& aSymbol) const;
bool operator!=( const SCH_SYMBOL& aSymbol) const;
2021-06-10 14:10:55 +00:00
SCH_SYMBOL& operator=( const SCH_ITEM& aItem );
2016-09-25 17:06:49 +00:00
bool IsReplaceable() const override { return true; }
VECTOR2I GetPosition() const override { return m_pos; }
void SetPosition( const VECTOR2I& aPosition ) override { Move( aPosition - m_pos ); }
bool HitTest( const VECTOR2I& aPosition, int aAccuracy = 0 ) const override;
2022-08-31 09:33:46 +00:00
bool HitTest( const BOX2I& aRect, bool aContained, int aAccuracy = 0 ) const override;
void Plot( PLOTTER* aPlotter, bool aBackground,
const SCH_PLOT_SETTINGS& aPlotSettings ) const override;
/**
* Plot just the symbol pins. This is separated to match the GAL display order. The pins
* are ALSO plotted with the symbol group. This replotting allows us to ensure that they
* are shown above other elements in the schematic.
*
* @param aPlotter is the #PLOTTER object used to plot pins.
*/
void PlotPins( PLOTTER* aPlotter ) const;
/**
* Plot the red 'X' over the symbol. This is separated to allow it being used from the
* screen plot function, overlapping the pins
*
* @param aPlotter the #PLOTTER object used to draw the X
*/
void PlotDNP( PLOTTER* aPlotter ) const;
2016-09-24 18:53:15 +00:00
EDA_ITEM* Clone() const override;
#if defined(DEBUG)
2016-09-25 17:06:49 +00:00
void Show( int nestLevel, std::ostream& os ) const override;
2008-02-26 19:19:54 +00:00
#endif
void ClearBrightenedPins();
bool HasBrightenedPins();
bool GetExcludedFromSim() const override { return m_excludedFromSim; }
void SetExcludedFromSim( bool aExclude ) override { m_excludedFromSim = aExclude; }
bool GetExcludedFromBOM() const { return m_excludedFromBOM; }
void SetExcludedFromBOM( bool aIncludeInBOM ) { m_excludedFromBOM = aIncludeInBOM; }
bool GetExcludedFromBoard() const { return m_excludedFromBoard; }
void SetExcludedFromBoard( bool aIncludeOnBoard ) { m_excludedFromBoard = aIncludeOnBoard; }
bool GetDNP() const { return m_DNP; }
void SetDNP( bool aDNP ) { m_DNP = aDNP; }
bool IsPointClickableAnchor( const VECTOR2I& aPos ) const override;
/**
* @return true if the symbol is equivalent to a global label:
* It is a Power symbol
* It has only one pin type Power input
*/
bool IsSymbolLikePowerGlobalLabel() const;
bool IsPower() const;
double Similarity( const SCH_ITEM& aOther ) const override;
bool operator==( const SCH_ITEM& aOther ) const override;
private:
2022-08-30 23:28:18 +00:00
BOX2I doGetBoundingBox( bool aIncludePins, bool aIncludeFields ) const;
bool doIsConnected( const VECTOR2I& aPosition ) const override;
2021-03-25 21:13:01 +00:00
void Init( const VECTOR2I& pos = VECTOR2I( 0, 0 ) );
2021-03-25 21:13:01 +00:00
VECTOR2I m_pos;
2021-03-25 21:13:01 +00:00
LIB_ID m_lib_id; ///< Name and library the symbol was loaded from, i.e. 74xx:74LS00.
int m_unit; ///< The unit for multiple part per package symbols.
int m_convert; ///< The alternate body style for symbols that have more than
///< one body style defined. Primarily used for symbols that
///< have a De Morgan conversion.
wxString m_prefix; ///< C, R, U, Q etc - the first character(s) which typically
///< indicate what the symbol is. Determined, upon placement,
///< from the library symbol. Created upon file load, by the
///< first non-digits in the reference fields.
2021-03-25 21:13:01 +00:00
/**
* The name used to look up a symbol in the symbol library embedded in a schematic.
*
* By default this is the same as #LIB_ID::GetLibItemName(). However, schematics allow for
* multiple variants of the same library symbol. Set this member in order to preserve the
* link to the original symbol library. If empty, #LIB_ID::GetLibItemName() should be used.
*/
wxString m_schLibSymbolName;
TRANSFORM m_transform; ///< The rotation/mirror transformation.
std::vector<SCH_FIELD> m_fields; ///< Variable length list of fields.
2021-03-25 21:13:01 +00:00
std::unique_ptr< LIB_SYMBOL > m_part; ///< a flattened copy of the LIB_SYMBOL
///< from the PROJECT's libraries.
std::vector<std::unique_ptr<SCH_PIN>> m_pins; ///< a SCH_PIN for every LIB_PIN (all units)
std::unordered_map<LIB_PIN*, SCH_PIN*> m_pinMap; ///< library pin pointer : SCH_PIN's index
2021-03-25 21:13:01 +00:00
bool m_isInNetlist; ///< True if the symbol should appear in the netlist
bool m_excludedFromSim; ///< True to exclude from simulation.
bool m_excludedFromBOM; ///< True to exclude from bill of materials export.
bool m_excludedFromBoard; ///< True to exclude from netlist when updating board.
bool m_DNP; ///< True if symbol is set to 'Do Not Populate'.
2021-03-25 21:13:01 +00:00
// Defines the hierarchical path and reference of the symbol. This allows support
// for multiple references to a single sub-sheet.
std::vector<SCH_SYMBOL_INSTANCE> m_instanceReferences;
/// @see SCH_SYMBOL::GetOrientation
static std::unordered_map<TRANSFORM, int> s_transformToOrientationCache;
2007-05-06 16:03:28 +00:00
};
2021-06-10 14:10:55 +00:00
#endif /* __SYMBOL_H__ */