[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-devel
Subject: Re: KFile plugins
From: Thomas Kadauke <tkadauke () gmx ! de>
Date: 2005-10-14 18:33:16
Message-ID: 200510142033.16547.tkadauke () gmx ! de
[Download RAW message or body]
Am Thursday 13 October 2005 21:52 schrieb Adriaan de Groot:
> To some extent, these tutorials should be _in_ the APIDOX, as extra pages
> or as overview documentation for the classes (or a collection of classes)
> so that (a) they're available everywhere (b) easier to find (by just
> looking at the documentation) (c) they get checked for validity and
> accuracy regularly. So your offer to extend the dox is still in force?
I changed the documentation of KFilePlugin (see attached file). Please tell me
if it is good or not. If yes, I will work on the other documentation and post
a diff. Note that I didn't change the public part of the class'
documentation.
["kfileplugin.h" (text/x-c++hdr)]
/**
* @short Base class for a meta information plugin.
*
* Meta information plugins are used to extract useful information from
* files of a given type. These plugins are used in Konqueror's file
* properties dialog, for example.
*
* If you want to write your own plugin, you need to derive from this class.
*
* In the constructor of your class, you need to call addMimeTypeInfo to
* tell the KFile framework which mimetype(s) your plugin supports. For
* each mimetype, use the addGroupInfo and addItemInfo methods to declare
* the meta information items the plugin calculates and to group them
* accordingly. For groups, use setAttributes to customize your group (see
* KFileMimeTypeInfo::Attributes). For items, use setAttributes to define
* the behaviour of the item; use setHint to define the meaning of the item;
* use setUnit to define the Unit, such as KFileMimeTypeInfo::Seconds or
* KFileMimeTypeInfo::KiloBytes. In short, the constructor defines the
* data structure of the meta information supported by your plugin.
*
* Example:
* \code
* FooPlugin::FooPlugin(QObject *parent, const char *name,
* const QStringList &args)
* : KFilePlugin(parent, name, args)
* {
* KFileMimeTypeInfo* info = addMimeTypeInfo( "application/x-foo" );
*
* // our new group
* KFileMimeTypeInfo::GroupInfo* group = 0L;
* group = addGroupInfo(info, "FooInfo", i18n("Foo Information"));
*
* KFileMimeTypeInfo::ItemInfo* item;
*
* // our new items in the group
* item = addItemInfo(group, "Items", i18n("Items"), QVariant::Int);
* item = addItemInfo(group, "Size", i18n("Size"), QVariant::Int);
* setUnit(item, KFileMimeTypeInfo::KiloBytes);
*
* // strings are possible, too:
* //addItemInfo(group, "Document Type", i18n("Document type"), QVariant::String);
* }
* \endcode
*
* Some meta information items are likely to be available in several
* different file formats, such as "Author", "Title" (for documents), and
* "Length" (for multimedia files). Be sure to use the naming scheme from
* existing plugins for your meta information items if possible. If, for
* example, the meta information of a group of files is shown in a table
* view, this will allow two files to share the same column (say "Length")
* even if they are of a different file type.
*
* You must overwrite the readInfo method. In this method you need to
* extract the meta information of the given file. You can use a third-party
* library to achieve this task. This might be the best way for binary
* files, since a change in the file format is likely to be supported by
* subsequent releases of that library. Alternatively, for text-based file
* formats, you can use QTextStream to parse the file. For simple file
* formats, QRegExp can be of great help, too.
*
* After you extracted the relevant information, use appendGroup and
* appendItem to fill the meta information data structure (as defined in the
* constructor) with values. Note that you can leave out groups or items
* which are not appropriate for a particular file.
*
* Example:
* \code
* bool FooPlugin::readInfo( KFileMetaInfo& info, uint what)
* {
* int numItems = 0;
* int size = 0;
*
* // do your calculations here, e.g. using a third-party
* // library or by writing an own parser using e.g. QTextStream
*
* // calculate numItems and size ...
*
* // note: use the same key strings as in the constructor
* KFileMetaInfoGroup group = appendGroup(info, "FooInfo");
*
* appendItem(group, "Items", numItems);
* appendItem(group, "Size", size);
*
* return true;
* }
* \endcode
*
* If you want to define mutable meta information items, you need to
* overwrite the writeInfo method. In this method, you can use third-party
* library (appropriate mostly for binary files, see above) or QTextStream
* to write the information back to the file. If you use QTextStream, be sure
* to write all file contents back.
*
* For some items, it might be that not all possible values are allowed.
* You can overwrite the createValidator method to define constraints for
* a meta information item. For example, the Year field for an MP3 file could
* reject values outside the range 1500 - 2050 (at least for now). The
* validator is used to check values before the writeInfo method is called
* so that writeInfo is only provided correct values.
*
* In your plugin, you need to create a factory for the KFilePlugin
*
* Example:
* \code
* typedef KGenericFactory<FooPlugin> FooFactory;
* K_EXPORT_COMPONENT_FACTORY(kfile_foo, FooFactory("kfile_foo"));
* \endcode
*
* To make your plugin available within KDE, you also need to provide a
* .desktop file which describes your plugin. The required fields in the
* file are
*
* - Type: must be "Service"
* - Name: the name of the plugin
* - ServiceTypes: must contain "KFilePlugin"
* - X-KDE-Library: the name of the library containing the KFile plugin
* - MimeType: the mimetype(s) which are supported by the plugin
* - PreferredGroups: a comma-separated list of the most important groups.
* This list defines the order in which the meta information groups
* should be displayed
* - PreferredItems: a comma-separated list of the most important items.
* This list defines the order in which the meta information items
* should be displayed
*
* Example:
* \code
* [Desktop Entry]
* Encoding=UTF-8
* Type=Service
* Name=Foo Info
* ServiceTypes=KFilePlugin
* X-KDE-Library=kfile_foo
* MimeType=application/x-foo
* PreferredGroups=FooInfo
* PreferredItems=Items,Size
* \endcode
**/
class KIO_EXPORT KFilePlugin : public QObject
{
Q_OBJECT
public:
/**
* Creates a new KFilePlugin instance.
* @param parent the parent of the QObject, can be 0
* @param name the name of the QObject, can be 0
* @param args currently ignored
*/
KFilePlugin( QObject *parent, const char *name,
const QStringList& args );
virtual ~KFilePlugin();
/**
* Read the info from the file in this method and insert it into the
* provided KFileMetaInfo object. You can get the path to
* the file with info.path()
* @param info the information will be written here
* @param what defines what to read, see KFileMetaInfo::What
* @return true if successful, false if it failed
**/
virtual bool readInfo( KFileMetaInfo& info,
uint what = KFileMetaInfo::Fastest ) = 0;
/**
* Similar to the above method, but for writing the info back to the file.
* If you don't have any writable keys, don't implement this method
* @param info the information that will be written
* @return true if successful, false if it failed
**/
virtual bool writeInfo( const KFileMetaInfo& info ) const
{
Q_UNUSED(info);
return true;
}
/**
* This method should create an appropriate validator for the specified
* item if it's editable or return a null pointer if not. If you don't
* have any editable items, you don't need this method.
*
* If you you don't need any validation, e.g. you accept any input,
* you can simply return 0L, or not reimplement this method at all.
* @param mimeType the mime type
* @param group the group name of the validator item
* @param key the key name of the validator item
* @param parent the QObject parent, can be 0
* @param name the name of the QObject, can be 0
**/
virtual QValidator* createValidator( const QString& mimeType,
const QString& group,
const QString& key,
QObject* parent,
const char* name) const
{
Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
Q_UNUSED(parent);Q_UNUSED(name);
return 0;
}
protected:
/**
* Creates a meta information group for KFileMimeTypeInfo object returned
* by addMimeTypeInfo.
*
* @param info the object returned by addMimeTypeInfo
* @param key a unique string identifiing this group. For simplicity it is
* recommended to use the same string as for the translatedKey
* parameter
* @param translatedKey the translated version of the key string for
* displaying in user interfaces. Use i18n() to translate the string
* @return a GroupInfo object. Pass this object to addItemInfo to add meta
* information attributed to this group.
* @see setAttributes, addItemInfo
*/
KFileMimeTypeInfo::GroupInfo* addGroupInfo(KFileMimeTypeInfo* info,
const QString& key, const QString& translatedKey) const;
/**
* Sets attributes of the GroupInfo object returned by addGroupInfo.
*
* @param gi the object returned by addGroupInfo
* @param attr the attributes for this group; these are values of type
* KFileMimeTypeInfo::Attributes, or'ed together
*/
void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
uint attr) const;
/**
* Adds a meta information item to a GroupInfo object as returned by
* addGroupInfo.
*
* @param gi the GroupInfo object to add a new item to
* @param key a unique string to identify this item. For simplicity it is
* recommended to use the same string as for the translatedKey
* parameter
* @param translatedKey the translated version of the key string for
* displaying in user interfaces. Use i18n() to translate the string
* @param type the type of the meta information item, e.g. QVariant::Int
* or QVariant::String.
* @return an ItemInfo object. Pass this object to setAttributes
*/
KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
const QString& key,
const QString& translatedKey,
QVariant::Type type);
/**
* Sets some attributes for a meta information item. The attributes describe
* if the item is mutable, how it should be computed for a list of files, and
* how it should be displayed
*
* @param item the ItemInfo object as returned by addItemInfo
* @param attr the attributes for this item; these are values of type
* KFileMimeTypeInfo::Attributes, or'ed together
*/
void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
/**
* Defines the meaning of the meta information item. Some applications make use
* of this information, so be sure to check KFileMimeTypeInfo::Hint to see if
* an item's meaning is in the list.
*
* @param item the ItemInfo object as returned by addItemInfo
* @param hint the item's meaning. See KFileMimeTypeInfo::Hint for a list of
* available meanings
*/
void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
/**
* Sets the unit used in the meta information item. This unit is used to format
* the value and to make large values human-readable. For example, if the item's
* unit is KFileMimeTypeInfo::Seconds and the value is 276, it will be displayed
* as 4:36.
*
* @param item the ItemInfo object as returned by addItemInfo
* @param unit the item's unit. See KFileMimeTypeInfo::Unit for a list of
* available units
*/
void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
/**
* Sets a prefix string which is displayed before the item's value. Use this
* string if no predefined unit fits the item's unit. Be sure to translate the
* string with i18n()
*
* @param item the ItemInfo object as returned by addItemInfo
* @param prefix the prefix string to display
*/
void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
/**
* Sets a suffix string which is displayed before the item's value. Use this
* string if no predefined unit fits the item's unit. Be sure to translate the
* string with i18n()
*
* @param item the ItemInfo object as returned by addItemInfo
* @param prefix the suffix string to display
*/
void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
/**
* Call this method from within readInfo to indicate that you wish to fill
* meta information items of the group identified by @p key with values.
*
* @param info the KFileMetaInfo object. Use the parameter of the readInfo
* method
* @param key the key string to identify the group. Use the string that you
* defined in your class' constructor
* @return a KFileMetaInfoGroup object, to be used in appendItem
*/
KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
/**
* Call this method form within readInfo to fill the meta information item
* identified by @p key with a value.
*
* @param group the KFileMetaInfoGroup object, as returned by appendGroup
* @param key the key string to identify the item.
*/
void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
/**
* Call this from within your constructor to tell the KFile framework what
* mimetypes your plugin supports.
*
* @param mimeType a string containing the mimetype, e.g. "text/html"
* @return a KFileMimeTypeInfo object, to be used with addGroupInfo
*/
// ### do we need this, if it only calls the provider?
// IMHO the Plugin shouldn't call its provider.
// DF: yes we need this. A plugin can create more than one mimetypeinfo.
// What sucks though, is to let plugins do that in their ctor.
// Would be much simpler to have a virtual init method for that,
// so that the provider can set up stuff with the plugin pointer first!
KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
QStringList m_preferredKeys;
QStringList m_preferredGroups;
protected:
virtual void virtual_hook( int id, void* data );
private:
class KFilePluginPrivate;
KFilePluginPrivate *d;
};
=
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscrib=
e <<
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic