Commit 64010ac8 authored by Jan Möbius's avatar Jan Möbius

Documentation for FileInterface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11147 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 4eda6af5
......@@ -47,15 +47,19 @@
#include <QtGui>
#include <OpenFlipper/common/Types.hh>
/** \brief Interface class for file and object handling
/** \file FileInterface.hh
*
* Interface class for file handling.\ref fileInterfacePage
*/
/** \brief Interface class for file handling.
*
* \ref fileInterfacePage "Detailed description"
* \n
*
* This interface class has to be fully implemented. When you want to support save and load
* for an object type you have to implement all functions in this class. The core manages the
* load and save interaction and gives the load and save actions to your plugin. The decision
* which plugin is called for saving an object depends on your supportedTypes() and the filters
* defined by your plugin.
* Loading and saving of files in OpenFlipper is handled via the file plugins.
* These have to implement this class.
*/
class FileInterface {
//===========================================================================
......@@ -73,18 +77,18 @@ class FileInterface {
*
* _currentFilter: one filter from saveFilters
*
* Return 0 when you dont need one
* Return 0 when you don't need one
*/
virtual QWidget* saveOptionsWidget(QString /*_currentFilter*/) = 0;
virtual QWidget* saveOptionsWidget(QString _currentFilter) = 0;
/** You can provide a special widget showing options for loading your file types
* depending on the current filter
*
* _currentFilter: one filter from loadFilters
*
* Return 0 when you dont need one
* Return 0 when you don't need one
*/
virtual QWidget* loadOptionsWidget(QString /*_currentFilter*/) = 0;
virtual QWidget* loadOptionsWidget(QString _currentFilter) = 0;
/** @} */
......@@ -97,14 +101,14 @@ public:
/** \brief Return your supported object type( e.g. DATA_TRIANGLE_MESH )
*
* If you support multiple datatypes you can use the bitwise or to combine them here.
* The function is used from addEmpty to check if your plugin can create an object of
* a given dataType.
* If you support multiple DataTypes you can combine them bitwise here.
* The function is used from the load and save code to check if your plugin
* can handle an object of a given dataType.
*/
virtual DataType supportedType() = 0;
/** Return the Qt Filters for Filedialogs when loading files (e.g. "Off files ( *.off )" )
/** Return the Qt Filters for File dialogs when loading files (e.g. "Off files ( *.off )" )
*
*/
virtual QString getLoadFilters() = 0;
......@@ -129,7 +133,7 @@ signals:
*
* @param _id Id of the new object
*/
virtual void openedFile( int /*_id*/ ) {};
virtual void openedFile( int _id ) {};
public slots:
......@@ -152,7 +156,7 @@ public slots:
* telling the core that it was successfully loaded but no new object
* has been created!
*/
virtual int loadObject(QString /*_filename*/) = 0;
virtual int loadObject(QString _filename) = 0;
/** \brief Load an object from the given file
*
......@@ -168,7 +172,7 @@ public slots:
* one of these DataTypes can be forced here
*
*/
virtual int loadObject(QString /*_filename*/, DataType /*_type*/){ return -1;};
virtual int loadObject(QString _filename, DataType _type){ return -1;};
/** \brief Save an object from the given file
*
......@@ -177,7 +181,7 @@ public slots:
* provided dataTypes ( see supportedType ).
* Additionally to the filename you get the id of the object to save
*/
virtual bool saveObject(int /*_id*/, QString /*_filename*/) = 0;
virtual bool saveObject(int _id, QString _filename) = 0;
/** \brief Save multiple objects to one file
*
......@@ -186,11 +190,149 @@ public slots:
* provided dataTypes ( see supportedType ).
* Additionally to the filename you get ids of the objects to save
*/
virtual bool saveObjects(IdList /*_ids*/, QString /*_filename*/){return false;};
virtual bool saveObjects(IdList _ids, QString _filename){return false;};
/** @} */
};
Q_DECLARE_INTERFACE(FileInterface,"OpenFlipper.FileInterface/0.3")
/** \page fileInterfacePage File Interface
* \n
\image html FileInterface.png
\n
\section fileInterface_Functionality Functionality
This interface class has to be fully implemented. When you want to support save and load
for an object type you have to implement all functions in this class in a file plugin.
The plugin has to be named Plugin-File<FileExtension>. The plugins are loaded directly after the
Type Plugins.
OpenFlipper manages loading and saving of files from the core.
\section fileInterface_filters Load/Save filters and Type Support
In these functions you have to return filters for your supported type. Use the standard format of Qt and
return your filters within the functions FileInterface::getLoadFilters() and FileInterface::getSaveFilters().
OpenFlipper will decide based on the filters, if your plugin is used to handle a load or save request.
Additionally you have to define, which DataTypes your plugin supports via FileInterface::supportedType().
\code
// File types you support when loading files
QString ExamplePlugin::getLoadFilters() {
return QString( tr("Your FileType ( *.ext )") );
}
// File types you support when saving files
QString ExamplePlugin::getSaveFilters() {
return QString( tr("Your FileType ( *.ext )") );
}
// Data types you support in your plugin
DataType ExamplePlugin::supportedType() {
DataType type = DATA_POLY_MESH | DATA_TRIANGLE_MESH | DATA_GROUP;
return type;
}
\endcode
\section fileInterface_widgets Widgets
When an object is loaded or saved via your file plugin, you can present an additional dialog, used to
control your reader/writer.
You have to implement the following functions. If you don't need such a widget, just return a 0.
\code
// In your plugin initialization
void ExamplePlugin::pluginsInitialized() {
// Global variable:
// QWidget* saveOptionsWidget_;
// Create widget
saveOptionsWidget_ = new QWidget(0);
// Setup widget afterwards
// Global variable:
// QWidget* loadOptionsWidget_;
// Create widget
loadOptionsWidget_ = new QWidget(0);
// Setup widget afterwards
}
// Return your widget for save options
QWidget* ExamplePlugin::saveOptionsWidget(QString _currentFilter) {
// Modify widget based on the filter
// ...
// Return widget
return saveOptionsWidget_;
}
// Return your widget for load options
QWidget* ExamplePlugin::loadOptionsWidget(QString _currentFilter) {
// Modify widget based on the filter
// ...
// Return widget
return loadOptionsWidget_;
}
\endcode
\section fileInterface_loading Loading Files
The FileInterface defines two functions for loading files. The first one ( FileInterface::loadObject(QString _filename) ) has
to be implemented. It has to load the data from the given file. The return value of this function has to be the id of the
new object. Additionally you have to
\code
emit FileInterface::openedFile( int _id );
\endcode
with the id of every object you loaded from the file.
If the file contains multiple objects, create a GroupObject and add all loaded objects to that group. Than return
the id of the group here. Don't forget the FileInterface::openedFile() signal for every newly loaded object from the file.
One function that can be implemented is FileInterface::loadObject(QString _filename, DataType _type). This function gets a
DataType along with the filename. This can be used to force a specific DataType when loading objects. E.g. A plugin loading
obj files which handles triangle and polygonal meshes which can than be forced to triangulate every input data.
\section fileInterface_saving Saving Files
The FileInterface defines two functions for loading files. The first one ( FileInterface::saveObject(int _id, QString _filename) )
has to be implemented. It has to save the object with the given id to the file specified by the filename. The return value of
this function has to be true if it succeeded, otherwise false. OpenFlipper will choose your plugin to save the data if two
prerequisites are fulfilled. Your FileInterface::supportedTypes() has to support the DataType of the object and
your save filters have to contain the extension of the file to use. These checks are done within OpenFlipper such that
you only get information that can be handled by the plugin.
Additionally there is a function FileInterface::saveObjects(IdList _ids, QString _filename) which does the same as the above
but saves a set of objects to a file.
\section fileInterface_usage Usage
To use the FileInterface:
<ul>
<li> include FileInterface.hh in your plugins header file
<li> derive your plugin from the class FileInterface
<li> add Q_INTERFACES(FileInterface) to your plugin class
<li> And implement the required slots and functions
</ul>
TODO:
// Deprecated here? In TypeInterface?
virtual int addEmpty() { return -1; };
*/
Q_DECLARE_INTERFACE(FileInterface,"OpenFlipper.FileInterface/1.0")
#endif // FILEINTERFACE_HH
......@@ -148,7 +148,10 @@ class LoadSaveInterface {
};
/** \page loadSaveInterfacePage Load/Save Interface
*
* \n
\image html loadSaveInterface.png
\n
The LoadSaveInterface can be used by plugins to add new objects to the scene either by creating empty objects
or by loading them from files. The interface also triggers saving of existing objects to files.
......
......@@ -55,7 +55,6 @@ The following groups of Interfaces are available:
\section todoInterfaces Interfaces todos for documentation:
BackupInterface
FileInterface
IniInterface
ProcessInterface
TextureInterface
......@@ -70,11 +69,6 @@ This page gives an overview over the available interfaces which control other pa
\image html TextureInterface.png
Allows your plugin to provide a texture. ( TextureInterface )
\subsection FilePlugin File Interface
\image html FileInterface.png
Provides functions to read and write custom filetypes ( FileInterface )
\subsection ViewPlugin View Interface
\image html ViewInterface.png
This interface is used to add additional view widgets ( ViewInterface ).
......@@ -149,6 +143,11 @@ Specify own view modes setting which toolboxes/toolbars/context menus will be vi
/** \page pluginInterfacesDataHandling Object and Data Handling
This page shows interfaces for controlling and adding Objects.
\subpage fileInterfacePage
\image html FileInterface.png
Provides an interface to read and write file types. All load/save plugins need to implement this interface ( \ref fileInterfacePage )
\subpage loadSaveInterfacePage
\image html loadSaveInterface.png
Provides functions to control loading/saving of files and generate new objects. Additionally
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment