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 
44 class IO_MGR
45 {
46 public:
47 
53  {
64  // add your type here.
65 
66  // etc.
67 
69  };
70 
76  {
77  public:
78  struct ENTRY
79  {
81  std::function<PLUGIN*(void)> m_createFunc;
82  wxString m_name;
83  };
84 
86  {
87  static PLUGIN_REGISTRY *self = nullptr;
88 
89  if( !self )
90  {
91  self = new PLUGIN_REGISTRY;
92  }
93  return self;
94  }
95 
96  void Register( PCB_FILE_T aType, const wxString& aName,
97  std::function<PLUGIN*(void)> aCreateFunc )
98  {
99  ENTRY ent;
100  ent.m_type = aType;
101  ent.m_createFunc = aCreateFunc;
102  ent.m_name = aName;
103  m_plugins.push_back( ent );
104  }
105 
106  PLUGIN* Create( PCB_FILE_T aFileType ) const
107  {
108  for( auto& ent : m_plugins )
109  {
110  if ( ent.m_type == aFileType )
111  {
112  return ent.m_createFunc();
113  }
114  }
115 
116  return nullptr;
117  }
118 
119  const std::vector<ENTRY>& AllPlugins() const
120  {
121  return m_plugins;
122  }
123 
124  private:
125  std::vector<ENTRY> m_plugins;
126  };
127 
138  {
139  REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName,
140  std::function<PLUGIN*(void)> aCreateFunc )
141  {
142  PLUGIN_REGISTRY::Instance()->Register( aType, aName, aCreateFunc );
143  }
144  };
145 
146 
159  static PLUGIN* PluginFind( PCB_FILE_T aFileType );
160 
167  static void PluginRelease( PLUGIN* aPlugin );
168 
172  static const wxString ShowType( PCB_FILE_T aFileType );
173 
177  static PCB_FILE_T EnumFromStr( const wxString& aFileType );
178 
185  static const wxString GetFileExtension( PCB_FILE_T aFileType );
186 
190  static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
191 
211  static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
212  BOARD* aAppendToMe = nullptr, const PROPERTIES* aProperties = nullptr,
213  PROJECT* aProject = nullptr );
214 
234  static void Save( PCB_FILE_T aFileType, const wxString& aFileName, BOARD* aBoard,
235  const PROPERTIES* aProperties = nullptr );
236 };
237 
238 
267 class PLUGIN
268 {
269 public:
273  virtual const wxString PluginName() const = 0;
274 
278  virtual const wxString GetFileExtension() const = 0;
279 
306  virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
307  const PROPERTIES* aProperties = nullptr, PROJECT* aProject = nullptr );
308 
317  virtual std::vector<FOOTPRINT*> GetImportedCachedLibraryFootprints();
318 
337  virtual void Save( const wxString& aFileName, BOARD* aBoard,
338  const PROPERTIES* aProperties = nullptr );
339 
354  virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
355  bool aBestEfforts, const PROPERTIES* aProperties = nullptr );
356 
363  virtual long long GetLibraryTimestamp( const wxString& aLibraryPath ) const = 0;
364 
382  virtual void PrefetchLib( const wxString& aLibraryPath,
383  const PROPERTIES* aProperties = nullptr );
384 
403  virtual FOOTPRINT* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
404  const PROPERTIES* aProperties = nullptr );
405 
410  virtual const FOOTPRINT* GetEnumeratedFootprint( const wxString& aLibraryPath,
411  const wxString& aFootprintName,
412  const PROPERTIES* aProperties = nullptr );
413 
417  virtual bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
418  const PROPERTIES* aProperties = nullptr );
419 
436  virtual void FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
437  const PROPERTIES* aProperties = nullptr );
438 
453  virtual void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
454  const PROPERTIES* aProperties = nullptr );
455 
472  virtual void FootprintLibCreate( const wxString& aLibraryPath,
473  const PROPERTIES* aProperties = nullptr );
474 
491  virtual bool FootprintLibDelete( const wxString& aLibraryPath,
492  const PROPERTIES* aProperties = nullptr );
493 
504  virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
505 
533  virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
534 
535  virtual ~PLUGIN()
536  {
537  //printf( "~%s", __func__ );
538  };
539 
540 
541 #ifndef SWIG
542 
545  class RELEASER
546  {
548 
549  // private assignment operator so it's illegal
550  RELEASER& operator=( RELEASER& aOther ) { return *this; }
551 
552  // private copy constructor so it's illegal
553  RELEASER( const RELEASER& aOther ) : plugin( nullptr ) {}
554 
555  public:
556  RELEASER( PLUGIN* aPlugin = nullptr ) :
557  plugin( aPlugin )
558  {
559  }
560 
562  {
563  if( plugin )
564  release();
565  }
566 
567  void release()
568  {
570  plugin = nullptr;
571  }
572 
573  void set( PLUGIN* aPlugin )
574  {
575  if( plugin )
576  release();
577  plugin = aPlugin;
578  }
579 
580  operator PLUGIN* () const
581  {
582  return plugin;
583  }
584 
586  {
587  return plugin;
588  }
589  };
590 #endif
591 };
592 
593 #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:82
void release()
Definition: io_mgr.h:567
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:106
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:139
RELEASER(const RELEASER &aOther)
Definition: io_mgr.h:553
virtual void FootprintLibOptions(PROPERTIES *aListToAppendTo) const
Append supported PLUGIN options to aListToAppenTo along with internationalized descriptions.
Definition: plugin.cpp:147
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:585
Geda PCB file formats.
Definition: io_mgr.h:63
static PCB_FILE_T GuessPluginTypeFromLibPath(const wxString &aLibPath)
Return a plugin type given a footprint library's libPath.
Definition: io_mgr.cpp:124
virtual BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr)
Load information from some input file format that this PLUGIN implementation knows about into either ...
Definition: plugin.cpp:46
Hold a list of available plugins, created using a singleton REGISTER_PLUGIN object.
Definition: io_mgr.h:75
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:545
A factory which returns an instance of a PLUGIN.
Definition: io_mgr.h:44
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:125
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:556
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:550
void set(PLUGIN *aPlugin)
Definition: io_mgr.h:573
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
static BOARD * Load(PCB_FILE_T aFileType, const wxString &aFileName, BOARD *aAppendToMe=nullptr, const PROPERTIES *aProperties=nullptr, PROJECT *aProject=nullptr)
Find the requested PLUGIN and if found, calls the PLUGIN::Load() function on it using the arguments p...
Definition: io_mgr.cpp:158
std::function< PLUGIN *(void)> m_createFunc
Definition: io_mgr.h:81
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:85
PLUGIN * plugin
Definition: io_mgr.h:547
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:54
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:173
Information pertinent to a Pcbnew printed circuit board.
Definition: board.h:189
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:267
virtual FOOTPRINT * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Load a footprint having aFootprintName from the aLibraryPath containing a library format that this PL...
Definition: plugin.cpp:99
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:119
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:52
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:535
Register a plugin.
Definition: io_mgr.h:137
void Register(PCB_FILE_T aType, const wxString &aName, std::function< PLUGIN *(void)> aCreateFunc)
Definition: io_mgr.h:96
virtual bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=nullptr)
Check for the existence of a footprint.
Definition: plugin.cpp:91
S-expression Pcbnew file format.
Definition: io_mgr.h:55
static const wxString GetFileExtension(PCB_FILE_T aFileType)
Return the file extension for aFileType.
Definition: io_mgr.cpp:109