schematic.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * 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 3 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, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef KICAD_SCHEMATIC_H
#define KICAD_SCHEMATIC_H
 
#include <eda_item.h>
#include <embedded_files.h>
#include <erc/erc_exclusion.h>
#include <properties/property_mgr.h>
#include <schematic_holder.h>
#include <sch_rtree.h>
#include <sch_sheet_path.h>
#include <schematic_settings.h>
#include <project.h>
#include <import_net_map.h>
 
#include <memory>
#include <optional>
#include <vector>
 
 
struct HISTORY_FILE_DATA;
class BUS_ALIAS;
class CONNECTION_GRAPH;
class EDA_BASE_FRAME;
class ERC_SETTINGS;
class LIB_SYMBOL;
class PROJECT;
class SCH_COMMIT;
class SCH_LINE;
class SCH_SCREEN;
class SCH_SHEET;
class SCH_SHEET_LIST;
class SCH_GLOBALLABEL;
class SCH_REFERENCE;
class PROGRESS_REPORTER;
class TOOL_MANAGER;
class PICKED_ITEMS_LIST;
 
namespace SCH_CONNECTIVITY
{
class FACADE;
class NETCHAIN_MANAGER;
}
 
namespace KIFONT
{
class OUTLINE_FONT;
}
 
namespace KIGFX
{
class SCH_VIEW;
}
 
 
class SCHEMATIC;
 
class SCHEMATIC_LISTENER
{
public:
    virtual ~SCHEMATIC_LISTENER() {}
    virtual void OnSchItemsAdded( SCHEMATIC& aSch, std::vector<SCH_ITEM*>& aSchItem ) {}
    virtual void OnSchItemsRemoved( SCHEMATIC& aSch, std::vector<SCH_ITEM*>& aSchItem ) {}
    virtual void OnSchItemsChanged( SCHEMATIC& aSch, std::vector<SCH_ITEM*>& aSchItem ) {}
 
    // This is called when the user changes to a new sheet, not when a sheet is altered.
    // Sheet alteration events will call OnSchItems*
    virtual void OnSchSheetChanged( SCHEMATIC& aSch ) {}
 
    virtual void OnSchSelectionChanged( SCHEMATIC& aSch ) {}
};
 
enum SCH_CLEANUP_FLAGS
{
    NO_CLEANUP,
    LOCAL_CLEANUP,
    GLOBAL_CLEANUP
};

struct SCHEMATIC_CONTENT
{
    SCH_SHEET* targetSheet = nullptr;

    std::unique_ptr<SCH_SCREEN> screen;

    EE_RTREE screenItems;

    std::unique_ptr<SCH_SCREEN> screenLibSymbols;

    std::vector<std::unique_ptr<SCH_ITEM>> itemOwners;

    std::vector<SCH_SHEET*> topLevelSheets;
 
    SCH_SHEET_LIST                    hierarchy;
    std::optional<SCH_SHEET_PATH>     currentSheet;
    std::unique_ptr<CONNECTION_GRAPH> connectionGraph;

    bool preserveNetChains = false;
 
    std::optional<EMBEDDED_FILES>     embeddedFiles;
    wxString                          drawingSheetFileName;
};

class SCHEMATIC : public EDA_ITEM, public EMBEDDED_FILES, public PROJECT::_ELEM
{
public:
    SCHEMATIC( PROJECT* aPrj );
 
    virtual ~SCHEMATIC();
 
    virtual wxString GetClass() const override
    {
        return wxT( "SCHEMATIC" );
    }

    void Reset();
 
    const IMPORT_NET_MAP* GetImportNetMap() const
    {
        return m_importNetMap ? &*m_importNetMap : nullptr;
    }
 
    void SetImportNetMap( IMPORT_NET_MAP aMap ) { m_importNetMap = std::move( aMap ); }

    PROJECT& Project() const { return *m_project; }
    void SetProject( PROJECT* aPrj );
 
    const std::map<wxString, wxString>* GetProperties() { return &m_properties; }
 
    SCH_SHEET_LIST BuildSheetListSortedByPageNumbers() const;
 
    SCH_SHEET_LIST BuildUnorderedSheetList() const;

    SCH_SHEET_LIST Hierarchy() const;

    bool HasHierarchy() const { return !m_hierarchy.empty(); }
 
    void RefreshHierarchy();
 
    SCH_ITEM* ResolveItem( const KIID& aID, SCH_SHEET_PATH* aPathOut = nullptr,
                           bool aAllowNullptrReturn = false ) const
    {
        return m_hierarchy.ResolveItem( aID, aPathOut, aAllowNullptrReturn );
    }
 
    SCH_SHEET& Root() const
    {
        return *m_rootSheet;
    }

    std::vector<SCH_SHEET*> GetTopLevelSheets() const;
 
    SCH_SHEET* GetTopLevelSheet( int aIndex = 0 ) const;

    bool IsTopLevelSheetUuid( const KIID& aUuid ) const;

    KIID_PATH NormalizeInstancePath( const KIID_PATH& aPath ) const;

    bool IsInstancePathInProject( const KIID_PATH& aPath ) const;

    void SetTopLevelSheets( const std::vector<SCH_SHEET*>& aSheets );

    void AdoptContent( SCHEMATIC_CONTENT&& aContent ) noexcept;

    void AddTopLevelSheet( SCH_SHEET* aSheet );

    bool RemoveTopLevelSheet( SCH_SHEET* aSheet );

    bool IsTopLevelSheet( const SCH_SHEET* aSheet ) const;

    bool IsValid() const
    {
        return m_project && m_rootSheet != nullptr;
    }

    SCH_SCREEN* RootScreen() const;
 
    void GetContextualTextVars( wxArrayString* aVars ) const;
 
    bool ResolveTextVar( const SCH_SHEET_PATH* aSheetPath, wxString* token, int aDepth ) const;

    wxString GetFileName() const;
 
    SCH_SHEET_PATH& CurrentSheet() const
    {
        return *m_currentSheet;
    }
 
    void SetCurrentSheet( const SCH_SHEET_PATH& aPath )
    {
        *m_currentSheet = aPath;
    }
 
    SCH_SCREEN* GetCurrentScreen() const { return CurrentSheet().LastScreen(); }
 
    SCH_CONNECTIVITY::FACADE& Connectivity() const { return *m_connectivity; }
    SCH_CONNECTIVITY::NETCHAIN_MANAGER& NetChains() const { return *m_netChains; }
 
    CONNECTION_GRAPH* ConnectionGraph() const
    {
        return m_connectionGraph;
    }
 
    const wxString& GetHighlightedNetChain() const { return m_highlightedNetChain; }
    void SetHighlightedNetChain( const wxString& aNetChain ) { m_highlightedNetChain = aNetChain; }
 
    SCHEMATIC_SETTINGS& Settings() const;
 
    ERC_SETTINGS& ErcSettings() const;
 
    std::vector<SCH_MARKER*> ResolveERCExclusions();
 
    EMBEDDED_FILES* GetEmbeddedFiles() override;
    const EMBEDDED_FILES* GetEmbeddedFiles() const;

    std::shared_ptr<BUS_ALIAS> GetBusAlias( const wxString& aLabel ) const;
 
    void AddBusAlias( std::shared_ptr<BUS_ALIAS> aAlias );
 
    void SetBusAliases( const std::vector<std::shared_ptr<BUS_ALIAS>>& aAliases );
 
    // An explicit project table, including an empty one, supersedes legacy sheet definitions.
    bool HasProjectBusAliases() const;
 
    const std::vector<std::shared_ptr<BUS_ALIAS>>& GetAllBusAliases() const
    {
        return m_busAliases;
    }

    std::set<wxString> GetNetClassAssignmentCandidates();

    bool ResolveCrossReference( wxString* token, int aDepth ) const;
 
    std::map<wxString, std::set<int>>& GetPageRefsMap() { return m_labelToPageRefsMap; }
 
    std::map<int, wxString> GetVirtualPageToSheetNamesMap() const;
    std::map<int, wxString> GetVirtualPageToSheetPagesMap() const;
 
    wxString ConvertRefsToKIIDs( const wxString& aSource ) const;
    wxString ConvertKIIDsToRefs( const wxString& aSource ) const;

    void SetLegacySymbolInstanceData();

    wxString GetUniqueFilenameForCurrentSheet();

    void SetSheetNumberAndCount();

    void RecomputeIntersheetRefs();
 
    void SyncLibSymbolPinMaps( const wxString& aSchLibSymbolName, const LIB_SYMBOL& aSource, SCH_COMMIT* aCommit );

    void ClearOperatingPoints()
    {
        m_operatingPoints.clear();
    }

    void SetOperatingPoint( const wxString& aNetChain, double aValue )
    {
        m_operatingPoints[ aNetChain ] = aValue;
    }
 
    wxString GetOperatingPoint( const wxString& aNetName, int aPrecision, const wxString& aRange );

    int FixupJunctionsAfterImport( const std::function<void( SCH_LINE*, SCH_LINE* )>& aOnSplit = {} );

    void RecordERCExclusions();
 
    size_t GetUnresolvedERCExclusionCount() const { return m_unresolvedErcExclusions.size(); }
 
    void ClearUnresolvedERCExclusions( int aErrorCode = -1 );

    void ResolveERCExclusionsPostUpdate();

    void OnItemsAdded( std::vector<SCH_ITEM*>& aNewItems );

    void OnItemsRemoved( std::vector<SCH_ITEM*>& aRemovedItems );

    void OnItemsChanged( std::vector<SCH_ITEM*>& aItems );

    void OnSchSheetChanged();

    void OnSchSelectionChanged();

    void AddListener( SCHEMATIC_LISTENER* aListener );

    void RemoveListener( SCHEMATIC_LISTENER* aListener );

    void RemoveAllListeners();
 
    void RunOnNestedEmbeddedFiles( const std::function<void( EMBEDDED_FILES* )>& aFunction ) override;

    void EmbedFonts() override;

    std::set<KIFONT::OUTLINE_FONT*> GetFonts() const override;

    std::set<const SCH_SCREEN*> GetSchematicsSharedByMultipleProjects() const;

    bool IsComplexHierarchy() const;
 
    void SetSchematicHolder( SCHEMATIC_HOLDER* aHolder ) { m_schematicHolder = aHolder; }

    void CleanUp( SCH_COMMIT* aCommit, SCH_SCREEN* aScreen = nullptr );
 
    // Prepare source geometry and intersheet references before rebuilding connectivity.
    void CleanUpConnections( SCH_COMMIT* aCommit, SCH_CLEANUP_FLAGS aCleanupFlags,
                             const std::set<SCH_SCREEN*>& aLocalScreens = {} );
 
    // Fully rebuild the selected connectivity backend without changing source geometry.
    void RebuildConnectivity( std::function<void( SCH_ITEM* )>* aChangedItemHandler = nullptr,
                              PROGRESS_REPORTER* aProgressReporter = nullptr,
                              KIGFX::SCH_VIEW* aSchView = nullptr );

    void RecalculateConnections( SCH_COMMIT* aCommit, SCH_CLEANUP_FLAGS aCleanupFlags,
                                 TOOL_MANAGER* aToolManager,
                                 PROGRESS_REPORTER* aProgressReporter = nullptr,
                                 KIGFX::SCH_VIEW* aSchView = nullptr,
                                 std::function<void( SCH_ITEM* )>* aChangedItemHandler = nullptr,
                                 PICKED_ITEMS_LIST*                aLastChangeList = nullptr,
                                 bool aCleanupDone = false );

    void CacheExistingAnnotation();

    bool Contains( const SCH_REFERENCE& aRef ) const;
 
    void CreateDefaultScreens();

    wxArrayString GetVariantNamesForUI() const;

    wxString GetCurrentVariant() const;
 
    void SetCurrentVariant( const wxString& aVariantName );

    void DeleteVariant( const wxString& aVariantName, SCH_COMMIT* aCommit = nullptr );
 
    void AddVariant( const wxString& aVariantName );

    void RenameVariant( const wxString& aOldName, const wxString& aNewName,
                        SCH_COMMIT* aCommit = nullptr );

    void CopyVariant( const wxString& aSourceVariant, const wxString& aNewVariant,
                      SCH_COMMIT* aCommit = nullptr );

    const std::set<wxString>& GetVariantNames() const { return m_variantNames; }

    bool HasVariant( const wxString& aVariantName ) const;

    wxString GetVariantDescription( const wxString& aVariantName ) const;

    void SetVariantDescription( const wxString& aVariantName, const wxString& aDescription );

    void LoadVariants();
 
#if defined(DEBUG)
    void Show( int nestLevel, std::ostream& os ) const override {}
#endif
 
    PROJECT::ELEM ProjectElementType() override { return PROJECT::ELEM::SCHEMATIC; }

    void SaveToHistory( const wxString& aProjectPath, std::vector<HISTORY_FILE_DATA>& aFileData );

    std::weak_ptr<void> GetHistoryLifetimeToken() const { return m_historyLifetime; }
 
private:
    bool resolveCrossReference( wxString* aToken, int aDepth ) const;
 
    friend class SCH_EDIT_FRAME;
 
    template <typename Func, typename... Args>
    void InvokeListeners( Func&& aFunc, Args&&... args )
    {
        for( auto&& l : m_listeners )
            ( l->*aFunc )( std::forward<Args>( args )... );
    }
 
    void ensureVirtualRoot();
    void ensureDefaultTopLevelSheet();
    void ensureCurrentSheetIsTopLevel();
    void rebuildHierarchyState( bool aResetConnectionGraph );
 
    PROJECT* m_project;
    std::optional<IMPORT_NET_MAP> m_importNetMap;

    std::shared_ptr<void> m_historyLifetime = std::make_shared<char>();

    SCH_SHEET* m_rootSheet;

    std::vector<SCH_SHEET*> m_topLevelSheets;

    SCH_SHEET_PATH* m_currentSheet;

    CONNECTION_GRAPH* m_connectionGraph;
    std::unique_ptr<SCH_CONNECTIVITY::FACADE> m_connectivity;
    std::unique_ptr<SCH_CONNECTIVITY::NETCHAIN_MANAGER> m_netChains;
 
    wxString m_highlightedNetChain;

    std::map<wxString, std::set<int>> m_labelToPageRefsMap;

    std::map<wxString, wxString>      m_properties;

    std::map<wxString, double>        m_operatingPoints;

    SCH_SHEET_LIST m_hierarchy;

    std::vector<ERC_EXCLUSION> m_unresolvedErcExclusions;

    std::vector<SCHEMATIC_LISTENER*> m_listeners;

    SCHEMATIC_HOLDER* m_schematicHolder;
 
    void loadBusAliasesFromProject();
 
    void updateProjectBusAliases();
 
    std::vector<std::shared_ptr<BUS_ALIAS>> m_busAliases;
 
    wxString m_currentVariant;
 
    std::set<wxString> m_variantNames;

    bool m_settingTopLevelSheets = false;

    std::unique_ptr<class SCHEMATIC_TEXT_VAR_ADAPTER> m_textVarAdapter;

    PROPERTY_LISTENER_SUBSCRIPTION m_fieldListenerSubscription;
 
public:
    class SCHEMATIC_TEXT_VAR_ADAPTER* GetTextVarAdapter() const { return m_textVarAdapter.get(); }
};
 
#endif