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 #include <wx/time.h>
32 
33 #include <config.h>
34 
35 class BOARD;
36 class PLUGIN;
37 class MODULE;
38 class PROPERTIES;
39 
40 
45 class IO_MGR
46 {
47 public:
48 
55  {
61 
62  //N.B. This needs to be commented out to ensure compile-type errors
63 #if defined(BUILD_GITHUB_PLUGIN)
64  GITHUB,
65 #endif
66  // add your type here.
67 
68  // ALTIUM,
69  // etc.
70 
72  };
73 
80  {
81  public:
82  struct ENTRY
83  {
85  std::function<PLUGIN*(void)> m_createFunc;
86  wxString m_name;
87  };
88 
90  {
91  static PLUGIN_REGISTRY *self = nullptr;
92 
93  if( !self )
94  {
95  self = new PLUGIN_REGISTRY;
96  }
97  return self;
98  }
99 
100  void Register( PCB_FILE_T aType, const wxString& aName, std::function<PLUGIN*(void)> aCreateFunc )
101  {
102  ENTRY ent;
103  ent.m_type = aType;
104  ent.m_createFunc = aCreateFunc;
105  ent.m_name = aName;
106  m_plugins.push_back( ent );
107  }
108 
109  PLUGIN* Create( PCB_FILE_T aFileType ) const
110  {
111  for( auto& ent : m_plugins )
112  {
113  if ( ent.m_type == aFileType )
114  {
115  return ent.m_createFunc();
116  }
117  }
118  return nullptr;
119  }
120 
121  const std::vector<ENTRY>& AllPlugins() const
122  {
123  return m_plugins;
124  }
125 
126  private:
127  std::vector<ENTRY> m_plugins;
128  };
129 
138  {
139  REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName, std::function<PLUGIN*(void)> aCreateFunc )
140  {
141  PLUGIN_REGISTRY::Instance()->Register( aType, aName, aCreateFunc );
142  }
143  };
144 
145 
158  static PLUGIN* PluginFind( PCB_FILE_T aFileType );
159 
167  static void PluginRelease( PLUGIN* aPlugin );
168 
173  static const wxString ShowType( PCB_FILE_T aFileType );
174 
179  static PCB_FILE_T EnumFromStr( const wxString& aFileType );
180 
189  static const wxString GetFileExtension( PCB_FILE_T aFileType );
190 
195  static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
196 
218  static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
219  BOARD* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
220 
244  static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
245  BOARD* aBoard, const PROPERTIES* aProperties = NULL );
246 };
247 
248 
271 class PLUGIN
272 {
273 public:
274 
275  //-----<PUBLIC PLUGIN API>-------------------------------------------------
276 
281  virtual const wxString PluginName() const = 0;
282 
287  virtual const wxString GetFileExtension() const = 0;
288 
315  virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
316  const PROPERTIES* aProperties = NULL );
317 
338  virtual void Save( const wxString& aFileName, BOARD* aBoard,
339  const PROPERTIES* aProperties = NULL );
340 
341  //-----<Footprint Stuff>-----------------------------
342 
358  virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
359  const PROPERTIES* aProperties = NULL );
360 
366  virtual long long GetLibraryTimestamp( const wxString& aLibraryPath ) const = 0;
367 
387  virtual void PrefetchLib( const wxString& aLibraryPath,
388  const PROPERTIES* aProperties = NULL );
389 
411  virtual MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
412  const PROPERTIES* aProperties = NULL );
413 
419  virtual const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
420  const wxString& aFootprintName,
421  const PROPERTIES* aProperties = NULL );
422 
427  virtual bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
428  const PROPERTIES* aProperties = NULL );
429 
449  virtual void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
450  const PROPERTIES* aProperties = NULL );
451 
469  virtual void FootprintDelete( const wxString& aLibraryPath,
470  const wxString& aFootprintName, const PROPERTIES* aProperties = NULL );
471 
489  virtual void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
490 
510  virtual bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
511 
522  virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
523 
550  virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
551 
552  //-----</PUBLIC PLUGIN API>------------------------------------------------
553 
554 
555  /* The compiler writes the "zero argument" constructor for a PLUGIN
556  automatically if you do not provide one. If you decide you need to
557  provide a zero argument constructor of your own design, that is allowed.
558  It must be public, and it is what the IO_MGR uses. Parameters may be
559  passed into a PLUGIN via the PROPERTIES variable for any of the public
560  API functions which take one.
561  */
562 
563  virtual ~PLUGIN()
564  {
565  //printf( "~%s", __func__ );
566  };
567 
568 
569 #ifndef SWIG
570 
575  class RELEASER
576  {
578 
579  // private assignment operator so it's illegal
580  RELEASER& operator=( RELEASER& aOther ) { return *this; }
581 
582  // private copy constructor so it's illegal
583  RELEASER( const RELEASER& aOther ) {}
584 
585  public:
586  RELEASER( PLUGIN* aPlugin = NULL ) :
587  plugin( aPlugin )
588  {
589  }
590 
592  {
593  if( plugin )
594  release();
595  }
596 
597  void release()
598  {
600  plugin = NULL;
601  }
602 
603  void set( PLUGIN* aPlugin )
604  {
605  if( plugin )
606  release();
607  plugin = aPlugin;
608  }
609 
610  operator PLUGIN* () const
611  {
612  return plugin;
613  }
614 
616  {
617  return plugin;
618  }
619  };
620 #endif
621 };
622 
623 #endif // IO_MGR_H_
void release()
Definition: io_mgr.h:597
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:109
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:53
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:60
virtual long long GetLibraryTimestamp(const wxString &aLibraryPath) const =0
Generate a timestamp representing all the files in the library (including the library directory).
virtual void PrefetchLib(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function PrefetchLib If possible, prefetches the specified library (e.g.
Definition: plugin.cpp:68
RELEASER(PLUGIN *aPlugin=NULL)
Definition: io_mgr.h:586
RELEASER(const RELEASER &aOther)
Definition: io_mgr.h:583
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:101
virtual const MODULE * GetEnumeratedFootprint(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL)
Function GetEnumeratedFootprint a version of FootprintLoad() for use after FootprintEnumerate() for m...
Definition: plugin.cpp:75
virtual void FootprintLibOptions(PROPERTIES *aListToAppendTo) const
Function FootprintLibOptions appends supported PLUGIN options to aListToAppenTo along with internatio...
Definition: plugin.cpp:140
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:615
Geda PCB file formats.
Definition: io_mgr.h:60
static PCB_FILE_T GuessPluginTypeFromLibPath(const wxString &aLibPath)
Function GuessPluginTypeFromLibPath returns a plugin type given a footprint library's libPath.
Definition: io_mgr.cpp:124
Class PLUGIN_REGISTRY Holds a list of available plugins, created using a singleton REGISTER_PLUGIN ob...
Definition: io_mgr.h:79
virtual bool IsFootprintLibWritable(const wxString &aLibraryPath)
Function IsFootprintLibWritable returns true iff the library at aLibraryPath is writable.
Definition: plugin.cpp:132
Class RELEASER releases a PLUGIN in the context of a potential thrown exception, through its destruct...
Definition: io_mgr.h:575
Class IO_MGR is a factory which returns an instance of a PLUGIN.
Definition: io_mgr.h:45
std::vector< ENTRY > m_plugins
Definition: io_mgr.h:127
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:92
virtual bool FootprintLibDelete(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function FootprintLibDelete deletes an existing footprint library and returns true,...
Definition: plugin.cpp:124
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:93
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:173
RELEASER & operator=(RELEASER &aOther)
Definition: io_mgr.h:580
void set(PLUGIN *aPlugin)
Definition: io_mgr.h:603
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:85
virtual bool FootprintExists(const wxString &aLibraryPath, const wxString &aFootprintName, const PROPERTIES *aProperties=NULL)
Function FootprintExists check for the existence of a footprint.
Definition: plugin.cpp:84
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:188
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:89
PLUGIN * plugin
Definition: io_mgr.h:577
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:56
Class BOARD holds information pertinent to a Pcbnew printed circuit board.
Definition: class_board.h:161
static PLUGIN * PluginFind(PCB_FILE_T aFileType)
Function PluginFind returns a PLUGIN which the caller can use to import, export, save,...
Definition: io_mgr.cpp:58
Class PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:271
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:109
virtual void FootprintLibCreate(const wxString &aLibraryPath, const PROPERTIES *aProperties=NULL)
Function FootprintLibCreate creates a new empty footprint library at aLibraryPath empty.
Definition: plugin.cpp:117
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:121
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:54
virtual ~PLUGIN()
Definition: io_mgr.h:563
Class REGISTER_PLUGIN Registers 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:100
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:46
S-expression Pcbnew file format.
Definition: io_mgr.h:57
static const wxString GetFileExtension(PCB_FILE_T aFileType)
Function GetFileExtension returns the file extension for aFileType.
Definition: io_mgr.cpp:109