--Boundary-00=_6+AUDbPVQD2wunm Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline 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 --Boundary-00=_6+AUDbPVQD2wunm Content-Type: text/x-diff; charset="iso-8859-1"; name="kfileplugindoc.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="kfileplugindoc.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 MyFactory; - * K_EXPORT_COMPONENT_FACTORY(kfile_foo, MyFactory("kfile_foo")); - * \endcode + * @code + * typedef KGenericFactory 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; --Boundary-00=_6+AUDbPVQD2wunm Content-Type: text/plain; charset="iso-8859-1" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Disposition: inline = >> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscrib= e << --Boundary-00=_6+AUDbPVQD2wunm--