realAscot/kicad-source
1
0
Fork 0
mirror of https://gitlab.com/kicad/code/kicad.git synced 2025-09-15 02:33:15 +02:00
Code Issues Packages Projects Releases Wiki Activity
kicad-source/pcbnew/io_mgr.h
Wayne Stambaugh 06aa1506ee Add optional project parameter to PCB plugin load method. 
The optional PROJECT parameter is primarily used for third party plugins
that need to store project information loaded by the plugin.
2020-12-18 10:40:51 -05:00

583 lines
24 KiB
C++
Raw Blame History

#ifndef IO_MGR_H_
#define IO_MGR_H_
/*
* This program source code file is part of KICAD, a free EDA CAD application.
*
* Copyright (C) 2011-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
* Copyright (C) 2016-2020 Kicad Developers, see AUTHORS.txt for contributors.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, you may find one here:
* http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
* or you may search the http://www.gnu.org website for the version 2 license,
* or you may write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
*/
#include <richio.h>
#include <map>
#include <functional>
#include <wx/time.h>
#include <config.h>
class BOARD;
class PLUGIN;
class FOOTPRINT;
class PROPERTIES;
class PROJECT;
/**
* A factory which returns an instance of a #PLUGIN.
*/
class IO_MGR
{
public:
/**
* The set of file types that the IO_MGR knows about, and for which there has been a
* plugin written.
*/
enum PCB_FILE_T
{
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.
// add your type here.
// etc.
FILE_TYPE_NONE
};
/**
* Hold a list of available plugins, created using a singleton REGISTER_PLUGIN object.
* This way, plugins can be added link-time.
*/
class PLUGIN_REGISTRY
{
public:
struct ENTRY
{
PCB_FILE_T m_type;
std::function<PLUGIN*(void)> m_createFunc;
wxString m_name;
};
static PLUGIN_REGISTRY *Instance()
{
static PLUGIN_REGISTRY *self = nullptr;
if( !self )
{
self = new PLUGIN_REGISTRY;
}
return self;
}
void Register( PCB_FILE_T aType, const wxString& aName,
std::function<PLUGIN*(void)> aCreateFunc )
{
ENTRY ent;
ent.m_type = aType;
ent.m_createFunc = aCreateFunc;
ent.m_name = aName;
m_plugins.push_back( ent );
}
PLUGIN* Create( PCB_FILE_T aFileType ) const
{
for( auto& ent : m_plugins )
{
if ( ent.m_type == aFileType )
{
return ent.m_createFunc();
}
}
return nullptr;
}
const std::vector<ENTRY>& AllPlugins() const
{
return m_plugins;
}
private:
std::vector<ENTRY> m_plugins;
};
/**
* Register a plugin.
*
* Declare as a static variable in an anonymous namespace.
*
* @param aType type of the plugin
* @param aName name of the file format
* @param aCreateFunc function that creates a new object for the plugin.
*/
struct REGISTER_PLUGIN
{
REGISTER_PLUGIN( PCB_FILE_T aType, const wxString& aName,
std::function<PLUGIN*(void)> aCreateFunc )
{
PLUGIN_REGISTRY::Instance()->Register( aType, aName, aCreateFunc );
}
};
/**
* Return 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.
*
* @note The caller owns the returned object and must call PluginRelease when done using it.
*
* @param aFileType is from #PCB_FILE_T and tells which plugin to find.
* @return the plug in corresponding to \a aFileType or NULL if not found.
*/
static PLUGIN* PluginFind( PCB_FILE_T aFileType );
/**
* Release a #PLUGIN back to the system and may cause it to be unloaded from memory.
*
* @param aPlugin is the one to be released, and which is no longer usable
* after calling this.
*/
static void PluginRelease( PLUGIN* aPlugin );
/**
* Return a brief name for a plugin given \a aFileType enum.
*/
static const wxString ShowType( PCB_FILE_T aFileType );
/**
* Return the #PCB_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
*/
static PCB_FILE_T EnumFromStr( const wxString& aFileType );
/**
* Return the file extension for \a aFileType.
*
* @param aFileType The #PCB_FILE_T type.
* @return the file extension for \a aFileType or an empty string if \a aFileType is invalid.
*/
static const wxString GetFileExtension( PCB_FILE_T aFileType );
/**
* Return a plugin type given a footprint library's libPath.
*/
static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
/**
* Find the requested #PLUGIN and if found, calls the #PLUGIN::Load() function
* on it using the arguments passed to this function. After the #PLUGIN::Load()
* function returns, the #PLUGIN is Released() as part of this call.
*
* @param aFileType is the #PCB_FILE_T of file to load.
* @param aFileName is the name of the file to load.
* @param aAppendToMe is an existing BOARD to append to, use NULL if fresh
* board load is wanted.
* @param aProperties is an associative array that allows the caller to
* pass additional tuning parameters to the PLUGIN.
* @param aProject is the optional #PROJECT object primarily used by third party
* importers.
* @return the loaded #BOARD object. The caller owns it an it will never NULL because
* exception thrown if error.
*
* @throw IO_ERROR if the #PLUGIN cannot be found, file cannot be found, or file cannot
* be loaded.
*/
static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
BOARD* aAppendToMe = nullptr, const PROPERTIES* aProperties = nullptr,
PROJECT* aProject = nullptr );
/**
* Write either a full \a aBoard to a storage file in a format that this implementation
* knows about, or it can be used to write a portion of\a aBoard to a special kind of
* export file.
*
* @param aFileType is the #PCB_FILE_T of file to save.
* @param aFileName is the name of a file to save to on disk.
* @param aBoard is the #BOARD document (data tree) to save or export to disk.
* @param aBoard is the in memory document tree from which to extract information when
* writing to \a aFileName. The caller continues to own the #BOARD, and
* the plugin should refrain from modifying the #BOARD if possible.
* @param aProperties is 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.
*
* @throw IO_ERROR if there is a problem saving or exporting.
*/
static void Save( PCB_FILE_T aFileType, const wxString& aFileName, BOARD* aBoard,
const PROPERTIES* aProperties = nullptr );
};
/**
* A base class that #BOARD loading and saving plugins should derive from.
*
* Implementations can provide either Load() or Save() functions, or both. PLUGINs throw
* exceptions, so it is best that you wrap your calls to these functions in a try catch block.
* Plugins throw exceptions because it is illegal for them to have any user interface calls in
* them whatsoever, i.e. no windowing or screen printing at all.
*
*The compiler writes the "zero argument" constructor for a PLUGIN automatically if you do
* not provide one. If you decide you need to provide a zero argument constructor of your
* own design, that is allowed. It must be public, and it is what the #IO_MGR uses. Parameters
* may be passed into a PLUGIN via the #PROPERTIES variable for any of the public API functions
* which take one.
*
*
* <pre>
* try
* {
* IO_MGR::Load(...);
* or
* IO_MGR::Save(...);
* }
* catch( const IO_ERROR& ioe )
* {
* // grab text from ioe, show in error window.
* }
* </pre>
*/
class PLUGIN
{
public:
/**
* Return a brief hard coded name for this PLUGIN.
*/
virtual const wxString PluginName() const = 0;
/**
* Returns the file extension for the PLUGIN.
*/
virtual const wxString GetFileExtension() const = 0;
/**
* Load information from some input file format that this PLUGIN implementation
* knows about into either a new #BOARD or an existing one.
*
* This may be used to load an entire new #BOARD, or to augment an existing one if
* @a aAppendToMe is not NULL.
*
* @param aFileName is the name of the file to use as input and may be foreign in
* nature or native in nature.
* @param aAppendToMe is an existing BOARD to append to, but if NULL then this means
* "do not append, rather load anew".
* @param aProperties is an associative array that can be used to tell the loader how to
* load the file, because it can take any number of additional named
* arguments that the plugin is known to support. These are tuning
* parameters for the import or load. The caller continues to own
* this object (plugin may not delete it), and plugins should expect
* it to be optionally NULL.
* @param aProject is the optional #PROJECT object primarily used by third party
* importers.
* @return the successfully loaded board, or the same one as \a aAppendToMe if aAppendToMe
* was not NULL, and caller owns it.
*
* @throw IO_ERROR if there is a problem loading, and its contents should say what went
* wrong, using line number and character offsets of the input file if
* possible.
*/
virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
const PROPERTIES* aProperties = nullptr, PROJECT* aProject = nullptr );
/**
* Write @a aBoard to a storage file in a format that this PLUGIN implementation knows
* about or it can be used to write a portion of \a aBoard to a special kind of export
* file.
*
* @param aFileName is the name of a file to save to on disk.
* @param aBoard is the class #BOARD in memory document tree from which to extract
* information when writing to \a aFileName. The caller continues to
* own the BOARD, and the plugin should refrain from modifying the BOARD
* if possible.
* @param aProperties is 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.
*
* @throw IO_ERROR if there is a problem saving or exporting.
*/
virtual void Save( const wxString& aFileName, BOARD* aBoard,
const PROPERTIES* aProperties = nullptr );
/**
* Return a list of footprint names contained within the library at @a aLibraryPath.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file,
* or URL containing several footprints.
* @param aProperties is an associative array that can be used to tell the plugin
* anything needed about how to perform with respect to @a aLibraryPath.
* The caller continues to own this object (plugin may not delete it),
* and plugins should expect it to be optionally NULL.
* @param aFootprintNames is the array of available footprint names inside a library.
* @param aBestEfforts if true, don't throw on errors, just return an empty list.
*
* @throw IO_ERROR if the library cannot be found, or footprint cannot be loaded.
*/
virtual void FootprintEnumerate( wxArrayString& aFootprintNames, const wxString& aLibraryPath,
bool aBestEfforts, const PROPERTIES* aProperties = nullptr );
/**
* Generate a timestamp representing all the files in the library (including the library
* directory).
*
* Timestamps should not be considered ordered, they either match or they don't.
*/
virtual long long GetLibraryTimestamp( const wxString& aLibraryPath ) const = 0;
/**
* If possible, prefetches the specified library (e.g. performing downloads). Does not parse.
* Threadsafe.
*
* This is a no-op for libraries that cannot be prefetched. Plugins that cannot prefetch
* need not override this; a default no-op is provided.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
*
* @param aProperties is an associative array that can be used to tell the plugin anything
* needed about how to perform with respect to @a aLibraryPath. The
* caller continues to own this object (plugin may not delete it), and
* plugins should expect it to be optionally NULL.
*
* @throw IO_ERROR if there is an error prefetching the library.
*/
virtual void PrefetchLib( const wxString& aLibraryPath,
const PROPERTIES* aProperties = nullptr );
/**
* Load a footprint having @a aFootprintName from the @a aLibraryPath containing a library
* format that this PLUGIN knows about.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
* @param aFootprintName is the name of the footprint to load.
* @param aProperties is an associative array that can be used to tell the loader
* implementation to do something special, 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.
* @return the #FOOTPRINT object if found caller owns it, else NULL if not found.
*
* @throw IO_ERROR if the library cannot be found or read. No exception is thrown in
* the case where \a aFootprintName cannot be found.
*/
virtual FOOTPRINT* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
const PROPERTIES* aProperties = nullptr );
/**
* A version of FootprintLoad() for use after FootprintEnumerate() for more efficient
* cache management.
*/
virtual const FOOTPRINT* GetEnumeratedFootprint( const wxString& aLibraryPath,
const wxString& aFootprintName,
const PROPERTIES* aProperties = nullptr );
/**
* Check for the existence of a footprint.
*/
virtual bool FootprintExists( const wxString& aLibraryPath, const wxString& aFootprintName,
const PROPERTIES* aProperties = nullptr );
/**
* Write @a aFootprint to an existing library located at @a aLibraryPath.
* If a footprint by the same name already exists, it is replaced.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
* @param aFootprint is what to store in the library. The caller continues to own the
* footprint after this call.
* @param aProperties is an associative array that can be used to tell the saver how to
* save the footprint, 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.
*
* @throw IO_ERROR if there is a problem saving.
*/
virtual void FootprintSave( const wxString& aLibraryPath, const FOOTPRINT* aFootprint,
const PROPERTIES* aProperties = nullptr );
/**
* Delete @a aFootprintName from the library at @a aLibraryPath.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
* @param aFootprintName is the name of a footprint to delete from the specified library.
* @param aProperties is an associative array that can be used to tell the library delete
* function anything special, 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.
*
* @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it.
*/
virtual void FootprintDelete( const wxString& aLibraryPath, const wxString& aFootprintName,
const PROPERTIES* aProperties = nullptr );
/**
* Create a new empty footprint library at @a aLibraryPath empty.
*
* It is an error to attempt to create an existing library or to attempt to create
* on a "read only" location.
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
* @param aProperties is an associative array that can be used to tell the library create
* function anything special, 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.
*
* @throw IO_ERROR if there is a problem finding the library, or creating it.
*/
virtual void FootprintLibCreate( const wxString& aLibraryPath,
const PROPERTIES* aProperties = nullptr );
/**
* Delete 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.
*
* @param aLibraryPath is a locator for the "library", usually a directory or file which
* will contain footprints.
* @param aProperties is an associative array that can be used to tell the library delete
* implementation function anything special, 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.
* @return true if library deleted, false if library did not exist.
*
* @throw IO_ERROR if there is a problem deleting an existing library.
*/
virtual bool FootprintLibDelete( const wxString& aLibraryPath,
const PROPERTIES* aProperties = nullptr );
/**
* Return true if the library at @a aLibraryPath is writable.
*
* The system libraries are typically read only because of where they are installed..
*
* @param aLibraryPath is a locator for the "library", usually a directory, file, or URL
* containing several footprints.
*
* @throw IO_ERROR if no library at aLibraryPath exists.
*/
virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
/**
* Append supported PLUGIN options to @a aListToAppenTo along with internationalized
* descriptions.
*
* Options are typically appended so that a derived #PLUGIN can call its base class
* function by the same name first, thus inheriting options declared there. Some base
* class options could pertain to all Footprint*() functions in all derived PLUGINs.
*
* @note Since aListToAppendTo is a #PROPERTIES object, all options will be unique and
* last guy wins.
*
* @param aListToAppendTo holds a tuple of
* <dl>
* <dt>option</dt>
* <dd>This eventually is what shows up into the fp-lib-table "options"
* field, possibly combined with others.</dd>
* <dt>internationalized description</dt>
* <dd>The internationalized description is displayed in DIALOG_FP_PLUGIN_OPTIONS.
* It may be multi-line and be quite explanatory of the option.</dd>
* </dl>
* <br>
* In the future perhaps @a aListToAppendTo evolves to something capable of also
* holding a wxValidator for the cells in said dialog:
* http://forums.wxwidgets.org/viewtopic.php?t=23277&p=104180.
* This would require a 3 column list, and introducing wx GUI knowledge to
* PLUGIN, which has been avoided to date.
*/
virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;
virtual ~PLUGIN()
{
//printf( "~%s", __func__ );
};
#ifndef SWIG
/**
* Releases a PLUGIN in the context of a potential thrown exception through its destructor.
*/
class RELEASER
{
PLUGIN* plugin;
// private assignment operator so it's illegal
RELEASER& operator=( RELEASER& aOther ) { return *this; }
// private copy constructor so it's illegal
RELEASER( const RELEASER& aOther ) : plugin( nullptr ) {}
public:
RELEASER( PLUGIN* aPlugin = nullptr ) :
plugin( aPlugin )
{
}
~RELEASER()
{
if( plugin )
release();
}
void release()
{
IO_MGR::PluginRelease( plugin );
plugin = nullptr;
}
void set( PLUGIN* aPlugin )
{
if( plugin )
release();
plugin = aPlugin;
}
operator PLUGIN* () const
{
return plugin;
}
PLUGIN* operator -> () const
{
return plugin;
}
};
#endif
};
#endif // IO_MGR_H_
Reference in New Issue View Git Blame Copy Permalink