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-2017 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 
32 class BOARD;
33 class PLUGIN;
34 class MODULE;
35 class PROPERTIES;
36 
37 
42 class IO_MGR
43 {
44 public:
45 
52  {
59 
60  // add your type here.
61 
62  // ALTIUM,
63  // etc.
64 
66  };
67 
74  {
75  public:
76  struct ENTRY
77  {
79  std::function<PLUGIN*(void)> m_createFunc;
80  wxString m_name;
81  };
82 
84  {
85  static PLUGIN_REGISTRY *self = nullptr;
86 
87  if( !self )
88  {
89  self = new PLUGIN_REGISTRY;
90  }
91  return self;
92  }
93 
94  void Register( PCB_FILE_T aType, const wxString& aName, std::function<PLUGIN*(void)> aCreateFunc )
95  {
96  ENTRY ent;
97  ent.m_type = aType;
98  ent.m_createFunc = aCreateFunc;
99  ent.m_name = aName;
100  m_plugins.push_back( ent );
101  }
102 
103  PLUGIN* Create( PCB_FILE_T aFileType ) const
104  {
105  for( auto& ent : m_plugins )
106  {
107  if ( ent.m_type == aFileType )
108  {
109  return ent.m_createFunc();
110  }
111  }
112  return nullptr;
113  }
114 
115  const std::vector<ENTRY>& AllPlugins() const
116  {
117  return m_plugins;
118  }
119 
120  private:
121  std::vector<ENTRY> m_plugins;
122  };
123 
132  {
133  REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName, std::function<PLUGIN*(void)> aCreateFunc )
134  {
135  PLUGIN_REGISTRY::Instance()->Register( aType, aName, aCreateFunc );
136  }
137  };
138 
139 
152  static PLUGIN* PluginFind( PCB_FILE_T aFileType );
153 
161  static void PluginRelease( PLUGIN* aPlugin );
162 
167  static const wxString ShowType( PCB_FILE_T aFileType );
168 
173  static PCB_FILE_T EnumFromStr( const wxString& aFileType );
174 
183  static const wxString GetFileExtension( PCB_FILE_T aFileType );
184 
189  static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
190 
212  static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
213  BOARD* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
214 
238  static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
239  BOARD* aBoard, const PROPERTIES* aProperties = NULL );
240 };
241 
242 
265 class PLUGIN
266 {
267 public:
268 
269  //-----<PUBLIC PLUGIN API>-------------------------------------------------
270 
275  virtual const wxString PluginName() const = 0;
276 
281  virtual const wxString GetFileExtension() const = 0;
282 
309  virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
310  const PROPERTIES* aProperties = NULL );
311 
332  virtual void Save( const wxString& aFileName, BOARD* aBoard,
333  const PROPERTIES* aProperties = NULL );
334 
335  //-----<Footprint Stuff>-----------------------------
336 
352  virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
353  const PROPERTIES* aProperties = NULL );
354 
374  virtual void PrefetchLib( const wxString& aLibraryPath,
375  const PROPERTIES* aProperties = NULL );
376 
398  virtual MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
399  const PROPERTIES* aProperties = NULL );
400 
420  virtual void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
421  const PROPERTIES* aProperties = NULL );
422 
440  virtual void FootprintDelete( const wxString& aLibraryPath,
441  const wxString& aFootprintName, const PROPERTIES* aProperties = NULL );
442 
460  virtual void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
461 
481  virtual bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
482 
493  virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
494 
521  virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
522 
523  //-----</PUBLIC PLUGIN API>------------------------------------------------
524 
525 
526  /* The compiler writes the "zero argument" constructor for a PLUGIN
527  automatically if you do not provide one. If you decide you need to
528  provide a zero argument constructor of your own design, that is allowed.
529  It must be public, and it is what the IO_MGR uses. Parameters may be
530  passed into a PLUGIN via the PROPERTIES variable for any of the public
531  API functions which take one.
532  */
533 
534  virtual ~PLUGIN()
535  {
536  //printf( "~%s", __func__ );
537  };
538 
539 
540 #ifndef SWIG
541 
546  class RELEASER
547  {
549 
550  // private assignment operator so it's illegal
551  RELEASER& operator=( RELEASER& aOther ) { return *this; }
552 
553  // private copy constructor so it's illegal
554  RELEASER( const RELEASER& aOther ) {}
555 
556  public:
557  RELEASER( PLUGIN* aPlugin = NULL ) :
558  plugin( aPlugin )
559  {
560  }
561 
563  {
564  if( plugin )
565  release();
566  }
567 
568  void release()
569  {
570  IO_MGR::PluginRelease( plugin );
571  plugin = NULL;
572  }
573 
574  void set( PLUGIN* aPlugin )
575  {
576  if( plugin )
577  release();
578  plugin = aPlugin;
579  }
580 
581  operator PLUGIN* () const
582  {
583  return plugin;
584  }
585 
587  {
588  return plugin;
589  }
590  };
591 #endif
592 };
593 
594 #endif // IO_MGR_H_
void release()
Definition: io_mgr.h:568
virtual void Save(const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=NULL)
Function Save will write aBoard to a storage file in a format that this PLUGIN implementation knows a...
Definition: plugin.cpp:54
virtual void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Return a list of footprint names contained within the library at aLibraryPath.
Definition: plugin.cpp:61
virtual void PrefetchLib(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function PrefetchLib If possible, prefetches the specified library (e.g.
Definition: plugin.cpp:69
RELEASER(PLUGIN *aPlugin=NULL)
Definition: io_mgr.h:557
RELEASER(const RELEASER &aOther)
Definition: io_mgr.h:554
virtual void FootprintSave(const wxString &aLibraryPath, const MODULE *aFootprint, const PROPERTIES *aProperties=NULL)
Function FootprintSave will write aModule to an existing library located at aLibraryPath.
Definition: plugin.cpp:85
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:115
static const wxString ShowType(PCB_FILE_T aFileType)
Function ShowType returns a brief name for a plugin, given aFileType enum.
Definition: io_mgr.cpp:77
Class PROPERTIES is a name/value tuple with unique names and optional values.
Definition: properties.h:34
PLUGIN * operator->() const
Definition: io_mgr.h:586
Geda PCB file formats.
Definition: io_mgr.h:57
static PCB_FILE_T GuessPluginTypeFromLibPath(const wxString &aLibPath)
Function GuessPluginTypeFromLibPath returns a plugin type given a footprint library's libPath...
Definition: io_mgr.cpp:132
Class PLUGIN_REGISTRY Holds a list of available plugins, created using a singleton REGISTER_PLUGIN ob...
Definition: io_mgr.h:73
virtual bool IsFootprintLibWritable(const wxString &aLibraryPath)
Function IsFootprintLibWritable returns true iff the library at aLibraryPath is writable.
Definition: plugin.cpp:114
Class RELEASER releases a PLUGIN in the context of a potential thrown exception, through its destruct...
Definition: io_mgr.h:546
Class IO_MGR is a factory which returns an instance of a PLUGIN.
Definition: io_mgr.h:42
std::vector< ENTRY > m_plugins
Definition: io_mgr.h:121
virtual MODULE * FootprintLoad(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL)
Function FootprintLoad loads a footprint having aFootprintName from the aLibraryPath containing a lib...
Definition: plugin.cpp:76
virtual bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function FootprintLibDelete deletes an existing footprint library and returns true, or if library does not exist returns false, or throws an exception if library exists but is read only or cannot be deleted for some other reason.
Definition: plugin.cpp:106
static PCB_FILE_T EnumFromStr(const wxString &aFileType)
Function EnumFromStr returns the PCB_FILE_T from the corresponding plugin type name: "kicad"...
Definition: io_mgr.cpp:97
static BOARD * Load(PCB_FILE_T aFileType, const wxString &aFileName, BOARD *aAppendToMe=NULL, const PROPERTIES *aProperties=NULL)
Function Load finds the requested PLUGIN and if found, calls the PLUGIN->Load(..) funtion on it using...
Definition: io_mgr.cpp:179
RELEASER & operator=(RELEASER &aOther)
Definition: io_mgr.h:551
void set(PLUGIN *aPlugin)
Definition: io_mgr.h:574
virtual const wxString PluginName() const =0
Function PluginName returns a brief hard coded name for this PLUGIN.
std::function< PLUGIN *(void)> m_createFunc
Definition: io_mgr.h:79
virtual const wxString GetFileExtension() const =0
Function GetFileExtension returns the file extension for the PLUGIN.
static void Save(PCB_FILE_T aFileType, const wxString &aFileName, BOARD *aBoard, const PROPERTIES *aProperties=NULL)
Function Save will write either a full aBoard to a storage file in a format that this implementation ...
Definition: io_mgr.cpp:194
static void PluginRelease(PLUGIN *aPlugin)
Function PluginRelease releases a PLUGIN back to the system, and may cause it to be unloaded from mem...
Definition: io_mgr.cpp:67
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:83
PLUGIN * plugin
Definition: io_mgr.h:548
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:53
Class BOARD holds information pertinent to a Pcbnew printed circuit board.
Definition: class_board.h:169
static PLUGIN * PluginFind(PCB_FILE_T aFileType)
Function PluginFind returns a PLUGIN which the caller can use to import, export, save, or load design documents.
Definition: io_mgr.cpp:58
Class PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:265
virtual void FootprintDelete(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL)
Function FootprintDelete deletes aFootprintName from the library at aLibraryPath. ...
Definition: plugin.cpp:92
virtual void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function FootprintLibCreate creates a new empty footprint library at aLibraryPath empty...
Definition: plugin.cpp:99
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:103
PCB_FILE_T
Enum PCB_FILE_T is a set of file types that the IO_MGR knows about, and for which there has been a pl...
Definition: io_mgr.h:51
virtual ~PLUGIN()
Definition: io_mgr.h:534
virtual void FootprintLibOptions(PROPERTIES *aListToAppendTo) const
Function FootprintLibOptions appends supported PLUGIN options to aListToAppenTo along with internatio...
Definition: plugin.cpp:122
Read only http://github.com repo holding pretty footprints.
Definition: io_mgr.h:58
Class REGISTER_PLUGIN Registers a plugin.
Definition: io_mgr.h:131
void Register(PCB_FILE_T aType, const wxString &aName, std::function< PLUGIN *(void)> aCreateFunc)
Definition: io_mgr.h:94
virtual BOARD * Load(const wxString &aFileName, BOARD *aAppendToMe, const PROPERTIES *aProperties=NULL)
Function Load loads information from some input file format that this PLUGIN implementation knows abo...
Definition: plugin.cpp:47
S-expression Pcbnew file format.
Definition: io_mgr.h:54
static const wxString GetFileExtension(PCB_FILE_T aFileType)
Function GetFileExtension returns the file extension for aFileType.
Definition: io_mgr.cpp:117