KiCad PCB EDA Suite
io_mgr.h
Go to the documentation of this file.
1 #ifndef IO_MGR_H_
2 #define IO_MGR_H_
3 
4 /*
5  * This program source code file is part of KICAD, a free EDA CAD application.
6  *
7  * Copyright (C) 2011-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
8  * Copyright (C) 2016-2020 Kicad Developers, see AUTHORS.txt for contributors.
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License
12  * as published by the Free Software Foundation; either version 2
13  * of the License, or (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, you may find one here:
22  * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
23  * or you may search the http://www.gnu.org website for the version 2 license,
24  * or you may write to the Free Software Foundation, Inc.,
25  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
26  */
27 
28 #include <richio.h>
29 #include <map>
30 #include <functional>
31 #include <wx/time.h>
32 
33 #include <config.h>
34 
35 class BOARD;
36 class PLUGIN;
37 class FOOTPRINT;
38 class PROPERTIES;
39 class PROJECT;
40 class PROGRESS_REPORTER;
41 
45 class IO_MGR
46 {
47 public:
48 
54  {
65  // add your type here.
66 
67  // etc.
68 
70  };
71 
77  {
78  public:
79  struct ENTRY
80  {
82  std::function<PLUGIN*(void)> m_createFunc;
83  wxString m_name;
84  };
85 
87  {
88  static PLUGIN_REGISTRY *self = nullptr;
89 
90  if( !self )
91  {
92  self = new PLUGIN_REGISTRY;
93  }
94  return self;
95  }
96 
97  void Register( PCB_FILE_T aType, const wxString& aName,
98  std::function<PLUGIN*(void)> aCreateFunc )
99  {
100  ENTRY ent;
101  ent.m_type = aType;
102  ent.m_createFunc = aCreateFunc;
103  ent.m_name = aName;
104  m_plugins.push_back( ent );
105  }
106 
107  PLUGIN* Create( PCB_FILE_T aFileType ) const
108  {
109  for( auto& ent : m_plugins )
110  {
111  if ( ent.m_type == aFileType )
112  {
113  return ent.m_createFunc();
114  }
115  }
116 
117  return nullptr;
118  }
119 
120  const std::vector<ENTRY>& AllPlugins() const
121  {
122  return m_plugins;
123  }
124 
125  private:
126  std::vector<ENTRY> m_plugins;
127  };
128 
139  {
140  REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName,
141  std::function<PLUGIN*(void)> aCreateFunc )
142  {
143  PLUGIN_REGISTRY::Instance()->Register( aType, aName, aCreateFunc );
144  }
145  };
146 
147 
160  static PLUGIN* PluginFind( PCB_FILE_T aFileType );
161 
168  static void PluginRelease( PLUGIN* aPlugin );
169 
173  static const wxString ShowType( PCB_FILE_T aFileType );
174 
178  static PCB_FILE_T EnumFromStr( const wxString& aFileType );
179 
186  static const wxString GetFileExtension( PCB_FILE_T aFileType );
187 
191  static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
192 
212  static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
213  BOARD* aAppendToMe = nullptr, const PROPERTIES* aProperties = nullptr,
214  PROJECT* aProject = nullptr,
215  PROGRESS_REPORTER* aProgressReporter = nullptr );
216 
236  static void Save( PCB_FILE_T aFileType, const wxString& aFileName, BOARD* aBoard,
237  const PROPERTIES* aProperties = nullptr );
238 };
239 
240 
269 class PLUGIN
270 {
271 public:
275  virtual const wxString PluginName() const = 0;
276 
280  virtual const wxString GetFileExtension() const = 0;
281 
310  virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
311  const PROPERTIES* aProperties = nullptr, PROJECT* aProject = nullptr,
312  PROGRESS_REPORTER* aProgressReporter = nullptr );
313 
322  virtual std::vector<FOOTPRINT*> GetImportedCachedLibraryFootprints();
323 
342  virtual void Save( const wxString& aFileName, BOARD* aBoard,
343  const PROPERTIES* aProperties = nullptr );
344 
359  virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
360  bool aBestEfforts, const PROPERTIES* aProperties = nullptr );
361 
368  virtual long long GetLibraryTimestamp( const wxString& aLibraryPath ) const = 0;
369 
387  virtual void PrefetchLib( const wxString& aLibraryPath,
388  const PROPERTIES* aProperties = nullptr );
389 
411  virtual FOOTPRINT* FootprintLoad( const wxString& aLibraryPath,
412  const wxString& aFootprintName,
413  bool aKeepUUID = false,
414  const PROPERTIES* aProperties = nullptr );
415 
420  virtual const FOOTPRINT* GetEnumeratedFootprint( const wxString& aLibraryPath,
421  const wxString& aFootprintName,
422  const PROPERTIES* aProperties = nullptr );
423 
427  virtual bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
428  const PROPERTIES* aProperties = nullptr );
429 
446  virtual void FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
447  const PROPERTIES* aProperties = nullptr );
448 
463  virtual void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
464  const PROPERTIES* aProperties = nullptr );
465 
482  virtual void FootprintLibCreate( const wxString& aLibraryPath,
483  const PROPERTIES* aProperties = nullptr );
484 
501  virtual bool FootprintLibDelete( const wxString& aLibraryPath,
502  const PROPERTIES* aProperties = nullptr );
503 
514  virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
515 
543  virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
544 
545  virtual ~PLUGIN()
546  {
547  //printf( "~%s", __func__ );
548  };
549 
550 
551 #ifndef SWIG
552 
555  class RELEASER
556  {
558 
559  // private assignment operator so it's illegal
560  RELEASER& operator=( RELEASER& aOther ) { return *this; }
561 
562  // private copy constructor so it's illegal
563  RELEASER( const RELEASER& aOther ) : plugin( nullptr ) {}
564 
565  public:
566  RELEASER( PLUGIN* aPlugin = nullptr ) :
567  plugin( aPlugin )
568  {
569  }
570 
572  {
573  if( plugin )
574  release();
575  }
576 
577  void release()
578  {
580  plugin = nullptr;
581  }
582 
583  void set( PLUGIN* aPlugin )
584  {
585  if( plugin )
586  release();
587  plugin = aPlugin;
588  }
589 
590  operator PLUGIN* () const
591  {
592  return plugin;
593  }
594 
596  {
597  return plugin;
598  }
599  };
600 #endif
601 };
602 
603 #endif // IO_MGR_H_
virtual const FOOTPRINT * GetEnumeratedFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
A version of FootprintLoad() for use after FootprintEnumerate() for more efficient cache management.
Definition: plugin.cpp:80
void release()
Definition: io_mgr.h:577
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:107
Container for project specific data.
Definition: project.h:62
virtual void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
Create a new empty footprint library at aLibraryPath empty.
Definition: plugin.cpp:124
virtual long long GetLibraryTimestamp(const wxString &aLibraryPath) const =0
Generate a timestamp representing all the files in the library (including the library directory).
REGISTER_PLUGIN(PCB_FILE_T aType, const wxString &aName, std::function< PLUGIN *(void)> aCreateFunc)
Definition: io_mgr.h:140
RELEASER(const RELEASER &aOther)
Definition: io_mgr.h:563
virtual BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr, PROGRESS_REPORTER *aProgressReporter=nullptr)
Load information from some input file format that this PLUGIN implementation knows about into either ...
Definition: plugin.cpp:46
A progress reporter interface for use in multi-threaded environments.
virtual void FootprintLibOptions(PROPERTIES *aListToAppendTo) const
Append supported PLUGIN options to aListToAppenTo along with internationalized descriptions.
Definition: plugin.cpp:147
virtual FOOTPRINT * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, bool aKeepUUID=false, const PROPERTIES *aProperties=nullptr)
Load a footprint having aFootprintName from the aLibraryPath containing a library format that this PL...
Definition: plugin.cpp:97
static const wxString ShowType(PCB_FILE_T aFileType)
Return a brief name for a plugin given aFileType enum.
Definition: io_mgr.cpp:77
A name/value tuple with unique names and optional values.
Definition: properties.h:33
PLUGIN * operator ->() const
Definition: io_mgr.h:595
Geda PCB file formats.
Definition: io_mgr.h:64
static PCB_FILE_T GuessPluginTypeFromLibPath(const wxString &aLibPath)
Return a plugin type given a footprint library's libPath.
Definition: io_mgr.cpp:124
Hold a list of available plugins, created using a singleton REGISTER_PLUGIN object.
Definition: io_mgr.h:76
virtual bool IsFootprintLibWritable(const wxString &aLibraryPath)
Return true if the library at aLibraryPath is writable.
Definition: plugin.cpp:139
Releases a PLUGIN in the context of a potential thrown exception through its destructor.
Definition: io_mgr.h:555
A factory which returns an instance of a PLUGIN.
Definition: io_mgr.h:45
virtual std::vector< FOOTPRINT * > GetImportedCachedLibraryFootprints()
Return a container with the cached library footprints generated in the last call to Load.
Definition: plugin.cpp:54
std::vector< ENTRY > m_plugins
Definition: io_mgr.h:126
virtual void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, bool aBestEfforts, const PROPERTIES *aProperties=nullptr)
Return a list of footprint names contained within the library at aLibraryPath.
Definition: plugin.cpp:67
RELEASER(PLUGIN *aPlugin=nullptr)
Definition: io_mgr.h:566
virtual void FootprintDelete(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Delete aFootprintName from the library at aLibraryPath.
Definition: plugin.cpp:116
static PCB_FILE_T EnumFromStr(const wxString &aFileType)
Return the PCB_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
Definition: io_mgr.cpp:93
virtual void Save(const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=nullptr)
Write aBoard to a storage file in a format that this PLUGIN implementation knows about or it can be u...
Definition: plugin.cpp:60
virtual void PrefetchLib(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
If possible, prefetches the specified library (e.g.
Definition: plugin.cpp:75
RELEASER & operator=(RELEASER &aOther)
Definition: io_mgr.h:560
void set(PLUGIN *aPlugin)
Definition: io_mgr.h:583
virtual const wxString PluginName() const =0
Return a brief hard coded name for this PLUGIN.
virtual void FootprintSave(const wxString &aLibraryPath, const FOOTPRINT *aFootprint, const PROPERTIES *aProperties=nullptr)
Write aFootprint to an existing library located at aLibraryPath.
Definition: plugin.cpp:108
std::function< PLUGIN *(void)> m_createFunc
Definition: io_mgr.h:82
virtual const wxString GetFileExtension() const =0
Returns the file extension for the PLUGIN.
static void PluginRelease(PLUGIN *aPlugin)
Release a PLUGIN back to the system and may cause it to be unloaded from memory.
Definition: io_mgr.cpp:67
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:86
PLUGIN * plugin
Definition: io_mgr.h:557
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:55
static void Save(PCB_FILE_T aFileType, const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=nullptr)
Write either a full aBoard to a storage file in a format that this implementation knows about,...
Definition: io_mgr.cpp:174
Information pertinent to a Pcbnew printed circuit board.
Definition: board.h:190
static PLUGIN * PluginFind(PCB_FILE_T aFileType)
Return a PLUGIN which the caller can use to import, export, save, or load design documents.
Definition: io_mgr.cpp:58
A base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:269
static BOARD * Load(PCB_FILE_T aFileType, const wxString &aFileName, BOARD *aAppendToMe=nullptr, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr, PROGRESS_REPORTER *aProgressReporter=nullptr)
Find the requested PLUGIN and if found, calls the PLUGIN::Load() function on it using the arguments p...
Definition: io_mgr.cpp:158
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:120
PCB_FILE_T
The set of file types that the IO_MGR knows about, and for which there has been a plugin written.
Definition: io_mgr.h:53
virtual bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=nullptr)
Delete an existing footprint library and returns true, or if library does not exist returns false,...
Definition: plugin.cpp:131
virtual ~PLUGIN()
Definition: io_mgr.h:545
Register a plugin.
Definition: io_mgr.h:138
void Register(PCB_FILE_T aType, const wxString &aName, std::function< PLUGIN *(void)> aCreateFunc)
Definition: io_mgr.h:97
virtual bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Check for the existence of a footprint.
Definition: plugin.cpp:89
S-expression Pcbnew file format.
Definition: io_mgr.h:56
static const wxString GetFileExtension(PCB_FILE_T aFileType)
Return the file extension for aFileType.
Definition: io_mgr.cpp:109