lib_symbol.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2004-2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
 * Copyright (C) 2008 Wayne Stambaugh <stambaughw@gmail.com>
 * Copyright (C) 2022 CERN
 * Copyright The 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
 */
 
#ifndef LIB_SYMBOL_H
#define LIB_SYMBOL_H
 
#include <embedded_files.h>
#include <symbol.h>
#include <sch_field.h>
#include <sch_pin.h>
#include <lib_tree_item.h>
#include <vector>
#include <core/multivector.h>
 
class LINE_READER;
class OUTPUTFORMATTER;
class REPORTER;
class SYMBOL_LIB;
class LIB_SYMBOL;
class OUTLINE_FONT;
class TEST_LIB_SYMBOL_FIXTURE;
 
namespace KIFONT
{
    class OUTLINE_FONT;
}
 
 
typedef std::shared_ptr<LIB_SYMBOL>       LIB_SYMBOL_SPTR;      
typedef std::weak_ptr<LIB_SYMBOL>         LIB_SYMBOL_REF;       
typedef MULTIVECTOR<SCH_ITEM, SCH_SHAPE_T, SCH_PIN_T> LIB_ITEMS_CONTAINER;
typedef LIB_ITEMS_CONTAINER::ITEM_PTR_VECTOR LIB_ITEMS;
 
 
/* values for member .m_options */
enum LIBRENTRYOPTIONS
{
    ENTRY_NORMAL,     // Libentry is a standard symbol (real or alias)
    ENTRY_GLOBAL_POWER,      // Libentry is a power symbol
    ENTRY_LOCAL_POWER // Libentry is a local power symbol
};
 
 
extern bool operator<( const LIB_SYMBOL& aItem1, const LIB_SYMBOL& aItem2 );
 
 
struct LIB_SYMBOL_UNIT
{
    int m_unit;                       
    int m_bodyStyle;                  
    std::vector<SCH_ITEM*> m_items;   
};
 
 
class LIB_SYMBOL : public SYMBOL, public LIB_TREE_ITEM, public EMBEDDED_FILES
{
public:
    LIB_SYMBOL( const wxString& aName, LIB_SYMBOL* aParent = nullptr,
                SYMBOL_LIB* aLibrary = nullptr );
 
    LIB_SYMBOL( const LIB_SYMBOL& aSymbol, SYMBOL_LIB* aLibrary = nullptr );
 
    virtual ~LIB_SYMBOL()
    {}
 
    LIB_SYMBOL_SPTR SharedPtr() const { return m_me; }
 
    virtual LIB_SYMBOL* Duplicate() const
    {
        LIB_SYMBOL* dupe = new LIB_SYMBOL( *this, m_library );
        const_cast<KIID&>( dupe->m_Uuid ) = KIID();
 
        for( SCH_ITEM& item : dupe->m_drawings )
            const_cast<KIID&>( item.m_Uuid ) = KIID();
 
        return dupe;
    }
 
    static LIB_SYMBOL* GetDummy();
 
    void SetParent( LIB_SYMBOL* aParent = nullptr );
    LIB_SYMBOL_REF& GetParent() { return m_parent; }
    const LIB_SYMBOL_REF& GetParent() const { return m_parent; }
 
    unsigned GetInheritanceDepth() const;
 
    LIB_SYMBOL_SPTR GetRootSymbol() const;
 
    virtual wxString GetClass() const override
    {
        return wxT( "LIB_SYMBOL" );
    }
 
    static inline bool ClassOf( const EDA_ITEM* aItem )
    {
        return aItem && aItem->Type() == LIB_SYMBOL_T;
    }
 
    virtual void SetName( const wxString& aName );
    wxString GetName() const override { return m_name; }
 
    LIB_ID GetLIB_ID() const override { return m_libId; }
    wxString GetDesc() override { return GetDescription(); }
    int GetSubUnitCount() const override { return GetUnitCount(); }
 
    const LIB_ID& GetLibId() const override { return m_libId; }
    void SetLibId( const LIB_ID& aLibId ) { m_libId = aLibId; }
 
    LIB_ID GetSourceLibId() const { return m_sourceLibId; }
    void SetSourceLibId( const LIB_ID& aLibId ) { m_sourceLibId = aLibId; }
 
    wxString GetLibNickname() const override { return GetLibraryName(); }
 
    void SetDescription( const wxString& aDescription )
    {
        GetDescriptionField().SetText( aDescription );
    }
 
    wxString GetDescription() const override
    {
        if( GetDescriptionField().GetText().IsEmpty() && IsDerived() )
        {
            if( LIB_SYMBOL_SPTR parent = m_parent.lock() )
                return parent->GetDescription();
        }
 
        return GetDescriptionField().GetText();
    }
 
    void SetKeyWords( const wxString& aKeyWords ) { m_keyWords = aKeyWords; }
 
    wxString GetKeyWords() const override
    {
        if( m_keyWords.IsEmpty() && IsDerived() )
        {
            if( LIB_SYMBOL_SPTR parent = m_parent.lock() )
                return parent->GetKeyWords();
        }
 
        return m_keyWords;
    }
 
    std::vector<SEARCH_TERM> GetSearchTerms() override;
 
    wxString GetFootprint() override
    {
        return GetFootprintField().GetText();
    }
 
    void GetChooserFields( std::map<wxString , wxString>& aColumnMap ) override;
 
    bool IsRoot() const override { return m_parent.use_count() == 0; }
    bool IsDerived() const { return !m_parent.expired() && m_parent.use_count() > 0; }
 
    const wxString GetLibraryName() const;
 
    SYMBOL_LIB* GetLib() const          { return m_library; }
    void SetLib( SYMBOL_LIB* aLibrary ) { m_library = aLibrary; }
 
    timestamp_t GetLastModDate() const { return m_lastModDate; }
 
    void SetFPFilters( const wxArrayString& aFilters ) { m_fpFilters = aFilters; }
 
    wxArrayString GetFPFilters() const
    {
        if( m_fpFilters.IsEmpty() && IsDerived() )
        {
            if( LIB_SYMBOL_SPTR parent = m_parent.lock() )
                return parent->GetFPFilters();
        }
 
        return m_fpFilters;
    }
 
    const BOX2I GetUnitBoundingBox( int aUnit, int aBodyStyle,
                                    bool aIgnoreHiddenFields = true ) const;
 
    const BOX2I GetBoundingBox() const override
    {
        return GetUnitBoundingBox( 0, 0 );
    }
 
    const BOX2I GetBodyBoundingBox( int aUnit, int aBodyStyle, bool aIncludePins,
                                    bool aIncludePrivateItems ) const;
 
    BOX2I GetBodyBoundingBox() const override
    {
        return GetBodyBoundingBox( m_previewUnit, m_previewBodyStyle, false, false );
    }
 
    BOX2I GetBodyAndPinsBoundingBox() const override
    {
        return GetBodyBoundingBox( m_previewUnit, m_previewBodyStyle, true, false );
    }
 
    bool IsGlobalPower() const override;
    bool IsLocalPower() const override;
    bool IsPower() const override;
    bool IsNormal() const override;
 
    void SetGlobalPower();
    void SetLocalPower();
    void SetNormal();
 
    void LockUnits( bool aLockUnits ) { m_unitsLocked = aLockUnits; }
 
    bool UnitsLocked() const { return m_unitsLocked; }
 
    void SetFields( const std::vector<SCH_FIELD>& aFieldsList );
 
    void GetFields( std::vector<SCH_FIELD*>& aList, bool aVisibleOnly = false ) const override;
 
    void CopyFields( std::vector<SCH_FIELD>& aList );
 
    void AddField( SCH_FIELD* aField );
 
    void AddField( SCH_FIELD& aField ) { AddField( new SCH_FIELD( aField ) ); }
 
    int GetNextFieldOrdinal() const;
 
    SCH_FIELD* GetField( const wxString& aFieldName );
    const SCH_FIELD* GetField( const wxString& aFieldName ) const;
 
    SCH_FIELD* FindFieldCaseInsensitive( const wxString& aFieldName );
 
    const SCH_FIELD* GetField( FIELD_T aFieldType ) const;
    SCH_FIELD* GetField( FIELD_T aFieldType );
 
    SCH_FIELD& GetValueField() { return *GetField( FIELD_T::VALUE ); }
    const SCH_FIELD& GetValueField() const;
 
    SCH_FIELD& GetReferenceField() { return *GetField( FIELD_T::REFERENCE ); }
    const SCH_FIELD& GetReferenceField() const;
 
    SCH_FIELD& GetFootprintField() { return *GetField( FIELD_T::FOOTPRINT ); }
    const SCH_FIELD& GetFootprintField() const;
 
    SCH_FIELD& GetDatasheetField() { return *GetField( FIELD_T::DATASHEET ); }
    const SCH_FIELD& GetDatasheetField() const;
 
    SCH_FIELD& GetDescriptionField() {return *GetField( FIELD_T::DESCRIPTION ); }
    const SCH_FIELD& GetDescriptionField() const;
 
    wxString GetPrefix();
 
    const wxString GetRef( const SCH_SHEET_PATH* aSheet, bool aIncludeUnit = false ) const override
    {
        return GetReferenceField().GetText();
    }
 
    const wxString GetValue( bool aResolve, const SCH_SHEET_PATH* aPath,
                             bool aAllowExtraText ) const override
    {
        return GetValueField().GetText();
    }
 
    std::set<KIFONT::OUTLINE_FONT*> GetFonts() const override;
 
    EMBEDDED_FILES* GetEmbeddedFiles() override;
    const EMBEDDED_FILES* GetEmbeddedFiles() const;
 
    void EmbedFonts() override;
 
    void AutoplaceFields( SCH_SCREEN* aScreen, AUTOPLACE_ALGO aAlgo ) override;
 
    void RunOnChildren( const std::function<void( SCH_ITEM* )>& aFunction, RECURSE_MODE aMode ) override;
 
    bool ResolveTextVar( wxString* token, int aDepth = 0 ) const;
 
    void Plot( PLOTTER* aPlotter, bool aBackground, const SCH_PLOT_OPTS& aPlotOpts,
               int aUnit, int aBodyStyle, const VECTOR2I& aOffset, bool aDimmed ) override;
 
    void PlotFields( PLOTTER* aPlotter, bool aBackground, const SCH_PLOT_OPTS& aPlotOpts,
                     int aUnit, int aBodyStyle, const VECTOR2I& aOffset, bool aDimmed );
 
    void AddDrawItem( SCH_ITEM* aItem, bool aSort = true );
 
    void RemoveDrawItem( SCH_ITEM* aItem );
 
    void RemoveField( SCH_FIELD* aField ) { RemoveDrawItem( aField ); }
 
    std::vector<SCH_PIN*> GetPins( int aUnit, int aBodyStyle ) const;
 
    std::vector<SCH_PIN*> GetPins() const override;
 
    int GetPinCount() override;
 
    SCH_PIN* GetPin( const wxString& aNumber, int aUnit = 0, int aBodyStyle = 0 ) const;
 
    bool PinsConflictWith( const LIB_SYMBOL& aOtherSymbol, bool aTestNums, bool aTestNames,
                           bool aTestType, bool aTestOrientation, bool aTestLength ) const;
 
    void Move( const VECTOR2I& aOffset ) override;
 
    bool HasAlternateBodyStyle() const override;
 
    int GetMaxPinNumber() const;
 
    void ClearTempFlags() override;
    void ClearEditFlags() override;
 
    SCH_ITEM* LocateDrawItem( int aUnit, int aBodyStyle, KICAD_T aType, const VECTOR2I& aPoint );
 
    SCH_ITEM* LocateDrawItem( int aUnit, int aBodyStyle, KICAD_T aType, const VECTOR2I& aPoint,
                              const TRANSFORM& aTransform );
 
    LIB_ITEMS_CONTAINER& GetDrawItems() { return m_drawings; }
    const LIB_ITEMS_CONTAINER& GetDrawItems() const { return m_drawings; }
 
    void FixupDrawItems();
 
    INSPECT_RESULT Visit( INSPECTOR inspector, void* testData,
                          const std::vector<KICAD_T>& aScanTypes ) override;
 
    void SetUnitCount( int aCount, bool aDuplicateDrawItems = true );
    int GetUnitCount() const override;
 
    wxString GetUnitReference( int aUnit ) override;
 
    bool HasUnitDisplayName( int aUnit ) override;
 
    wxString GetUnitDisplayName( int aUnit ) override;
 
    void CopyUnitDisplayNames( std::map<int, wxString>& aTarget ) const;
 
    void SetUnitDisplayName( int aUnit, const wxString& aName );
 
    bool GetDuplicatePinNumbersAreJumpers() const { return m_duplicatePinNumbersAreJumpers; }
    void SetDuplicatePinNumbersAreJumpers( bool aEnabled ) { m_duplicatePinNumbersAreJumpers = aEnabled; }
 
    std::vector<std::set<wxString>>& JumperPinGroups() { return m_jumperPinGroups; }
    const std::vector<std::set<wxString>>& JumperPinGroups() const { return m_jumperPinGroups; }
 
    std::optional<const std::set<wxString>> GetJumperPinGroup( const wxString& aPinNumber ) const;
 
    bool IsMulti() const override { return m_unitCount > 1; }
 
    static wxString LetterSubReference( int aUnit, int aFirstId );
 
    void SetHasAlternateBodyStyle( bool aHasAlternate, bool aDuplicatePins = true );
 
    int Compare( const LIB_SYMBOL& aRhs, int aCompareFlags = 0,
                 REPORTER* aReporter = nullptr ) const;
 
    const LIB_SYMBOL& operator=( const LIB_SYMBOL& aSymbol );
 
    std::unique_ptr< LIB_SYMBOL > Flatten() const;
 
    std::vector<struct LIB_SYMBOL_UNIT> GetUnitDrawItems();
 
    std::vector<SCH_ITEM*> GetUnitDrawItems( int aUnit, int aBodyStyle );
 
    double Similarity( const SCH_ITEM& aSymbol ) const override;
#if defined(DEBUG)
    void Show( int nestLevel, std::ostream& os ) const override { ShowDummy( os ); }
#endif
 
private:
    // We create a different set parent function for this class, so we hide the inherited one.
    using EDA_ITEM::SetParent;
 
    int compare( const SCH_ITEM& aOther,
                 int aCompareFlags = SCH_ITEM::COMPARE_FLAGS::EQUALITY ) const override;
 
    void deleteAllFields();
 
private:
    LIB_SYMBOL_SPTR     m_me;
    LIB_SYMBOL_REF      m_parent;           
    LIB_ID              m_libId;
    LIB_ID              m_sourceLibId;      
    timestamp_t         m_lastModDate;
 
    int                 m_unitCount;        
    bool                m_unitsLocked;      
 
    LIBRENTRYOPTIONS    m_options;          
 
    LIB_ITEMS_CONTAINER m_drawings;
 
    SYMBOL_LIB*         m_library;
    wxString            m_name;
    wxString            m_keyWords;         
    wxArrayString       m_fpFilters;        
 
    std::vector<std::set<wxString> > m_jumperPinGroups;
 
    bool m_duplicatePinNumbersAreJumpers;
 
    std::map<int, wxString> m_unitDisplayNames;
};
 
#endif  //  CLASS_LIBENTRY_H