[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 20:06:18
Message-ID: 200510142206.18468.tkadauke () gmx ! de
[Download RAW message or body]
Am Friday 14 October 2005 20:33 schrieb Thomas Kadauke:
> 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.
The other documentation actually looks pretty good. Here's my patch (against
kdelibs) with my changes.
Thanks for all your help
--Thomas
["kfileplugindoc.diff" (text/x-diff)]
Index: kio/kio/kfilemetainfo.h
===================================================================
--- kio/kio/kfilemetainfo.h (revision 470597)
+++ kio/kio/kfilemetainfo.h (working copy)
@@ -1108,7 +1108,7 @@
*/
bool containsGroup( const QString& key ) const;
- /*
+ /**
* Returns the value with the given @p key.
* @param key the key to retrieve
* @return the value. Invalid if it does not exist
@@ -1183,21 +1183,141 @@
/**
- * Baseclass for a meta info plugin. If you want to write your own plugin,
- * you need to derive from this class.
+ * @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<MyPlugin> MyFactory;
- * K_EXPORT_COMPONENT_FACTORY(kfile_foo, MyFactory("kfile_foo"));
- * \endcode
+ * @code
+ * typedef KGenericFactory<FooPlugin> FooFactory;
+ * K_EXPORT_COMPONENT_FACTORY(kfile_foo, FooFactory("kfile_foo"));
+ * @endcode
*
- * and then just overwrite the methods your plugin supports. If your plugin
- * can only read data, it is sufficient to only write a readInfo() method.
- * If you also want to support changing data and writing it back into the
- * file, you usually need all methods.
+ * 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:
+ *
+ * - @c Type: must be "Service"
+ * - @c Name: the name of the plugin
+ * - @c ServiceTypes: must contain "KFilePlugin"
+ * - @c X-KDE-Library: the name of the library containing the KFile plugin
+ * - @c MimeType: the mimetype(s) which are supported by the plugin
+ * - @c PreferredGroups: a comma-separated list of the most important groups.
+ * This list defines the order in which the meta information groups should be
+ * displayed
+ * - @c 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
{
@@ -1205,11 +1325,13 @@
public:
/**
- * Creates a new KFilePlugin instance.
+ * Creates a new KFilePlugin instance. You need to implement a constructor
+ * with the same argument list as this is required by KGenericFactory
+ *
* @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 );
@@ -1217,11 +1339,13 @@
/**
* 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()
+ * provided KFileMetaInfo object. You can get the path to the file with
+ * info.path(). Use appendGroup() and appendItem() to fill @p info with the
+ * extracted values
+ *
* @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
+ * @return @c true if successful, @c false if it failed
**/
virtual bool readInfo( KFileMetaInfo& info,
uint what = KFileMetaInfo::Fastest ) = 0;
@@ -1230,7 +1354,7 @@
* 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
+ * @return @c true if successful, @c false if it failed
**/
virtual bool writeInfo( const KFileMetaInfo& info ) const
{
@@ -1240,11 +1364,12 @@
/**
* 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.
+ * item if it's editable or return a null pointer if not. If you don't have
+ * any editable items, you don't need to implement 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.
+ * 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
@@ -1264,33 +1389,145 @@
protected:
+ /**
+ * 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 );
+
+ /**
+ * 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 suffix 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);
- void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
/**
- * Call this in your constructor
- */
- // ### 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 );
+ * Call this method form within readInfo to fill the meta information item
+ * identified by @p key with a @p value
+ *
+ * @param group the KFileMetaInfoGroup object, as returned by appendGroup()
+ * @param key the key string to identify the item.
+ * @param value the value of the meta information item
+ **/
+ void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
QStringList m_preferredKeys;
QStringList m_preferredGroups;
=
>> 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