org.kde.koala

Class KFilePlugin

public class KFilePlugin extends QObject

UNKNOWN: 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: FooPlugin.FooPlugin(QObject parent, String name, ArrayListargs) { KFileMimeTypeInfo info = addMimeTypeInfo( "application/x-foo" ); // our new group KFileMimeTypeInfo.GroupInfo group = null; 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); } Some meta information items are likely to be available in several different file formats, such as @c "Author", @c "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: boolean 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; } 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 @c "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: typedef KGenericFactory FooFactory; K_EXPORT_COMPONENT_FACTORY(kfile_foo, FooFactory("kfile_foo")); 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 @c "Service" - Name: the name of the plugin - ServiceTypes: must contain @c "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: [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 @brief Base class for a meta information plugin

Constructor Summary
protected KFilePlugin(Class dummy)
Method Summary
StringclassName()
QValidatorcreateValidator(String mimeType, String group, String key, QObject parent, String name)
This method should create an appropriate validator for the specified item if it's editable or return a null pointer if not.
QMetaObjectmetaObject()
booleanreadInfo(KFileMetaInfo info, int what)
Read the info from the file in this method and insert it into the provided KFileMetaInfo object.
booleanreadInfo(KFileMetaInfo info)
booleanwriteInfo(KFileMetaInfo info)
Similar to the readInfo() but for writing the info back to the file.

Constructor Detail

KFilePlugin

protected KFilePlugin(Class dummy)

Method Detail

className

public String className()

createValidator

public QValidator createValidator(String mimeType, String group, String key, QObject parent, String name)
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 to implement this method. If you you don't need any validation, e.g. you accept any input, you can simply return null, or not reimplement this method at all.

Parameters: mimeType the mime type group the group name of the validator item key the key name of the validator item parent the QObject parent, can be 0 name the name of the QObject, can be 0

UNKNOWN: This method should create an appropriate validator for the specified item if it's editable or return a null pointer if not.

metaObject

public QMetaObject metaObject()

readInfo

public boolean readInfo(KFileMetaInfo info, int what)
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 KFileMetaInfo.path(). Use appendGroup() and appendItem() to fill info with the extracted values

Parameters: info the information will be written here what defines what to read, see KFileMetaInfo.What

Returns: @c true if successful, @c false if it failed

See Also: KFilePlugin

UNKNOWN: Read the info from the file in this method and insert it into the provided KFileMetaInfo object.

readInfo

public boolean readInfo(KFileMetaInfo info)

writeInfo

public boolean writeInfo(KFileMetaInfo info)
Similar to the readInfo() but for writing the info back to the file. If you don't have any writable keys, don't implement this method

Parameters: info the information that will be written

Returns: @c true if successful, @c false if it failed

UNKNOWN: Similar to the readInfo() but for writing the info back to the file.