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  {
64 
65  //N.B. This needs to be commented out to ensure compile-type errors
66 #if defined(BUILD_GITHUB_PLUGIN)
67  GITHUB,
68 #endif
69  // add your type here.
70 
71  // etc.
72 
74  };
75 
82  {
83  public:
84  struct ENTRY
85  {
87  std::function<PLUGIN*(void)> m_createFunc;
88  wxString m_name;
89  };
90 
92  {
93  static PLUGIN_REGISTRY *self = nullptr;
94 
95  if( !self )
96  {
97  self = new PLUGIN_REGISTRY;
98  }
99  return self;
100  }
101 
102  void Register( PCB_FILE_T aType, const wxString& aName, std::function<PLUGIN*(void)> aCreateFunc )
103  {
104  ENTRY ent;
105  ent.m_type = aType;
106  ent.m_createFunc = aCreateFunc;
107  ent.m_name = aName;
108  m_plugins.push_back( ent );
109  }
110 
111  PLUGIN* Create( PCB_FILE_T aFileType ) const
112  {
113  for( auto& ent : m_plugins )
114  {
115  if ( ent.m_type == aFileType )
116  {
117  return ent.m_createFunc();
118  }
119  }
120  return nullptr;
121  }
122 
123  const std::vector<ENTRY>& AllPlugins() const
124  {
125  return m_plugins;
126  }
127 
128  private:
129  std::vector<ENTRY> m_plugins;
130  };
131 
140  {
141  REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName, 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 
169  static void PluginRelease( PLUGIN* aPlugin );
170 
175  static const wxString ShowType( PCB_FILE_T aFileType );
176 
181  static PCB_FILE_T EnumFromStr( const wxString& aFileType );
182 
191  static const wxString GetFileExtension( PCB_FILE_T aFileType );
192 
197  static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
198 
220  static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
221  BOARD* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
222 
246  static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
247  BOARD* aBoard, const PROPERTIES* aProperties = NULL );
248 };
249 
250 
273 class PLUGIN
274 {
275 public:
276 
277  //-----<PUBLIC PLUGIN API>-------------------------------------------------
278 
283  virtual const wxString PluginName() const = 0;
284 
289  virtual const wxString GetFileExtension() const = 0;
290 
317  virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
318  const PROPERTIES* aProperties = NULL );
319 
340  virtual void Save( const wxString& aFileName, BOARD* aBoard,
341  const PROPERTIES* aProperties = NULL );
342 
343  //-----<Footprint Stuff>-----------------------------
344 
362  virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
363  bool aBestEfforts, const PROPERTIES* aProperties = NULL );
364 
370  virtual long long GetLibraryTimestamp( const wxString& aLibraryPath ) const = 0;
371 
391  virtual void PrefetchLib( const wxString& aLibraryPath,
392  const PROPERTIES* aProperties = NULL );
393 
415  virtual MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
416  const PROPERTIES* aProperties = NULL );
417 
423  virtual const MODULE* GetEnumeratedFootprint( const wxString& aLibraryPath,
424  const wxString& aFootprintName,
425  const PROPERTIES* aProperties = NULL );
426 
431  virtual bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
432  const PROPERTIES* aProperties = NULL );
433 
453  virtual void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
454  const PROPERTIES* aProperties = NULL );
455 
473  virtual void FootprintDelete( const wxString& aLibraryPath,
474  const wxString& aFootprintName, const PROPERTIES* aProperties = NULL );
475 
493  virtual void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
494 
514  virtual bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
515 
526  virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
527 
554  virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
555 
556  //-----</PUBLIC PLUGIN API>------------------------------------------------
557 
558 
559  /* The compiler writes the "zero argument" constructor for a PLUGIN
560  automatically if you do not provide one. If you decide you need to
561  provide a zero argument constructor of your own design, that is allowed.
562  It must be public, and it is what the IO_MGR uses. Parameters may be
563  passed into a PLUGIN via the PROPERTIES variable for any of the public
564  API functions which take one.
565  */
566 
567  virtual ~PLUGIN()
568  {
569  //printf( "~%s", __func__ );
570  };
571 
572 
573 #ifndef SWIG
574 
579  class RELEASER
580  {
582 
583  // private assignment operator so it's illegal
584  RELEASER& operator=( RELEASER& aOther ) { return *this; }
585 
586  // private copy constructor so it's illegal
587  RELEASER( const RELEASER& aOther ) {}
588 
589  public:
590  RELEASER( PLUGIN* aPlugin = NULL ) :
591  plugin( aPlugin )
592  {
593  }
594 
596  {
597  if( plugin )
598  release();
599  }
600 
601  void release()
602  {
604  plugin = NULL;
605  }
606 
607  void set( PLUGIN* aPlugin )
608  {
609  if( plugin )
610  release();
611  plugin = aPlugin;
612  }
613 
614  operator PLUGIN* () const
615  {
616  return plugin;
617  }
618 
620  {
621  return plugin;
622  }
623  };
624 #endif
625 };
626 
627 #endif // IO_MGR_H_
void release()
Definition: io_mgr.h:601
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:111
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 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:590
RELEASER(const RELEASER &aOther)
Definition: io_mgr.h:587
virtual void FootprintEnumerate(wxArrayString &aFootprintNames, const wxString &aLibraryPath, bool aBestEfforts, const PROPERTIES *aProperties=NULL)
Return a list of footprint names contained within the library at aLibraryPath.
Definition: plugin.cpp:60
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:80
PROPERTIES is a name/value tuple with unique names and optional values.
Definition: properties.h:34
PLUGIN * operator ->() const
Definition: io_mgr.h:619
Geda PCB file formats.
Definition: io_mgr.h:63
static PCB_FILE_T GuessPluginTypeFromLibPath(const wxString &aLibPath)
Function GuessPluginTypeFromLibPath returns a plugin type given a footprint library's libPath.
Definition: io_mgr.cpp:127
PLUGIN_REGISTRY Holds a list of available plugins, created using a singleton REGISTER_PLUGIN object.
Definition: io_mgr.h:81
virtual bool IsFootprintLibWritable(const wxString &aLibraryPath)
Function IsFootprintLibWritable returns true iff the library at aLibraryPath is writable.
Definition: plugin.cpp:132
RELEASER releases a PLUGIN in the context of a potential thrown exception, through its destructor.
Definition: io_mgr.h:579
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:129
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
#define NULL
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:96
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:176
RELEASER & operator=(RELEASER &aOther)
Definition: io_mgr.h:584
void set(PLUGIN *aPlugin)
Definition: io_mgr.h:607
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:87
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:191
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:70
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:91
PLUGIN * plugin
Definition: io_mgr.h:581
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:56
BOARD holds information pertinent to a Pcbnew printed circuit board.
Definition: class_board.h:180
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:61
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:273
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:123
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:567
REGISTER_PLUGIN Registers a plugin.
Definition: io_mgr.h:139
void Register(PCB_FILE_T aType, const wxString &aName, std::function< PLUGIN *(void)> aCreateFunc)
Definition: io_mgr.h:102
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:112