KiCad PCB EDA Suite
symbol_library_manager.h
Go to the documentation of this file.
1 /*
2  * This program source code file is symbol of KiCad, a free EDA CAD application.
3  *
4  * Copyright (C) 2017 CERN
5  * Copyright (C) 2019-2021 KiCad Developers, see AUTHORS.txt for contributors.
6  *
7  * @author Maciej Suminski <maciej.suminski@cern.ch>
8  *
9  * This program is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU General Public License
11  * as published by the Free Software Foundation; either version 3
12  * of the License, or (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A SYMBOLICULAR PURPOSE. See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, you may find one here:
21  * https://www.gnu.org/licenses/gpl-3.0.html
22  * or you may search the http://www.gnu.org website for the version 3 license,
23  * or you may write to the Free Software Foundation, Inc.,
24  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
25  */
26 
27 #ifndef SYMBOL_LIBRARY_MANAGER_H
28 #define SYMBOL_LIBRARY_MANAGER_H
29 
30 #include <map>
31 #include <list>
32 #include <deque>
33 #include <set>
34 #include <memory>
35 #include <wx/arrstr.h>
37 #include <sch_io_mgr.h>
38 #include <sch_screen.h>
39 
40 class LIB_SYMBOL;
41 class SYMBOL_LIB;
42 class PROGRESS_REPORTER;
43 class SCH_PLUGIN;
44 class SYMBOL_EDIT_FRAME;
45 class SYMBOL_LIB_TABLE;
47 class LIB_LOGGER;
48 
49 
54 {
55 public:
58 
62  void Sync( const wxString& aForceRefresh,
63  std::function<void( int, int, const wxString& )> aProgressCallback );
64 
70  void Preload( PROGRESS_REPORTER& aReporter );
71 
72  int GetHash() const;
73 
74  bool HasModifications() const;
75 
83  int GetLibraryHash( const wxString& aLibrary ) const;
84 
88  wxArrayString GetLibraryNames() const;
89 
93  SYMBOL_LIB_TABLE_ROW* GetLibrary( const wxString& aLibrary ) const;
94 
95  std::list<LIB_SYMBOL*> GetAliases( const wxString& aLibrary ) const;
96 
100  bool CreateLibrary( const wxString& aFilePath, SYMBOL_LIB_TABLE* aTable )
101  {
102  return addLibrary( aFilePath, true, aTable );
103  }
104 
108  bool AddLibrary( const wxString& aFilePath, SYMBOL_LIB_TABLE* aTable )
109  {
110  return addLibrary( aFilePath, false, aTable );
111  }
112 
118  bool UpdateSymbol( LIB_SYMBOL* aSymbol, const wxString& aLibrary );
119 
124  bool UpdateSymbolAfterRename( LIB_SYMBOL* aSymbol, const wxString& oldAlias,
125  const wxString& aLibrary );
126 
131  bool RemoveSymbol( const wxString& aName, const wxString& aLibrary );
132 
137  LIB_SYMBOL* GetAlias( const wxString& aAlias, const wxString& aLibrary ) const;
138 
143  LIB_SYMBOL* GetBufferedSymbol( const wxString& aAlias, const wxString& aLibrary );
144 
149  SCH_SCREEN* GetScreen( const wxString& aAlias, const wxString& aLibrary );
150 
155  bool SymbolExists( const wxString& aAlias, const wxString& aLibrary ) const;
156 
161  bool LibraryExists( const wxString& aLibrary, bool aCheckEnabled = false ) const;
162 
166  bool IsLibraryLoaded( const wxString& aLibrary ) const;
167 
171  bool IsLibraryModified( const wxString& aLibrary ) const;
172 
176  bool IsSymbolModified( const wxString& aAlias, const wxString& aLibrary ) const;
177 
181  bool ClearLibraryModified( const wxString& aLibrary ) const;
182 
186  bool ClearSymbolModified( const wxString& aAlias, const wxString& aLibrary ) const;
187 
193  bool IsLibraryReadOnly( const wxString& aLibrary ) const;
194 
201  bool FlushSymbol( const wxString& aAlias, const wxString& aLibrary );
202 
210  bool SaveLibrary( const wxString& aLibrary, const wxString& aFileName,
211  SCH_IO_MGR::SCH_FILE_T aFileType = SCH_IO_MGR::SCH_FILE_T::SCH_LEGACY );
212 
219  LIB_ID RevertSymbol( const wxString& aAlias, const wxString& aLibrary );
220 
226  bool RevertLibrary( const wxString& aLibrary );
227 
233  bool RevertAll();
234 
239  wxString GetUniqueLibraryName() const;
240 
244  wxObjectDataPtr<LIB_TREE_MODEL_ADAPTER>& GetAdapter() { return m_adapter; }
245 
246  void GetRootSymbolNames( const wxString& aLibName, wxArrayString& aRootSymbolNames );
247 
254  bool HasDerivedSymbols( const wxString& aSymbolName, const wxString& aLibraryName );
255 
256  size_t GetLibraryCount() const;
257 
258 private:
260  static wxString getLibraryName( const wxString& aFilePath );
261 
263  bool addLibrary( const wxString& aFilePath, bool aCreate, SYMBOL_LIB_TABLE* aTable );
264 
266  SYMBOL_LIB_TABLE* symTable() const;
267 
269  {
270  return static_cast<SYMBOL_TREE_SYNCHRONIZING_ADAPTER*>( m_adapter.get() );
271  }
272 
275  {
276  public:
277  SYMBOL_BUFFER( LIB_SYMBOL* aSymbol = nullptr,
278  std::unique_ptr<SCH_SCREEN> aScreen = nullptr );
279  ~SYMBOL_BUFFER();
280 
281  LIB_SYMBOL* GetSymbol() const { return m_symbol; }
282  void SetSymbol( LIB_SYMBOL* aSymbol );
283 
284  LIB_SYMBOL* GetOriginal() const { return m_original; }
285  void SetOriginal( LIB_SYMBOL* aSymbol );
286 
287  bool IsModified() const;
288  SCH_SCREEN* GetScreen() const { return m_screen.get(); }
289 
291  std::unique_ptr<SCH_SCREEN> RemoveScreen()
292  {
293  return std::move( m_screen );
294  }
295 
296  bool SetScreen( std::unique_ptr<SCH_SCREEN> aScreen )
297  {
298  bool ret = !!m_screen;
299  m_screen = std::move( aScreen );
300  return ret;
301  }
302 
303  private:
304  std::unique_ptr<SCH_SCREEN> m_screen;
305 
306  LIB_SYMBOL* m_symbol; // Working copy
307  LIB_SYMBOL* m_original; // Initial state of the symbol
308  };
309 
310 
313  {
314  public:
315  LIB_BUFFER( const wxString& aLibrary ) :
316  m_libName( aLibrary ),
317  m_hash( 1 )
318  { }
319 
320  bool IsModified() const
321  {
322  if( !m_deleted.empty() )
323  return true;
324 
325  for( const std::shared_ptr<SYMBOL_BUFFER>& symbolBuf : m_symbols )
326  {
327  if( symbolBuf->IsModified() )
328  return true;
329  }
330 
331  return false;
332  }
333 
334  int GetHash() const { return m_hash; }
335 
337  LIB_SYMBOL* GetSymbol( const wxString& aAlias ) const;
338 
340  bool CreateBuffer( LIB_SYMBOL* aCopy, SCH_SCREEN* aScreen );
341 
343  bool UpdateBuffer( std::shared_ptr<SYMBOL_BUFFER> aSymbolBuf, LIB_SYMBOL* aCopy );
344 
345  bool DeleteBuffer( std::shared_ptr<SYMBOL_BUFFER> aSymbolBuf );
346 
348  {
349  m_deleted.clear();
350  }
351 
354  bool SaveBuffer( std::shared_ptr<SYMBOL_BUFFER> aSymbolBuf, SYMBOL_LIB_TABLE* aLibTable );
355 
358  bool SaveBuffer( std::shared_ptr<SYMBOL_BUFFER> aSymbolBuf, const wxString& aFileName,
359  SCH_PLUGIN* aPlugin, bool aBuffer );
360 
362  std::shared_ptr<SYMBOL_BUFFER> GetBuffer( const wxString& aAlias ) const;
363 
365  const std::deque< std::shared_ptr<SYMBOL_BUFFER> >& GetBuffers() const { return m_symbols; }
366 
374  bool HasDerivedSymbols( const wxString& aParentName ) const;
375 
381  void GetRootSymbolNames( wxArrayString& aRootSymbolNames );
382 
391  size_t GetDerivedSymbolNames( const wxString& aSymbolName, wxArrayString& aList );
392 
393  private:
400  int removeChildSymbols( std::shared_ptr<SYMBOL_BUFFER> aSymbolBuf );
401 
402  std::deque< std::shared_ptr<SYMBOL_BUFFER> > m_symbols;
403 
405  std::deque< std::shared_ptr<SYMBOL_BUFFER> > m_deleted;
406  const wxString m_libName; // Buffered library name
407  int m_hash;
408  };
409 
413  std::set<LIB_SYMBOL*> getOriginalSymbols( const wxString& aLibrary );
414 
419  LIB_BUFFER& getLibraryBuffer( const wxString& aLibrary );
420 
422  std::map<wxString, LIB_BUFFER> m_libs;
423 
427 
428  wxObjectDataPtr<LIB_TREE_MODEL_ADAPTER> m_adapter;
429 };
430 
431 #endif /* SYMBOL_LIBRARY_MANAGER_H */
std::deque< std::shared_ptr< SYMBOL_BUFFER > > m_deleted
bool UpdateBuffer(std::shared_ptr< SYMBOL_BUFFER > aSymbolBuf, LIB_SYMBOL *aCopy)
const std::deque< std::shared_ptr< SYMBOL_BUFFER > > & GetBuffers() const
Hold a record identifying a symbol library accessed by the appropriate symbol library SCH_PLUGIN obje...
void GetRootSymbolNames(const wxString &aLibName, wxArrayString &aRootSymbolNames)
bool SaveBuffer(std::shared_ptr< SYMBOL_BUFFER > aSymbolBuf, SYMBOL_LIB_TABLE *aLibTable)
Save stored modifications using a plugin.
Store a working copy of a library.
Object used to load, save, search, and otherwise manipulate symbol library files.
bool ClearLibraryModified(const wxString &aLibrary) const
Clear the modified flag for all symbols in a library.
bool AddLibrary(const wxString &aFilePath, SYMBOL_LIB_TABLE *aTable)
Add an existing library.
A progress reporter interface for use in multi-threaded environments.
SYMBOL_LIBRARY_MANAGER(SYMBOL_EDIT_FRAME &aFrame)
LIB_SYMBOL * GetBufferedSymbol(const wxString &aAlias, const wxString &aLibrary)
Return the symbol copy from the buffer.
bool SaveLibrary(const wxString &aLibrary, const wxString &aFileName, SCH_IO_MGR::SCH_FILE_T aFileType=SCH_IO_MGR::SCH_FILE_T::SCH_LEGACY)
Save library to a file, including unsaved changes.
static wxString getLibraryName(const wxString &aFilePath)
< Extract library name basing on the file name.
SYMBOL_LIB_TABLE * symTable() const
bool RemoveSymbol(const wxString &aName, const wxString &aLibrary)
Remove the symbol from the symbol buffer.
LIB_SYMBOL * GetSymbol(const wxString &aAlias) const
Create a new buffer to store a symbol. LIB_BUFFER takes ownership of aCopy.
int GetHash() const
Return the working copy of a LIB_SYMBOL root object with specified alias.
A logical library item identifier and consists of various portions much like a URI.
Definition: lib_id.h:51
SYMBOL_EDIT_FRAME & m_frame
Parent frame.
Define a library symbol object.
Definition: lib_symbol.h:96
LIB_ID RevertSymbol(const wxString &aAlias, const wxString &aLibrary)
Revert unsaved changes for a symbolicular symbol.
std::unique_ptr< SCH_SCREEN > RemoveScreen()
bool RevertLibrary(const wxString &aLibrary)
Revert unsaved changes for a symbolicular library.
LIB_BUFFER & getLibraryBuffer(const wxString &aLibrary)
Return an existing library buffer or creates one to using Symbol Library Table to get the original da...
bool addLibrary(const wxString &aFilePath, bool aCreate, SYMBOL_LIB_TABLE *aTable)
Return the current Symbol Library Table.
bool FlushSymbol(const wxString &aAlias, const wxString &aLibrary)
Save symbol changes to the library copy used by the schematic editor.
bool SymbolExists(const wxString &aAlias, const wxString &aLibrary) const
Return true if symbol with a specific alias exists in library (either original one or buffered).
Base class that schematic file and library loading and saving plugins should derive from.
Definition: sch_io_mgr.h:152
wxObjectDataPtr< LIB_TREE_MODEL_ADAPTER > m_adapter
bool RevertAll()
Revert all pending changes.
wxString GetUniqueLibraryName() const
Return a library name that is not currently in use.
SCH_SCREEN * GetScreen() const
Transfer the screen ownership.
SYMBOL_LIB_TABLE_ROW * GetLibrary(const wxString &aLibrary) const
Find a single library within the (aggregate) library table.
int GetLibraryHash(const wxString &aLibrary) const
Return a library hash value to determine if it has changed.
Class to handle modifications to the symbol libraries.
void ClearDeletedBuffer()
Save stored modifications to Symbol Lib Table.
bool IsLibraryReadOnly(const wxString &aLibrary) const
Return true if the library is stored in a read-only file.
bool IsSymbolModified(const wxString &aAlias, const wxString &aLibrary) const
Return true if symbol has unsaved modifications.
std::unique_ptr< SCH_SCREEN > m_screen
std::map< wxString, LIB_BUFFER > m_libs
SYMBOL_TREE_SYNCHRONIZING_ADAPTER * getAdapter()
Class to store a working copy of a LIB_SYMBOL object and editor context.
bool HasDerivedSymbols(const wxString &aSymbolName, const wxString &aLibraryName)
Check if symbol aSymbolName in library aLibraryName is a root symbol that has derived symbols.
void Sync(const wxString &aForceRefresh, std::function< void(int, int, const wxString &)> aProgressCallback)
Updates the SYMBOL_LIBRARY_MANAGER data to synchronize with Symbol Library Table.
void Preload(PROGRESS_REPORTER &aReporter)
Preloads all symbol libraries in the symbol library table using SYMBOL_ASYNC_LOADER.
SYMBOL_BUFFER(LIB_SYMBOL *aSymbol=nullptr, std::unique_ptr< SCH_SCREEN > aScreen=nullptr)
void GetRootSymbolNames(wxArrayString &aRootSymbolNames)
Fetch a list of root symbols names from the library buffer.
wxArrayString GetLibraryNames() const
Return the array of library names.
bool ClearSymbolModified(const wxString &aAlias, const wxString &aLibrary) const
Clear the modified flag for a symbol.
bool IsLibraryModified(const wxString &aLibrary) const
Return true if library has unsaved modifications.
bool LibraryExists(const wxString &aLibrary, bool aCheckEnabled=false) const
Return true if library exists.
std::set< LIB_SYMBOL * > getOriginalSymbols(const wxString &aLibrary)
Return a set of LIB_SYMBOL objects belonging to the original library.
std::shared_ptr< SYMBOL_BUFFER > GetBuffer(const wxString &aAlias) const
Return all buffered symbols.
wxObjectDataPtr< LIB_TREE_MODEL_ADAPTER > & GetAdapter()
Return the adapter object that provides the stored data.
bool IsLibraryLoaded(const wxString &aLibrary) const
Return true if the library was successfully loaded.
size_t GetDerivedSymbolNames(const wxString &aSymbolName, wxArrayString &aList)
Fetch all of the symbols derived from a aSymbolName into aList.
int m_syncHash
Symbol lib table hash value from last synchronization.
LIB_SYMBOL * GetAlias(const wxString &aAlias, const wxString &aLibrary) const
Return either an alias of a working LIB_SYMBOL copy, or alias of the original symbol if there is no w...
bool UpdateSymbol(LIB_SYMBOL *aSymbol, const wxString &aLibrary)
Update the symbol buffer with a new version of the symbol.
SCH_SCREEN * GetScreen(const wxString &aAlias, const wxString &aLibrary)
Return the screen used to edit a specific symbol.
bool CreateLibrary(const wxString &aFilePath, SYMBOL_LIB_TABLE *aTable)
Create an empty library and adds it to the library table.
bool SetScreen(std::unique_ptr< SCH_SCREEN > aScreen)
bool HasDerivedSymbols(const wxString &aParentName) const
Check to see any symbols in the buffer are derived from a parent named aParentName.
std::deque< std::shared_ptr< SYMBOL_BUFFER > > m_symbols
Buffer for deleted symbols until library is saved.
bool CreateBuffer(LIB_SYMBOL *aCopy, SCH_SCREEN *aScreen)
Update the buffered symbol with the contents of aCopy.
bool DeleteBuffer(std::shared_ptr< SYMBOL_BUFFER > aSymbolBuf)
int removeChildSymbols(std::shared_ptr< SYMBOL_BUFFER > aSymbolBuf)
Remove all symbols derived from aParent from the library buffer.
std::list< LIB_SYMBOL * > GetAliases(const wxString &aLibrary) const
bool UpdateSymbolAfterRename(LIB_SYMBOL *aSymbol, const wxString &oldAlias, const wxString &aLibrary)
Update the symbol buffer with a new version of the symbol when the name has changed.
The symbol library editor main window.