KiCad PCB EDA Suite
IO_MGR Class Reference

IO_MGR is a factory which returns an instance of a PLUGIN. More...

#include <io_mgr.h>

Classes

class  PLUGIN_REGISTRY
 PLUGIN_REGISTRY Holds a list of available plugins, created using a singleton REGISTER_PLUGIN object. More...
 
struct  REGISTER_PLUGIN
 REGISTER_PLUGIN Registers a plugin. More...
 

Public Types

enum  PCB_FILE_T {
  LEGACY, KICAD_SEXP, EAGLE, PCAD,
  ALTIUM_DESIGNER, ALTIUM_CIRCUIT_STUDIO, ALTIUM_CIRCUIT_MAKER, CADSTAR_PCB_ARCHIVE,
  GEDA_PCB, FILE_TYPE_NONE
}
 Enum PCB_FILE_T is a set of file types that the IO_MGR knows about, and for which there has been a plugin written. More...
 

Static Public Member Functions

static PLUGINPluginFind (PCB_FILE_T aFileType)
 Function PluginFind returns a PLUGIN which the caller can use to import, export, save, or load design documents. More...
 
static void PluginRelease (PLUGIN *aPlugin)
 Function PluginRelease releases a PLUGIN back to the system, and may cause it to be unloaded from memory. More...
 
static const wxString ShowType (PCB_FILE_T aFileType)
 Function ShowType returns a brief name for a plugin, given aFileType enum. More...
 
static PCB_FILE_T EnumFromStr (const wxString &aFileType)
 Function EnumFromStr returns the PCB_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc. More...
 
static const wxString GetFileExtension (PCB_FILE_T aFileType)
 Function GetFileExtension returns the file extension for aFileType. More...
 
static PCB_FILE_T GuessPluginTypeFromLibPath (const wxString &aLibPath)
 Function GuessPluginTypeFromLibPath returns a plugin type given a footprint library's libPath. More...
 
static BOARDLoad (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 the arguments passed to this function. More...
 
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 knows about, or it can be used to write a portion of aBoard to a special kind of export file. More...
 

Detailed Description

IO_MGR is a factory which returns an instance of a PLUGIN.

Definition at line 45 of file io_mgr.h.

Member Enumeration Documentation

◆ 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 plugin written.

Enumerator
LEGACY 

Legacy Pcbnew file formats prior to s-expression.

KICAD_SEXP 

S-expression Pcbnew file format.

EAGLE 
PCAD 
ALTIUM_DESIGNER 
ALTIUM_CIRCUIT_STUDIO 
ALTIUM_CIRCUIT_MAKER 
CADSTAR_PCB_ARCHIVE 
GEDA_PCB 

Geda PCB file formats.

FILE_TYPE_NONE 

Definition at line 54 of file io_mgr.h.

55  {
56  LEGACY,
57  KICAD_SEXP,
58  EAGLE,
59  PCAD,
64  GEDA_PCB,
65  // add your type here.
66 
67  // etc.
68 
70  };
Geda PCB file formats.
Definition: io_mgr.h:64
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:56
S-expression Pcbnew file format.
Definition: io_mgr.h:57

Member Function Documentation

◆ EnumFromStr()

IO_MGR::PCB_FILE_T IO_MGR::EnumFromStr ( const wxString &  aFileType)
static

Function EnumFromStr returns the PCB_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.

Definition at line 92 of file io_mgr.cpp.

93 {
94  const auto& plugins = PLUGIN_REGISTRY::Instance()->AllPlugins();
95 
96  for( const auto& plugin : plugins )
97  {
98  if ( plugin.m_name == aType )
99  {
100  return plugin.m_type;
101  }
102  }
103 
104  return PCB_FILE_T( -1 );
105 }
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:87
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:119
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

References IO_MGR::PLUGIN_REGISTRY::AllPlugins(), and IO_MGR::PLUGIN_REGISTRY::Instance().

Referenced by DIALOG_FP_PLUGIN_OPTIONS::DIALOG_FP_PLUGIN_OPTIONS(), and FP_LIB_TABLE_ROW::SetType().

◆ GetFileExtension()

const wxString IO_MGR::GetFileExtension ( PCB_FILE_T  aFileType)
static

Function GetFileExtension returns the file extension for aFileType.

Parameters
aFileTypeThe PCB_FILE_T type.
Returns
A wxString object containing the file extension for aFileType or an empty string if aFileType is invalid.

Definition at line 108 of file io_mgr.cpp.

109 {
110  wxString ext = wxEmptyString;
111  PLUGIN* plugin = PluginFind( aFileType );
112 
113  if( plugin != NULL )
114  {
115  ext = plugin->GetFileExtension();
116  PluginRelease( plugin );
117  }
118 
119  return ext;
120 }
#define NULL
virtual const wxString GetFileExtension() const =0
Function GetFileExtension returns the file extension for the PLUGIN.
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:66
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:57
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:269

References PLUGIN::GetFileExtension(), NULL, PluginFind(), and PluginRelease().

Referenced by plugin_type().

◆ GuessPluginTypeFromLibPath()

IO_MGR::PCB_FILE_T IO_MGR::GuessPluginTypeFromLibPath ( const wxString &  aLibPath)
static

Function GuessPluginTypeFromLibPath returns a plugin type given a footprint library's libPath.

Definition at line 123 of file io_mgr.cpp.

124 {
125  PCB_FILE_T ret = KICAD_SEXP; // default guess, unless detected otherwise.
126  wxFileName fn( aLibPath );
127 
128  if( fn.GetExt() == LegacyFootprintLibPathExtension )
129  {
130  ret = LEGACY;
131  }
132  else if( fn.GetExt() == GedaPcbFootprintLibFileExtension )
133  {
134  ret = GEDA_PCB;
135  }
136  else if( fn.GetExt() == EagleFootprintLibPathExtension )
137  {
138  ret = EAGLE;
139  }
140 
141  // Test this one anyways, even though it's the default guess, to avoid
142  // the wxURI instantiation below.
143  // We default ret to KICAD above, because somebody might have
144  // mistakenly put a pretty library into a directory other than
145  // *.pretty/ with *.kicad_mod in there., and I don't want to return -1,
146  // since we only claimed to be guessing.
147  //
148  else if( fn.GetExt() == KiCadFootprintLibPathExtension )
149  {
150  ret = KICAD_SEXP;
151  }
152 
153  return ret;
154 }
const std::string LegacyFootprintLibPathExtension
const std::string EagleFootprintLibPathExtension
Geda PCB file formats.
Definition: io_mgr.h:64
Legacy Pcbnew file formats prior to s-expression.
Definition: io_mgr.h:56
const std::string GedaPcbFootprintLibFileExtension
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
const std::string KiCadFootprintLibPathExtension
S-expression Pcbnew file format.
Definition: io_mgr.h:57

References EAGLE, EagleFootprintLibPathExtension, GEDA_PCB, GedaPcbFootprintLibFileExtension, KICAD_SEXP, KiCadFootprintLibPathExtension, LEGACY, and LegacyFootprintLibPathExtension.

Referenced by PCB_BASE_EDIT_FRAME::AddLibrary(), FOOTPRINT_EDIT_FRAME::DeleteModuleFromLibrary(), FOOTPRINT_EDIT_FRAME::SaveFootprint(), FOOTPRINT_EDIT_FRAME::SaveFootprintAs(), and FOOTPRINT_EDIT_FRAME::SaveLibraryAs().

◆ Load()

BOARD * IO_MGR::Load ( PCB_FILE_T  aFileType,
const wxString &  aFileName,
BOARD aAppendToMe = NULL,
const PROPERTIES aProperties = NULL 
)
static

Function Load finds the requested PLUGIN and if found, calls the PLUGIN->Load(..) funtion on it using the arguments passed to this function.

After the PLUGIN->Load() function returns, the PLUGIN is Released() as part of this call.

Parameters
aFileTypeis the PCB_FILE_T of file to load.
aFileNameis the name of the file to load.
aAppendToMeis an existing BOARD to append to, use NULL if fresh board load is wanted.
aPropertiesis an associative array that allows the caller to pass additional tuning parameters to the PLUGIN.
Returns
BOARD* - caller owns it, never NULL because exception thrown if error.
Exceptions
IO_ERRORif the PLUGIN cannot be found, file cannot be found, or file cannot be loaded.

Definition at line 157 of file io_mgr.cpp.

159 {
160  // release the PLUGIN even if an exception is thrown.
161  PLUGIN::RELEASER pi( PluginFind( aFileType ) );
162 
163  if( (PLUGIN*) pi ) // test pi->plugin
164  {
165  return pi->Load( aFileName, aAppendToMe, aProperties ); // virtual
166  }
167 
168  THROW_IO_ERROR( wxString::Format( FMT_NOTFOUND, ShowType( aFileType ).GetData() ) );
169 }
static const wxString ShowType(PCB_FILE_T aFileType)
Function ShowType returns a brief name for a plugin, given aFileType enum.
Definition: io_mgr.cpp:76
RELEASER releases a PLUGIN in the context of a potential thrown exception, through its destructor.
Definition: io_mgr.h:575
#define FMT_NOTFOUND
Definition: io_mgr.cpp:42
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, CPTREE &aTree)
Function Format outputs a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:201
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:57
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:269
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
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

References FMT_NOTFOUND, Format(), PLUGIN::Load(), PluginFind(), ShowType(), and THROW_IO_ERROR.

Referenced by LoadBoard().

◆ PluginFind()

PLUGIN * IO_MGR::PluginFind ( PCB_FILE_T  aFileType)
static

Function PluginFind returns a PLUGIN which the caller can use to import, export, save, or load design documents.

The returned PLUGIN, may be reference counted, so please call PluginRelease() when you are done using the returned PLUGIN. It may or may not be code running from a DLL/DSO.

Parameters
aFileTypeis from PCB_FILE_T and tells which plugin to find.
Returns
PLUGIN* - the plugin corresponding to aFileType or NULL if not found. Caller owns the returned object, and must call PluginRelease when done using it.

Definition at line 57 of file io_mgr.cpp.

58 {
59  // This implementation is subject to change, any magic is allowed here.
60  // The public IO_MGR API is the only pertinent public information.
61 
62  return PLUGIN_REGISTRY::Instance()->Create( aFileType );
63 }
PLUGIN * Create(PCB_FILE_T aFileType) const
Definition: io_mgr.h:107
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:87

References IO_MGR::PLUGIN_REGISTRY::Create(), and IO_MGR::PLUGIN_REGISTRY::Instance().

Referenced by PCBNEW_CONTROL::AppendBoardFromFile(), AskLoadBoardFileName(), PCB_BASE_EDIT_FRAME::CreateNewLibrary(), DIALOG_FP_PLUGIN_OPTIONS::DIALOG_FP_PLUGIN_OPTIONS(), FP_LIB_TABLE::FindRow(), GetFileExtension(), PCB_EDIT_FRAME::HarvestFootprintsToLibrary(), Load(), DIALOG_BOARD_SETUP::OnAuxiliaryAction(), PCB_EDIT_FRAME::OpenProjectFiles(), parse_module_with_plugin(), Save(), FOOTPRINT_EDIT_FRAME::SaveLibraryAs(), PCB_EDIT_FRAME::SavePcbCopy(), and PCB_EDIT_FRAME::SavePcbFile().

◆ PluginRelease()

void IO_MGR::PluginRelease ( PLUGIN aPlugin)
static

Function PluginRelease releases a PLUGIN back to the system, and may cause it to be unloaded from memory.

Parameters
aPluginis the one to be released, and which is no longer usable after calling this.

Definition at line 66 of file io_mgr.cpp.

67 {
68  // This function is a place holder for a future point in time where
69  // the plugin is a DLL/DSO. It could do reference counting, and then
70  // unload the DLL/DSO when count goes to zero.
71 
72  delete aPlugin;
73 }

Referenced by GetFileExtension(), and PLUGIN::RELEASER::release().

◆ Save()

void IO_MGR::Save ( PCB_FILE_T  aFileType,
const wxString &  aFileName,
BOARD aBoard,
const PROPERTIES aProperties = NULL 
)
static

Function Save will write either a full aBoard to a storage file in a format that this implementation knows about, or it can be used to write a portion of aBoard to a special kind of export file.

Parameters
aFileTypeis the PCB_FILE_T of file to save.
aFileNameis the name of a file to save to on disk.
aBoardis the BOARD document (data tree) to save or export to disk.
aBoardis the in memory document tree from which to extract information when writing to aFileName. The caller continues to own the BOARD, and the plugin should refrain from modifying the BOARD if possible.
aPropertiesis an associative array that can be used to tell the saver how to save the file, because it can take any number of additional named tuning arguments that the plugin is known to support. The caller continues to own this object (plugin may not delete it), and plugins should expect it to be optionally NULL.
Exceptions
IO_ERRORif there is a problem saving or exporting.

Definition at line 172 of file io_mgr.cpp.

173 {
174  // release the PLUGIN even if an exception is thrown.
175  PLUGIN::RELEASER pi( PluginFind( aFileType ) );
176 
177  if( (PLUGIN*) pi ) // test pi->plugin
178  {
179  pi->Save( aFileName, aBoard, aProperties ); // virtual
180  return;
181  }
182 
183  THROW_IO_ERROR( wxString::Format( FMT_NOTFOUND, ShowType( aFileType ).GetData() ) );
184 }
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
static const wxString ShowType(PCB_FILE_T aFileType)
Function ShowType returns a brief name for a plugin, given aFileType enum.
Definition: io_mgr.cpp:76
RELEASER releases a PLUGIN in the context of a potential thrown exception, through its destructor.
Definition: io_mgr.h:575
#define FMT_NOTFOUND
Definition: io_mgr.cpp:42
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, CPTREE &aTree)
Function Format outputs a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:201
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:57
PLUGIN is a base class that BOARD loading and saving plugins should derive from.
Definition: io_mgr.h:269
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38

References FMT_NOTFOUND, Format(), PluginFind(), PLUGIN::Save(), ShowType(), and THROW_IO_ERROR.

Referenced by SaveBoard().

◆ ShowType()

const wxString IO_MGR::ShowType ( PCB_FILE_T  aFileType)
static

Function ShowType returns a brief name for a plugin, given aFileType enum.

Definition at line 76 of file io_mgr.cpp.

77 {
78  const auto& plugins = PLUGIN_REGISTRY::Instance()->AllPlugins();
79 
80  for( const auto& plugin : plugins )
81  {
82  if ( plugin.m_type == aType )
83  {
84  return plugin.m_name;
85  }
86  }
87 
88  return wxString::Format( _( "UNKNOWN (%d)" ), aType );
89 }
static PLUGIN_REGISTRY * Instance()
Definition: io_mgr.h:87
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, CPTREE &aTree)
Function Format outputs a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:201
#define _(s)
Definition: 3d_actions.cpp:33
const std::vector< ENTRY > & AllPlugins() const
Definition: io_mgr.h:119

References _, IO_MGR::PLUGIN_REGISTRY::AllPlugins(), Format(), and IO_MGR::PLUGIN_REGISTRY::Instance().

Referenced by PCB_BASE_EDIT_FRAME::AddLibrary(), PANEL_FP_LIB_TABLE::browseLibrariesHandler(), FP_LIB_TABLE_ROW::GetType(), Load(), PANEL_FP_LIB_TABLE::PANEL_FP_LIB_TABLE(), and Save().


The documentation for this class was generated from the following files: