org.kde.koala
Class KFileItem

java.lang.Object
  extended by org.kde.koala.KFileItem
All Implemented Interfaces:
org.kde.qt.QtSupport

public class KFileItem
extends java.lang.Object
implements org.kde.qt.QtSupport

A KFileItem is a generic class to handle a file, local or remote. In particular, it makes it easier to handle the result of KIO.listDir (UDSEntry isn't very friendly to use). It includes many file attributes such as mimetype, icon, text, mode, link...


Field Summary
static int Access
           
static int Creation
           
static int Modification
           
static int NumFlags
           
static int Unknown
           
 
Constructor Summary
protected KFileItem(java.lang.Class dummy)
           
  KFileItem(KFileItem item)
          Copy constructor.
  KFileItem(KURL url, java.lang.String mimeType, long mode)
          Creates an item representing a file, for which the mimetype is already known.
  KFileItem(long _mode, long _permissions, KURL _url)
           
  KFileItem(long _mode, long _permissions, KURL _url, boolean _determineMimeTypeOnDemand)
          Creates an item representing a file, from all the necessary info for it.
 
Method Summary
 boolean acceptsDrops()
          Returns true if files can be dropped over this item.
 void assign(KFileItem item)
          Somewhat like an assignment operator, but more explicit.
 boolean cmp(KFileItem item)
          Somewhat like a comparison operator, but more explicit.
 void dispose()
          Delete the wrapped C++ instance ahead of finalize()
protected  void finalize()
          Deletes the wrapped C++ instance
 java.lang.String getStatusBarInfo()
          Returns the string to be displayed in the statusbar, e.g.
 java.lang.String getToolTipText()
           
 java.lang.String getToolTipText(int maxcount)
          Returns the string to be displayed in the tool tip when the mouse is over this item.
 java.lang.String group()
          Returns the group of the file.
 boolean hasExtendedACL()
          Tells if the file has extended access level information ( Posix ACL )
 java.lang.String iconName()
          Returns the full path name to the icon that represents this mime type.
protected  void init(boolean _determineMimeTypeOnDemand)
          Computes the text, mode, and mimetype from the UDSEntry Called by constructor, but can be called again later
 boolean isDir()
          Returns true if this item represents a directory.
 boolean isDisposed()
          Has the wrapped C++ instance been deleted?
 boolean isFile()
          Returns true if this item represents a file (and not a a directory)
 boolean isHidden()
          Checks whether the file is hidden.
 boolean isLink()
          Returns true if this item represents a link in the UNIX sense of a link.
 boolean isLocalFile()
          Returns true if the file is a local file.
 boolean isMarked()
          Used when updating a directory.
 boolean isMimeTypeKnown()
          Returns the currently known mimetype of the file item.
 boolean isReadable()
          Checks whether the file or directory is readable.
 boolean isWritable()
          Checks whether the file or directory is writable.
 java.lang.String linkDest()
          Returns the link destination if isLink() == true.
 java.lang.String localPath()
          Returns the local path if isLocalFile() == true or the KIO item has a UDS_LOCAL_PATH atom.
 void mark()
          Marks the item.
 KFileMetaInfo metaInfo()
           
 KFileMetaInfo metaInfo(boolean autoget)
           
 KFileMetaInfo metaInfo(boolean autoget, int what)
          Returns the metainfo of this item.
 java.lang.String mimeComment()
          Returns the descriptive comment for this mime type, or the mime type itself if none is present.
 java.lang.String mimetype()
          Returns the mimetype of the file item.
 long mode()
          Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
 KURL mostLocalURL(boolean local)
          Tries to give a local URL for this file item if possible.
 java.lang.String name()
           
 java.lang.String name(boolean lowerCase)
          Return the name of the file item (without a path).
 int overlays()
          Returns the overlays (bitfield of KIcon.Overlay flags) that are used for this item's pixmap.
protected  java.lang.String parsePermissions(long perm)
          Parses the given permission set and provides it for access()
 long permissions()
          Returns the permissions of the file (stat.st_mode containing only permissions).
 java.lang.String permissionsString()
          Returns the access permissions for the file as a string.
 org.kde.qt.QPixmap pixmap(int _size)
           
 org.kde.qt.QPixmap pixmap(int _size, int _state)
          Returns a pixmap representing the file.
protected  void readUDSEntry(boolean _urlIsDirectory)
          Extracts the data from the UDSEntry member and updates the KFileItem accordingly.
 void refresh()
          Throw away and re-read (for local files) all information about the file.
 void refreshMimeType()
          Re-reads mimetype information.
 void run()
          Let's "KRun" this file ! (e.g.
 void setFileMode(long m)
          Sets the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
 void setMetaInfo(KFileMetaInfo info)
          Sets the metainfo of this item to info.
 void setMimeType(java.lang.String mimetype)
          Sets new mimetype for item
 void setName(java.lang.String name)
          Sets the item's name (i.e.
 void setURL(KURL url)
          Sets the item's URL.
 long size()
          Returns the size of the file, if known.
 long size(boolean hasSize)
          Returns the size of the file, if known, and sets hasSize to false if not known
 java.lang.String text()
          Returns the text of the file item.
 int time(int which)
          Requests the modification, access or creation time, depending on which.
 int time(int which, boolean hasTime)
          Requests the modification, access or creation time, depending on which.
 java.lang.String timeString()
           
 java.lang.String timeString(int which)
          Requests the modification, access or creation time as a string, depending on which.
 void unmark()
          Unmarks the item.
 KURL url()
          Returns the url of the file.
 java.lang.String user()
          Returns the owner of the file.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

Unknown

public static final int Unknown
See Also:
Constant Field Values

Modification

public static final int Modification
See Also:
Constant Field Values

Access

public static final int Access
See Also:
Constant Field Values

Creation

public static final int Creation
See Also:
Constant Field Values

NumFlags

public static final int NumFlags
See Also:
Constant Field Values
Constructor Detail

KFileItem

protected KFileItem(java.lang.Class dummy)

KFileItem

public KFileItem(long _mode,
                 long _permissions,
                 KURL _url,
                 boolean _determineMimeTypeOnDemand)
Creates an item representing a file, from all the necessary info for it.

Parameters:
_mode - the file mode (according to stat() (e.g. S_IFDIR...) Set to KFileItem.Unknown if unknown. For local files, KFileItem will use stat().
_permissions - the access permissions If you set both the mode and the permissions, you save a .stat() for local files. Set to KFileItem.Unknown if you don't know the mode or the permission.
_url - the file url
_determineMimeTypeOnDemand - specify if the mimetype of the given URL should be determined immediately or on demand

KFileItem

public KFileItem(long _mode,
                 long _permissions,
                 KURL _url)

KFileItem

public KFileItem(KURL url,
                 java.lang.String mimeType,
                 long mode)
Creates an item representing a file, for which the mimetype is already known.

Parameters:
url - the file url
mimeType - the name of the file's mimetype
mode - the mode (S_IFDIR...)

KFileItem

public KFileItem(KFileItem item)
Copy constructor. Note that extra-data set via setExtraData() is not deeply copied -- just the pointers are copied.

Method Detail

refresh

public void refresh()
Throw away and re-read (for local files) all information about the file. This is called when the _file_ changes.


refreshMimeType

public void refreshMimeType()
Re-reads mimetype information. This is called when the mimetype database changes.


url

public KURL url()
Returns the url of the file.

Returns:
the url of the file

setURL

public void setURL(KURL url)
Sets the item's URL. Do not call unless you know what you are doing! (used for example when an item got renamed).

Parameters:
url - the item's URL

setName

public void setName(java.lang.String name)
Sets the item's name (i.e. the filename). This is automatically done by setURL, to set the name from the URL's fileName(). This method is provided for some special cases like relative paths as names (KFindPart)

Parameters:
name - the item's name

permissions

public long permissions()
Returns the permissions of the file (stat.st_mode containing only permissions).

Returns:
the permissions of the file

permissionsString

public java.lang.String permissionsString()
Returns the access permissions for the file as a string.

Returns:
the access persmission as string

hasExtendedACL

public boolean hasExtendedACL()
Tells if the file has extended access level information ( Posix ACL )

Returns:
true if the file has extend ACL information or false if it hasn't

mode

public long mode()
Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).

Returns:
the file type

user

public java.lang.String user()
Returns the owner of the file.

Returns:
the file's owner

group

public java.lang.String group()
Returns the group of the file.

Returns:
the file's group

isLink

public boolean isLink()
Returns true if this item represents a link in the UNIX sense of a link.

Returns:
true if the file is a link

isDir

public boolean isDir()
Returns true if this item represents a directory.

Returns:
true if the item is a directory

isFile

public boolean isFile()
Returns true if this item represents a file (and not a a directory)

Returns:
true if the item is a file

isReadable

public boolean isReadable()
Checks whether the file or directory is readable. In some cases (remote files), we may return true even though it can't be read.

Returns:
true if the file can be read - more precisely, false if we know for sure it can't

isWritable

public boolean isWritable()
Checks whether the file or directory is writable. In some cases (remote files), we may return true even though it can't be written to.

Returns:
true if the file or directory can be written to - more precisely, false if we know for sure it can't

isHidden

public boolean isHidden()
Checks whether the file is hidden.

Returns:
true if the file is hidden.

linkDest

public java.lang.String linkDest()
Returns the link destination if isLink() == true.

Returns:
the link destination. null if the item is not a link

localPath

public java.lang.String localPath()
Returns the local path if isLocalFile() == true or the KIO item has a UDS_LOCAL_PATH atom.

Returns:
the item local path, or null if not known

size

public long size()
Returns the size of the file, if known.

Returns:
the file size, or 0 if not known

size

public long size(boolean hasSize)
Returns the size of the file, if known, and sets hasSize to false if not known

Parameters:
@hasSize - This is set to true if the size is known, and false if not known
Returns:
the file size, or 0 if not known

time

public int time(int which)
Requests the modification, access or creation time, depending on which.

Parameters:
which - UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
Returns:
the time asked for, (time_t)0 if not available
See Also:
timeString(int)

time

public int time(int which,
                boolean hasTime)
Requests the modification, access or creation time, depending on which.

Parameters:
which - UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
hasTime - This is set to true is the time is known, and false if not known
Returns:
the time asked for, (time_t)0 if not known/available
See Also:
timeString(int)

timeString

public java.lang.String timeString(int which)
Requests the modification, access or creation time as a string, depending on which.

Parameters:
which - UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
Returns:
a formatted string of the requested time, null if time is not known
See Also:
time(int)

timeString

public java.lang.String timeString()

isLocalFile

public boolean isLocalFile()
Returns true if the file is a local file.

Returns:
true if the file is local, false otherwise

text

public java.lang.String text()
Returns the text of the file item. It's not exactly the filename since some decoding happens ('%2F'.'/').

Returns:
the text of the file item

name

public java.lang.String name(boolean lowerCase)
Return the name of the file item (without a path). Similar to text(), but unencoded, i.e. the original name.

Parameters:
lowerCase - if true, the name will be returned in lower case, which is useful to speed up sorting by name, case insensitively.
Returns:
the file's name

name

public java.lang.String name()

mimetype

public java.lang.String mimetype()
Returns the mimetype of the file item. If _determineMimeTypeOnDemand was used in the constructor, this will determine the mimetype first. Equivalent to determineMimeType().name()

Returns:
the mime type of the file

isMimeTypeKnown

public boolean isMimeTypeKnown()
Returns the currently known mimetype of the file item. This will not try to determine the mimetype if unknown.

Returns:
the known mime type

mimeComment

public java.lang.String mimeComment()
Returns the descriptive comment for this mime type, or the mime type itself if none is present.

Returns:
the mime type description, or the mime type itself

iconName

public java.lang.String iconName()
Returns the full path name to the icon that represents this mime type.

Returns:
iconName the name of the file's icon

pixmap

public org.kde.qt.QPixmap pixmap(int _size,
                                 int _state)
Returns a pixmap representing the file.

Parameters:
_size - Size for the pixmap in pixels. Zero will return the globally configured default size.
_state - The state of the icon: KIcon.DefaultState, KIcon.ActiveState or KIcon.DisabledState.
Returns:
the pixmap

pixmap

public org.kde.qt.QPixmap pixmap(int _size)

overlays

public int overlays()
Returns the overlays (bitfield of KIcon.Overlay flags) that are used for this item's pixmap. Overlays are used to show for example, whether a file can be modified.

Returns:
the overlays of the pixmap

getStatusBarInfo

public java.lang.String getStatusBarInfo()
Returns the string to be displayed in the statusbar, e.g. when the mouse is over this item

Returns:
the status bar information

getToolTipText

public java.lang.String getToolTipText(int maxcount)
Returns the string to be displayed in the tool tip when the mouse is over this item. This may load a plugin to determine additional information specific to the mimetype of the file.

Parameters:
maxcount - the maximum number of entries shown
Returns:
the tool tip string

getToolTipText

public java.lang.String getToolTipText()

acceptsDrops

public boolean acceptsDrops()
Returns true if files can be dropped over this item. Contrary to popular belief, not only dirs will return true :) Executables, .desktop files, will do so as well.

Returns:
true if you can drop files over the item

run

public void run()
Let's "KRun" this file ! (e.g. when file is clicked or double-clicked or return is pressed)


isMarked

public boolean isMarked()
Used when updating a directory. marked == seen when refreshing.

Returns:
true if the file item is marked

mark

public void mark()
Marks the item.

See Also:
isMarked()

unmark

public void unmark()
Unmarks the item.

See Also:
isMarked()

cmp

public boolean cmp(KFileItem item)
Somewhat like a comparison operator, but more explicit.

Parameters:
item - the item to compare
Returns:
true if all values are equal

setMetaInfo

public void setMetaInfo(KFileMetaInfo info)
Sets the metainfo of this item to info.

Parameters:
info - the new meta info

setFileMode

public void setFileMode(long m)
Sets the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).

Parameters:
m - the new file type

setMimeType

public void setMimeType(java.lang.String mimetype)
Sets new mimetype for item

Parameters:
mimetype - the new mimetype

metaInfo

public KFileMetaInfo metaInfo(boolean autoget,
                              int what)
Returns the metainfo of this item.

Parameters:
autoget - if true, the metainfo will automatically be created
what - ignored

metaInfo

public KFileMetaInfo metaInfo(boolean autoget)

metaInfo

public KFileMetaInfo metaInfo()

assign

public void assign(KFileItem item)
Somewhat like an assignment operator, but more explicit. Note: extra-data set with setExtraData() is not copied, so be careful what you do!

Parameters:
item - the item to copy

mostLocalURL

public KURL mostLocalURL(boolean local)
Tries to give a local URL for this file item if possible. The given booleanean indicates if the returned url is local or not.


init

protected void init(boolean _determineMimeTypeOnDemand)
Computes the text, mode, and mimetype from the UDSEntry Called by constructor, but can be called again later


readUDSEntry

protected void readUDSEntry(boolean _urlIsDirectory)
Extracts the data from the UDSEntry member and updates the KFileItem accordingly.


parsePermissions

protected java.lang.String parsePermissions(long perm)
Parses the given permission set and provides it for access()


finalize

protected void finalize()
                 throws java.lang.InternalError
Deletes the wrapped C++ instance

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.InternalError

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()


isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?