Improved PLUGIN documentation in io_mgr.h

This commit is contained in:
Dick Hollenbeck 2011-12-02 10:28:00 -06:00
parent 6418163d3c
commit 0bdef38585
1 changed files with 56 additions and 23 deletions

View File

@ -54,6 +54,8 @@ public:
enum PCB_FILE_T enum PCB_FILE_T
{ {
KICAD, KICAD,
// add your type here.
// EAGLE, // EAGLE,
// ALTIUM, // ALTIUM,
// etc. // etc.
@ -77,7 +79,8 @@ public:
* Function PluginRelease * Function PluginRelease
* releases a PLUGIN back to the system, and may cause it to be unloaded from memory. * releases 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. * @param aPlugin is the one to be released, and which is no longer usable
* after calling this.
*/ */
static void PluginRelease( PLUGIN* aPlugin ); static void PluginRelease( PLUGIN* aPlugin );
@ -89,7 +92,9 @@ public:
/** /**
* Function Load * Function Load
* finds the requested PLUGIN and loads a BOARD, or throws an exception trying. * 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.
* *
* @param aFileType is the PCB_FILE_T of file to load. * @param aFileType is the PCB_FILE_T of file to load.
* *
@ -109,7 +114,23 @@ public:
static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName, static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
BOARD* aAppendToMe = NULL, PROPERTIES* aProperties = NULL ); BOARD* aAppendToMe = NULL, PROPERTIES* aProperties = NULL );
// etc. /**
* Function Save
* will write 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.
*
* @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 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.
*
* @throw IO_ERROR if there is a problem saving or exporting.
*/
static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
PROPERTIES* aProperties = NULL );
}; };
@ -123,7 +144,9 @@ public:
* <pre> * <pre>
* try * try
* { * {
* pi->Load(...); * IO_MGR::Load(...);
* or
* IO_MGR::Save(...);
* } * }
* catch( IO_ERROR ioe ) * catch( IO_ERROR ioe )
* { * {
@ -170,41 +193,47 @@ public:
}; };
//-----<PUBLIC PLUGIN API>-------------------------------------------------
/** /**
* Function PluginName * Function PluginName
* returns a brief hard coded name for this PLUGIN. * returns a brief hard coded name for this PLUGIN.
*/ */
virtual const wxString& PluginName() = 0; virtual const wxString& PluginName() = 0;
//-----<BOARD STUFF>----------------------------------------------------
/** /**
* Function Load * Function Load
* loads a board file from some input file format that this implementation * loads a board file, or a portion of one, from some input file format
* knows about. * that this PLUGIN implementation knows about. 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 load and may be foreign in * @param aFileName is the name of the file to use as input and may be foreign in
* nature or native in nature. * nature or native in nature.
* *
* @param aAppendToMe is an existing BOARD to append to but is often NULL * @param aAppendToMe is an existing BOARD to append to, but if NULL then
* meaning do not append. * this means "do not append, rather load anew".
* *
* @param aProperties is an associative array that can be used to tell the * @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 * loader how to load the file, because it can take any number of
* additional named arguments that the plugin is known to support. * 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.
* *
* @return BOARD* - the successfully loaded board, and caller owns it. * @return BOARD* - the successfully loaded board, or the same one as aAppendToMe
* if aAppendToMe was not NULL, and caller owns it.
* *
* @throw IO_ERROR if there is a problem loading, and its contents should * @throw IO_ERROR if there is a problem loading, and its contents should
* say what went wrong. * say what went wrong, using line number and character offsets of the
* input file if possible.
*/ */
virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe, virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
PROPERTIES* aProperties = NULL ); PROPERTIES* aProperties = NULL );
/** /**
* Function Save * Function Save
* will write a full aBoard to a storage file in a format that only this * will write 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 * PLUGIN implementation knows about, or it can be used to write a portion of
* aBoard to a special kind of export file. * aBoard to a special kind of export file.
* *
* @param aFileName is the name of a file to save to on disk. * @param aFileName is the name of a file to save to on disk.
@ -212,19 +241,23 @@ public:
* *
* @param aProperties is an associative array that can be used to tell the * @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 * saver how to save the file, because it can take any number of
* additional named arguments that the plugin is known to support. * 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 loading. * @throw IO_ERROR if there is a problem saving or exporting.
*/ */
virtual void Save( const wxString* aFileName, BOARD* aBoard, virtual void Save( const wxString* aFileName, BOARD* aBoard,
PROPERTIES* aProperties = NULL ); PROPERTIES* aProperties = NULL );
//-----</BOARD STUFF>--------------------------------------------------- //-----</PUBLIC PLUGIN API>------------------------------------------------
};
#if 0 #if 0
///--------- Should split into two PLUGIN base types here, rather than being combined like this
//-----<SCHEMATIC STUFF>------------------------------------------------ //-----<SCHEMATIC STUFF>------------------------------------------------
// Should split into schematic specific PLUGIN base type
/** /**
* Function Load * Function Load
@ -242,7 +275,7 @@ public:
/** /**
* Function Save * Function Save
* will write aBoard to a storage file in a format that only this * will write aSchematic to a storage file in a format that only this
* implementation knows about. * implementation knows about.
* *
* @param aFileName is the name of a file to save to on disk. * @param aFileName is the name of a file to save to on disk.
@ -258,6 +291,6 @@ public:
//-----</SCHEMATIC STUFF>---------------------------------------------- //-----</SCHEMATIC STUFF>----------------------------------------------
#endif #endif
};
#endif // IO_MGR_H_ #endif // IO_MGR_H_