• Skip to content
  • Skip to link menu
Trinity API Reference
  • Trinity API Reference
  • tdeio/tdeio
 

tdeio/tdeio

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
KFilePlugin Class Referenceabstract

#include <tdefilemetainfo.h>

Inherits TQObject.

Public Member Functions

 KFilePlugin (TQObject *parent, const char *name, const TQStringList &args)
 
virtual ~KFilePlugin ()
 
virtual bool readInfo (KFileMetaInfo &info, uint what=KFileMetaInfo::Fastest)=0
 
virtual bool writeInfo (const KFileMetaInfo &info) const
 
virtual TQValidator * createValidator (const TQString &mimeType, const TQString &group, const TQString &key, TQObject *parent, const char *name) const
 

Protected Member Functions

KFileMimeTypeInfo * addMimeTypeInfo (const TQString &mimeType)
 
KFileMimeTypeInfo::GroupInfo * addGroupInfo (KFileMimeTypeInfo *info, const TQString &key, const TQString &translatedKey) const
 
void setAttributes (KFileMimeTypeInfo::GroupInfo *gi, uint attr) const
 
void addVariableInfo (KFileMimeTypeInfo::GroupInfo *gi, TQVariant::Type type, uint attr) const
 
KFileMimeTypeInfo::ItemInfo * addItemInfo (KFileMimeTypeInfo::GroupInfo *gi, const TQString &key, const TQString &translatedKey, TQVariant::Type type)
 
void setAttributes (KFileMimeTypeInfo::ItemInfo *item, uint attr)
 
void setHint (KFileMimeTypeInfo::ItemInfo *item, uint hint)
 
void setUnit (KFileMimeTypeInfo::ItemInfo *item, uint unit)
 
void setPrefix (KFileMimeTypeInfo::ItemInfo *item, const TQString &prefix)
 
void setSuffix (KFileMimeTypeInfo::ItemInfo *item, const TQString &suffix)
 
KFileMetaInfoGroup appendGroup (KFileMetaInfo &info, const TQString &key)
 
void appendItem (KFileMetaInfoGroup &group, const TQString &key, TQVariant value)
 
virtual void virtual_hook (int id, void *data)
 

Protected Attributes

TQStringList m_preferredKeys
 
TQStringList m_preferredGroups
 

Detailed Description

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(TQObject *parent, const char *name,
const TQStringList &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"), TQVariant::Int);
item = addItemInfo(group, "Size", i18n("Size"), TQVariant::Int);
setUnit(item, KFileMimeTypeInfo::KiloBytes);
// strings are possible, too:
//addItemInfo(group, "Document Type", i18n("Document type"), TQVariant::String);
}

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 TQTextStream to parse the file. For simple file formats, TQRegExp 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:

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;
}

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 TQTextStream to write the information back to the file. If you use TQTextStream, 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:

typedef KGenericFactory<FooPlugin> FooFactory;
K_EXPORT_COMPONENT_FACTORY(tdefile_foo, FooFactory("tdefile_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 "Service"
  • Name: the name of the plugin
  • ServiceTypes: must contain "KFilePlugin"
  • X-TDE-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-TDE-Library=tdefile_foo
MimeType=application/x-foo
PreferredGroups=FooInfo
PreferredItems=Items,Size

Definition at line 1394 of file tdefilemetainfo.h.

Constructor & Destructor Documentation

KFilePlugin::KFilePlugin ( TQObject *  parent,
const char *  name,
const TQStringList &  args 
)

Creates a new KFilePlugin instance.

You need to implement a constructor with the same argument list as this is required by KGenericFactory

Parameters
parentthe parent of the TQObject, can be 0
namethe name of the TQObject, can be 0
argscurrently ignored
See also
addMimeTypeInfo()
addGroupInfo()
addItemInfo()
TQObject()

Definition at line 781 of file tdefilemetainfo.cpp.

KFilePlugin::~KFilePlugin ( )
virtual

Destructor.

Definition at line 788 of file tdefilemetainfo.cpp.

Member Function Documentation

KFileMimeTypeInfo::GroupInfo * KFilePlugin::addGroupInfo ( KFileMimeTypeInfo *  info,
const TQString &  key,
const TQString &  translatedKey 
) const
protected

Creates a meta information group for KFileMimeTypeInfo object returned by addMimeTypeInfo().

Parameters
infothe object returned by addMimeTypeInfo()
keya unique string identifiing this group. For simplicity it is recommended to use the same string as for the translatedKey parameter
translatedKeythe translated version of the key string for displaying in user interfaces. Use i18n() to translate the string
Returns
a GroupInfo object. Pass this object to addItemInfo to add meta information attributed to this group.
See also
setAttributes()
addItemInfo()

Definition at line 802 of file tdefilemetainfo.cpp.

KFileMimeTypeInfo::ItemInfo * KFilePlugin::addItemInfo ( KFileMimeTypeInfo::GroupInfo *  gi,
const TQString &  key,
const TQString &  translatedKey,
TQVariant::Type  type 
)
protected

Adds a meta information item to a GroupInfo object as returned by addGroupInfo().

Parameters
githe GroupInfo object to add a new item to
keya unique string to identify this item. For simplicity it is recommended to use the same string as for the translatedKey parameter
translatedKeythe translated version of the key string for displaying in user interfaces. Use i18n() to translate the string
typethe type of the meta information item, e.g. TQVariant::Int or TQVariant::String.
Returns
an ItemInfo object. Pass this object to setAttributes()

Definition at line 819 of file tdefilemetainfo.cpp.

KFileMimeTypeInfo * KFilePlugin::addMimeTypeInfo ( const TQString &  mimeType)
protected

Call this from within your constructor to tell the KFile framework what mimetypes your plugin supports.

Parameters
mimeTypea string containing the mimetype, e.g. "text/html"
Returns
a KFileMimeTypeInfo object, to be used with addGroupInfo()

Definition at line 793 of file tdefilemetainfo.cpp.

KFileMetaInfoGroup KFilePlugin::appendGroup ( KFileMetaInfo &  info,
const TQString &  key 
)
protected

Call this method from within readInfo() to indicate that you wish to fill meta information items of the group identified by key with values.

Parameters
infothe KFileMetaInfo object. Use the parameter of the readInfo() method
keythe key string to identify the group. Use the string that you defined in your class' constructor
Returns
a KFileMetaInfoGroup object, to be used in appendItem()

Definition at line 894 of file tdefilemetainfo.cpp.

void KFilePlugin::appendItem ( KFileMetaInfoGroup &  group,
const TQString &  key,
TQVariant  value 
)
protected

Call this method from within readInfo() to fill the meta information item identified by key with a value.

Parameters
groupthe KFileMetaInfoGroup object, as returned by appendGroup()
keythe key string to identify the item.
valuethe value of the meta information item

Definition at line 899 of file tdefilemetainfo.cpp.

virtual TQValidator* KFilePlugin::createValidator ( const TQString &  mimeType,
const TQString &  group,
const TQString &  key,
TQObject *  parent,
const char *  name 
) const
inlinevirtual

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 0L, or not reimplement this method at all.

Parameters
mimeTypethe mime type
groupthe group name of the validator item
keythe key name of the validator item
parentthe TQObject parent, can be 0
namethe name of the TQObject, can be 0

Definition at line 1462 of file tdefilemetainfo.h.

virtual bool KFilePlugin::readInfo ( KFileMetaInfo &  info,
uint  what = KFileMetaInfo::Fastest 
)
pure virtual

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
infothe information will be written here
whatdefines what to read, see KFileMetaInfo::What
Returns
true if successful, false if it failed
See also
writeInfo()
void KFilePlugin::setAttributes ( KFileMimeTypeInfo::GroupInfo *  gi,
uint  attr 
) const
protected

Sets attributes of the GroupInfo object returned by addGroupInfo().

Parameters
githe object returned by addGroupInfo()
attrthe attributes for this group; these are values of type KFileMimeTypeInfo::Attributes, or'ed together

Definition at line 808 of file tdefilemetainfo.cpp.

void KFilePlugin::setAttributes ( KFileMimeTypeInfo::ItemInfo *  item,
uint  attr 
)
protected

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

Parameters
itemthe ItemInfo object as returned by addItemInfo()
attrthe attributes for this item; these are values of type KFileMimeTypeInfo::Attributes, or'ed together

Definition at line 827 of file tdefilemetainfo.cpp.

void KFilePlugin::setHint ( KFileMimeTypeInfo::ItemInfo *  item,
uint  hint 
)
protected

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.

Parameters
itemthe ItemInfo object as returned by addItemInfo()
hintthe item's meaning. See KFileMimeTypeInfo::Hint for a list of available meanings

Definition at line 832 of file tdefilemetainfo.cpp.

void KFilePlugin::setPrefix ( KFileMimeTypeInfo::ItemInfo *  item,
const TQString &  prefix 
)
protected

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()

Parameters
itemthe ItemInfo object as returned by addItemInfo()
prefixthe prefix string to display

Definition at line 884 of file tdefilemetainfo.cpp.

void KFilePlugin::setSuffix ( KFileMimeTypeInfo::ItemInfo *  item,
const TQString &  suffix 
)
protected

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()

Parameters
itemthe ItemInfo object as returned by addItemInfo()
suffixthe suffix string to display

Definition at line 889 of file tdefilemetainfo.cpp.

void KFilePlugin::setUnit ( KFileMimeTypeInfo::ItemInfo *  item,
uint  unit 
)
protected

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.

Parameters
itemthe ItemInfo object as returned by addItemInfo()
unitthe item's unit. See KFileMimeTypeInfo::Unit for a list of available units

Definition at line 837 of file tdefilemetainfo.cpp.

void KFilePlugin::virtual_hook ( int  id,
void *  data 
)
protectedvirtual

Helper method to allow binary compatible extensions when needing "new virtual methods".

Parameters
idthe identifier of the new "virtual" method
dataany parameter data the new "virtual" method needs

Definition at line 798 of file tdefilemetainfo.cpp.

virtual bool KFilePlugin::writeInfo ( const KFileMetaInfo &  info) const
inlinevirtual

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
infothe information that will be written
Returns
true if successful, false if it failed

Definition at line 1442 of file tdefilemetainfo.h.


The documentation for this class was generated from the following files:
  • tdefilemetainfo.h
  • tdefilemetainfo.cpp

tdeio/tdeio

Skip menu "tdeio/tdeio"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

tdeio/tdeio

Skip menu "tdeio/tdeio"
  • arts
  • dcop
  • dnssd
  • interfaces
  •   kspeech
  •     interface
  •     library
  •   tdetexteditor
  • kate
  • kded
  • kdoctools
  • kimgio
  • kjs
  • libtdemid
  • libtdescreensaver
  •     tdecore
  • tdeabc
  • tdecmshell
  • tdecore
  • tdefx
  • tdehtml
  • tdeinit
  • tdeio
  •   bookmarks
  •   httpfilter
  •   kpasswdserver
  •   kssl
  • tdeioslave
  •   http
  •   tdefile
  •   tdeio
  •   tdeioexec
  • tdemdi
  •   tdemdi
  • tdenewstuff
  • tdeparts
  • tdeprint
  • tderandr
  • tderesources
  • tdespell2
  • tdesu
  • tdeui
  • tdeunittest
  • tdeutils
  • tdewallet
Generated for tdeio/tdeio by doxygen 1.8.8
This website is maintained by Timothy Pearson.