2016-07-06 09:22:56 +00:00
|
|
|
#ifndef _SCH_IO_MGR_H_
|
|
|
|
#define _SCH_IO_MGR_H_
|
|
|
|
|
|
|
|
/*
|
|
|
|
* This program source code file is part of KiCad, a free EDA CAD application.
|
|
|
|
*
|
|
|
|
* Copyright (C) 2016 CERN
|
2021-03-25 14:07:16 +00:00
|
|
|
* Copyright (C) 2016-2021 KiCad Developers, see AUTHORS.txt for contributors.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @author Wayne Stambaugh <stambaughw@gmail.com>
|
|
|
|
*
|
|
|
|
* 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 3
|
|
|
|
* 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, see <http://www.gnu.org/licenses/>.
|
|
|
|
*/
|
|
|
|
|
|
|
|
#include <richio.h>
|
2017-05-08 15:11:14 +00:00
|
|
|
#include <import_export.h>
|
2016-07-06 09:22:56 +00:00
|
|
|
#include <map>
|
2017-06-26 11:13:43 +00:00
|
|
|
#include <enum_vector.h>
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
class SCH_SHEET;
|
2016-07-11 19:48:46 +00:00
|
|
|
class SCH_SCREEN;
|
2016-07-06 09:22:56 +00:00
|
|
|
class SCH_PLUGIN;
|
2020-05-13 02:00:37 +00:00
|
|
|
class SCHEMATIC;
|
2016-07-06 09:22:56 +00:00
|
|
|
class KIWAY;
|
|
|
|
class LIB_PART;
|
2016-08-18 23:23:10 +00:00
|
|
|
class PART_LIB;
|
2016-07-06 09:22:56 +00:00
|
|
|
class PROPERTIES;
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
2021-03-25 14:07:16 +00:00
|
|
|
* A factory which returns an instance of a #SCH_PLUGIN.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
class SCH_IO_MGR
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* A set of file types that the #SCH_IO_MGR knows about, and for which there
|
2016-07-06 09:22:56 +00:00
|
|
|
* has been a plugin written.
|
|
|
|
*/
|
2017-06-26 11:13:43 +00:00
|
|
|
DEFINE_ENUM_VECTOR( SCH_FILE_T,
|
2020-04-03 23:22:24 +00:00
|
|
|
{
|
|
|
|
SCH_LEGACY, ///< Legacy Eeschema file formats prior to s-expression.
|
|
|
|
SCH_KICAD, ///< The s-expression version of the schematic file formats.
|
2020-08-23 19:01:08 +00:00
|
|
|
SCH_ALTIUM, ///< Altium file format
|
2020-09-19 22:05:02 +00:00
|
|
|
SCH_CADSTAR_ARCHIVE, ///< CADSTAR Schematic Archive
|
2020-04-03 23:22:24 +00:00
|
|
|
SCH_EAGLE, ///< Autodesk Eagle file format
|
2016-07-06 09:22:56 +00:00
|
|
|
|
2021-03-25 14:07:16 +00:00
|
|
|
// Add your schematic type here.
|
2020-05-15 13:25:11 +00:00
|
|
|
SCH_FILE_UNKNOWN
|
2020-04-03 23:22:24 +00:00
|
|
|
} )
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Return a #SCH_PLUGIN which the caller can use to import, export, save, or load
|
|
|
|
* design documents.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* The returned #SCH_PLUGIN, may be reference counted, so please call PluginRelease()
|
|
|
|
* when you are done using the returned #SCH_PLUGIN. It may or may not be code running
|
|
|
|
* from a DLL/DSO.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @param aFileType is from #SCH_FILE_T and tells which plugin to find.
|
|
|
|
*
|
|
|
|
* @return the plugin corresponding to aFileType or NULL if not found.
|
2016-07-06 09:22:56 +00:00
|
|
|
* Caller owns the returned object, and must call PluginRelease when done using it.
|
|
|
|
*/
|
2017-05-08 15:11:14 +00:00
|
|
|
APIEXPORT
|
2016-07-06 09:22:56 +00:00
|
|
|
static SCH_PLUGIN* FindPlugin( SCH_FILE_T aFileType );
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Release a #SCH_PLUGIN back to the system, and may cause it to be unloaded from memory.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aPlugin is the one to be released, and which is no longer usable
|
|
|
|
* after calling this.
|
|
|
|
*/
|
|
|
|
static void ReleasePlugin( SCH_PLUGIN* aPlugin );
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Return a brief name for a plugin, given aFileType enum.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
static const wxString ShowType( SCH_FILE_T aFileType );
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Return the #SCH_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
static SCH_FILE_T EnumFromStr( const wxString& aFileType );
|
|
|
|
|
|
|
|
/**
|
2020-02-28 14:03:09 +00:00
|
|
|
* Return the schematic file extension for \a aFileType.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
|
|
|
* @param aFileType is the #SCH_FILE_T type.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @return the file extension for \a aFileType or an empty string if \a aFileType is invalid.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
static const wxString GetFileExtension( SCH_FILE_T aFileType );
|
|
|
|
|
2020-02-28 14:03:09 +00:00
|
|
|
/**
|
|
|
|
* Return the symbol library file extension (if any) for \a aFileType.
|
|
|
|
*
|
|
|
|
* @param aFileType is the #SCH_FILE_T type.
|
|
|
|
*
|
|
|
|
* @return the file extension for \a aFileType or an empty string if \a aFileType is invalid.
|
|
|
|
*/
|
|
|
|
static const wxString GetLibraryFileExtension( SCH_FILE_T aFileType );
|
|
|
|
|
2016-07-06 09:22:56 +00:00
|
|
|
/**
|
2020-03-16 13:04:50 +00:00
|
|
|
* Return a plugin type given a symbol library using the file extension of \a aLibPath.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
static SCH_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );
|
|
|
|
|
2020-03-16 13:04:50 +00:00
|
|
|
/**
|
|
|
|
* Return a plugin type given a schematic using the file extension of \a aSchematicPath.
|
|
|
|
*/
|
|
|
|
static SCH_FILE_T GuessPluginTypeFromSchPath( const wxString& aSchematicPath );
|
2016-07-06 09:22:56 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Base class that schematic file and library loading and saving plugins should derive from.
|
2016-07-06 09:22:56 +00:00
|
|
|
* Implementations can provide either Load() or Save() functions, or both.
|
|
|
|
* SCH_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.
|
|
|
|
*
|
|
|
|
* <pre>
|
|
|
|
* try
|
|
|
|
* {
|
|
|
|
* SCH_IO_MGR::Load(...);
|
|
|
|
* or
|
|
|
|
* SCH_IO_MGR::Save(...);
|
|
|
|
* }
|
|
|
|
* catch( const IO_ERROR& ioe )
|
|
|
|
* {
|
|
|
|
* // grab text from ioe, show in error window.
|
|
|
|
* }
|
|
|
|
* </pre>
|
|
|
|
*/
|
|
|
|
class SCH_PLUGIN
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
|
|
|
|
//-----<PUBLIC SCH_PLUGIN API>-------------------------------------------------
|
|
|
|
|
|
|
|
/**
|
2021-03-25 14:07:16 +00:00
|
|
|
* Return a brief hard coded name for this SCH_PLUGIN.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
virtual const wxString GetName() const = 0;
|
|
|
|
|
|
|
|
/**
|
2021-03-25 14:07:16 +00:00
|
|
|
* Return the file extension for the #SCH_PLUGIN.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
virtual const wxString GetFileExtension() const = 0;
|
|
|
|
|
2020-02-28 14:03:09 +00:00
|
|
|
/**
|
|
|
|
* Return the library file extension for the #SCH_PLUGIN object.
|
|
|
|
*/
|
|
|
|
virtual const wxString GetLibraryFileExtension() const = 0;
|
|
|
|
|
2016-10-24 23:18:50 +00:00
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Return the modification hash from the library cache.
|
2016-10-24 23:18:50 +00:00
|
|
|
*
|
|
|
|
* @note This is temporary until the new s-expr file format is implement. The new file
|
|
|
|
* format will embed symbols instead of referencing them from the library. This
|
|
|
|
* function can be removed when the new file format is implemented.
|
|
|
|
*
|
|
|
|
* @return the modification hash of the library cache.
|
|
|
|
*/
|
|
|
|
virtual int GetModifyHash() const = 0;
|
|
|
|
|
2021-03-25 14:07:16 +00:00
|
|
|
virtual void SaveLibrary( const wxString& aFileName, const PROPERTIES* aProperties = nullptr );
|
2017-01-27 15:56:36 +00:00
|
|
|
|
2016-07-06 09:22:56 +00:00
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Load information from some input file format that this #SCH_PLUGIN implementation
|
|
|
|
* knows about, into either a new #SCH_SHEET or an existing one. This may be used to load an
|
|
|
|
* entire new #SCH_SHEET, or to augment an existing one if \a aAppendToMe is not NULL.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aFileName is the name of the file to use as input and may be foreign in
|
2016-10-09 12:29:44 +00:00
|
|
|
* nature or native in nature.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @param aKiway is the #KIWAY object used to access the component libraries loaded
|
|
|
|
* by the project.
|
|
|
|
*
|
|
|
|
* @param aAppendToMe is an existing #SCH_SHEET to append to, but if NULL then this means
|
2016-10-09 12:29:44 +00:00
|
|
|
* "do not append, rather load anew".
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-10-09 12:29:44 +00:00
|
|
|
* @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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @return the successfully loaded schematic, or the same one as \a aAppendToMe
|
|
|
|
* if \a aAppendToMe was not NULL, and the caller owns it.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-10-09 12:29:44 +00:00
|
|
|
* @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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
2020-05-21 03:00:23 +00:00
|
|
|
virtual SCH_SHEET* Load( const wxString& aFileName, SCHEMATIC* aSchematic,
|
2021-03-25 14:07:16 +00:00
|
|
|
SCH_SHEET* aAppendToMe = nullptr,
|
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Write \a aSchematic to a storage file in a format that this #SCH_PLUGIN implementation
|
|
|
|
* knows about, or it can be used to write a portion of \a aSchematic to a special kind
|
|
|
|
* of export file.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aFileName is the name of a file to save to on disk.
|
|
|
|
*
|
2020-05-21 03:00:23 +00:00
|
|
|
* @param aSheet is the class #SCH_SHEET in memory document tree from which to extract
|
2016-10-09 12:29:44 +00:00
|
|
|
* information when writing to \a aFileName. The caller continues to
|
|
|
|
* own the SCHEMATIC, and the plugin should refrain from modifying the
|
|
|
|
* SCHEMATIC if possible.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2020-05-21 03:00:23 +00:00
|
|
|
* @param aSchematic is the #SCHEMATIC object used to access any schematic-wide or project
|
|
|
|
* information needed to save the document.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
2016-10-09 12:29:44 +00:00
|
|
|
* @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
|
2020-04-26 20:53:29 +00:00
|
|
|
* should expect it to be optionally NULL. Set the
|
|
|
|
* #PropSaveCurrentSheetOnly property to only save the current sheet.
|
2021-03-25 14:07:16 +00:00
|
|
|
* Otherwise, all hierarchical sheets are saved.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @throw IO_ERROR if there is a problem saving or exporting.
|
|
|
|
*/
|
2020-05-21 03:00:23 +00:00
|
|
|
virtual void Save( const wxString& aFileName, SCH_SHEET* aSheet, SCHEMATIC* aSchematic,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Populate a list of #LIB_PART alias names contained within the library \a aLibraryPath.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2019-11-06 19:15:42 +00:00
|
|
|
* @param aSymbolNameList is an array to populate with the #LIB_PART names associated with
|
|
|
|
* the library.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
2016-07-06 09:22:56 +00:00
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
2016-08-18 23:23:10 +00:00
|
|
|
* or URL containing one or more #LIB_PART objects.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
2016-08-18 23:23:10 +00:00
|
|
|
* @param aProperties is an associative array that can be used to tell the plugin anything
|
2017-06-16 00:31:42 +00:00
|
|
|
* needed about how to perform with respect to \a aLibraryPath. The
|
2016-08-18 23:23:10 +00:00
|
|
|
* caller continues to own this object (plugin may not delete it), and
|
|
|
|
* plugins should expect it to be optionally NULL.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-08-18 23:23:10 +00:00
|
|
|
* @throw IO_ERROR if the library cannot be found, the part library cannot be loaded.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
2021-03-25 14:07:16 +00:00
|
|
|
virtual void EnumerateSymbolLib( wxArrayString& aSymbolNameList, const wxString& aLibraryPath,
|
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-08-18 23:23:10 +00:00
|
|
|
|
2017-02-24 16:09:27 +00:00
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Populate a list of #LIB_PART aliases contained within the library \a aLibraryPath.
|
2017-02-24 16:09:27 +00:00
|
|
|
*
|
2021-03-25 14:07:16 +00:00
|
|
|
* @note It is the responsibility of the caller to delete the returned object from the heap.
|
2019-11-06 19:15:42 +00:00
|
|
|
* Failure to do this will result in memory leaks.
|
|
|
|
*
|
|
|
|
* @param aSymbolList is an array to populate with the #LIB_PART pointers associated with
|
|
|
|
* the library.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
2017-02-24 16:09:27 +00:00
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
|
|
|
* or URL containing one or more #LIB_PART objects.
|
2017-06-16 00:31:42 +00:00
|
|
|
*
|
2017-02-24 16:09:27 +00:00
|
|
|
* @param aProperties is an associative array that can be used to tell the plugin anything
|
2017-06-16 00:31:42 +00:00
|
|
|
* needed about how to perform with respect to \a aLibraryPath. The
|
2017-02-24 16:09:27 +00:00
|
|
|
* caller continues to own this object (plugin may not delete it), and
|
|
|
|
* plugins should expect it to be optionally NULL.
|
|
|
|
*
|
|
|
|
* @throw IO_ERROR if the library cannot be found, the part library cannot be loaded.
|
|
|
|
*/
|
2019-11-06 19:15:42 +00:00
|
|
|
virtual void EnumerateSymbolLib( std::vector<LIB_PART*>& aSymbolList,
|
2021-03-25 14:07:16 +00:00
|
|
|
const wxString& aLibraryPath,
|
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2017-02-24 16:09:27 +00:00
|
|
|
|
2016-07-06 09:22:56 +00:00
|
|
|
/**
|
2019-11-06 19:15:42 +00:00
|
|
|
* Load a #LIB_PART object having \a aPartName from the \a aLibraryPath containing
|
|
|
|
* a library format that this #SCH_PLUGIN knows about.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
2016-09-23 17:28:38 +00:00
|
|
|
* or URL containing several symbols.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2019-11-06 19:15:42 +00:00
|
|
|
* @param aPartName is the name of the #LIB_PART to load.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-09-03 18:28:17 +00:00
|
|
|
* @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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2019-11-06 19:15:42 +00:00
|
|
|
* @return the part created on the heap if found caller shares it or NULL if not found.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @throw IO_ERROR if the library cannot be found or read. No exception
|
|
|
|
* is thrown in the case where aAliasName cannot be found.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
2019-11-06 19:15:42 +00:00
|
|
|
virtual LIB_PART* LoadSymbol( const wxString& aLibraryPath, const wxString& aPartName,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Write \a aSymbol to an existing library located at \a aLibraryPath. If a #LIB_PART
|
2016-10-05 23:28:56 +00:00
|
|
|
* by the same name already exists or there are any conflicting alias names, the new
|
2021-03-25 14:07:16 +00:00
|
|
|
* #LIB_PART will silently overwrite any existing aliases and/or part because libraries
|
2016-10-05 23:28:56 +00:00
|
|
|
* cannot have duplicate alias names. It is the responsibility of the caller to check
|
|
|
|
* the library for conflicts before saving.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
2016-09-23 17:28:38 +00:00
|
|
|
* or URL containing several symbols.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-09-17 17:31:58 +00:00
|
|
|
* @param aSymbol is what to store in the library. The library is refreshed and the
|
|
|
|
* caller must update any #LIB_PART pointers that may have changed.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aProperties is an associative array that can be used to tell the
|
2016-09-17 17:31:58 +00:00
|
|
|
* saver how to save the symbol, 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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-10-05 23:28:56 +00:00
|
|
|
* @throw IO_ERROR if there is a problem saving.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
2016-09-17 17:31:58 +00:00
|
|
|
virtual void SaveSymbol( const wxString& aLibraryPath, const LIB_PART* aSymbol,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
2016-09-29 22:31:43 +00:00
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Delete the entire #LIB_PART associated with \a aAliasName from the library
|
|
|
|
* \a aLibraryPath.
|
2016-09-29 22:31:43 +00:00
|
|
|
*
|
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
|
|
|
* or URL containing several symbols.
|
|
|
|
*
|
2019-11-06 19:15:42 +00:00
|
|
|
* @param aSymbolName is the name of a #LIB_PART associated with it's root #LIB_PART
|
|
|
|
* object to delete from the specified library.
|
2016-09-29 22:31:43 +00:00
|
|
|
*
|
|
|
|
* @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 alias or the library or deleting it.
|
|
|
|
*/
|
2019-11-06 19:15:42 +00:00
|
|
|
virtual void DeleteSymbol( const wxString& aLibraryPath, const wxString& aSymbolName,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-09-29 22:31:43 +00:00
|
|
|
|
2016-07-06 09:22:56 +00:00
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Create a new empty symbol library at \a aLibraryPath. It is an error to attempt
|
2016-10-05 23:28:56 +00:00
|
|
|
* to create an existing library or to attempt to create on a "read only" location.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
2016-10-05 23:28:56 +00:00
|
|
|
* or URL containing several footprints.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-10-05 23:28:56 +00:00
|
|
|
* @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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @throw IO_ERROR if there is a problem finding the library, or creating it.
|
|
|
|
*/
|
2016-10-05 23:28:56 +00:00
|
|
|
virtual void CreateSymbolLib( const wxString& aLibraryPath,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Delete an existing symbol library and returns true if successful, or if library
|
2016-10-09 12:29:44 +00:00
|
|
|
* does not exist returns false, or throws an exception if library exists but is read
|
|
|
|
* only or cannot be deleted for some other reason.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2016-10-09 12:29:44 +00:00
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory or file
|
|
|
|
* which will contain symbols.
|
|
|
|
*
|
|
|
|
* @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.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
2017-06-16 00:31:42 +00:00
|
|
|
* @return true if library deleted or false if library did not exist.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @throw IO_ERROR if there is a problem deleting an existing library.
|
|
|
|
*/
|
2016-10-09 12:29:44 +00:00
|
|
|
virtual bool DeleteSymbolLib( const wxString& aLibraryPath,
|
2021-03-25 14:07:16 +00:00
|
|
|
const PROPERTIES* aProperties = nullptr );
|
2016-07-06 09:22:56 +00:00
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Return true if the library at \a aLibraryPath is writable. (Often
|
2016-07-06 09:22:56 +00:00
|
|
|
* system libraries are read only because of where they are installed.)
|
|
|
|
*
|
|
|
|
* @param aLibraryPath is a locator for the "library", usually a directory, file,
|
2016-10-09 12:29:44 +00:00
|
|
|
* or URL containing several symbols.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @throw IO_ERROR if no library at aLibraryPath exists.
|
|
|
|
*/
|
|
|
|
virtual bool IsSymbolLibWritable( const wxString& aLibraryPath );
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Append supported #SCH_PLUGIN options to \a aListToAppenTo along with internationalized
|
2016-10-09 12:29:44 +00:00
|
|
|
* descriptions. Options are typically appended so that a derived SCH_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 Symbol*() functions in all derived
|
|
|
|
* SCH_PLUGINs.) Note that since aListToAppendTo is a PROPERTIES object, all options
|
|
|
|
* will be unique and last guy wins.
|
2016-07-06 09:22:56 +00:00
|
|
|
*
|
|
|
|
* @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_SCH_PLUGIN_OPTIONS.
|
|
|
|
* It may be multi-line and be quite explanatory of the option.</dd>
|
|
|
|
* </dl>
|
|
|
|
* <br>
|
2017-06-16 00:31:42 +00:00
|
|
|
* In the future perhaps \a aListToAppendTo evolves to something capable of also
|
2016-07-06 09:22:56 +00:00
|
|
|
* 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
|
2017-06-16 00:31:42 +00:00
|
|
|
* #SCH_PLUGIN, which has been avoided to date.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
virtual void SymbolLibOptions( PROPERTIES* aListToAppendTo ) const;
|
|
|
|
|
2017-06-21 12:41:00 +00:00
|
|
|
/**
|
2017-12-07 00:10:45 +00:00
|
|
|
* Return true if the first line in @a aFileName begins with the expected header.
|
|
|
|
*
|
2017-06-21 12:41:00 +00:00
|
|
|
* @param aFileName is the name of the file to use as input
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
virtual bool CheckHeader( const wxString& aFileName );
|
|
|
|
|
2017-12-07 00:10:45 +00:00
|
|
|
/**
|
|
|
|
* Return an error string to the caller.
|
|
|
|
*
|
|
|
|
* This is useful for schematic loaders that can load partial schematics where throwing
|
|
|
|
* an exception would be problematic such as the KiCad legacy plugin.
|
|
|
|
*
|
|
|
|
* @return an unformatted string containing errors if any.
|
|
|
|
*/
|
|
|
|
virtual const wxString& GetError() const;
|
|
|
|
|
2016-07-06 09:22:56 +00:00
|
|
|
//-----</PUBLIC SCH_PLUGIN API>------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
/* The compiler writes the "zero argument" constructor for a SCH_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 SCH_IO_MGR uses. Parameters may be
|
|
|
|
passed into a SCH_PLUGIN via the PROPERTIES variable for any of the public
|
|
|
|
API functions which take one.
|
|
|
|
*/
|
|
|
|
virtual ~SCH_PLUGIN() { }
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
2017-06-16 00:31:42 +00:00
|
|
|
* Helper object to release a #SCH_PLUGIN in the context of a potential thrown exception
|
|
|
|
* through its destructor.
|
2016-07-06 09:22:56 +00:00
|
|
|
*/
|
|
|
|
class SCH_PLUGIN_RELEASER
|
|
|
|
{
|
|
|
|
SCH_PLUGIN* plugin;
|
|
|
|
|
|
|
|
// private assignment operator so it's illegal
|
|
|
|
SCH_PLUGIN_RELEASER& operator=( SCH_PLUGIN_RELEASER& aOther ) { return *this; }
|
|
|
|
|
|
|
|
// private copy constructor so it's illegal
|
|
|
|
SCH_PLUGIN_RELEASER( const SCH_PLUGIN_RELEASER& aOther ) {}
|
|
|
|
|
|
|
|
public:
|
2021-03-25 14:07:16 +00:00
|
|
|
SCH_PLUGIN_RELEASER( SCH_PLUGIN* aPlugin = nullptr ) :
|
2016-07-06 09:22:56 +00:00
|
|
|
plugin( aPlugin )
|
|
|
|
{
|
|
|
|
}
|
|
|
|
|
|
|
|
~SCH_PLUGIN_RELEASER()
|
|
|
|
{
|
|
|
|
if( plugin )
|
|
|
|
release();
|
|
|
|
}
|
|
|
|
|
|
|
|
void release()
|
|
|
|
{
|
|
|
|
SCH_IO_MGR::ReleasePlugin( plugin );
|
2021-03-25 14:07:16 +00:00
|
|
|
plugin = nullptr;
|
2016-07-06 09:22:56 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
void set( SCH_PLUGIN* aPlugin )
|
|
|
|
{
|
|
|
|
if( plugin )
|
|
|
|
release();
|
|
|
|
plugin = aPlugin;
|
|
|
|
}
|
|
|
|
|
|
|
|
operator SCH_PLUGIN* () const
|
|
|
|
{
|
|
|
|
return plugin;
|
|
|
|
}
|
|
|
|
|
|
|
|
SCH_PLUGIN* operator -> () const
|
|
|
|
{
|
|
|
|
return plugin;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
};
|
|
|
|
|
|
|
|
#endif // _SCH_IO_MGR_H_
|