The Item object represents a file or folder displayed in a tab. You can obtain a collection of Item objects from the various methods of the Tab object. A collection of Item objects is also used with the Command object to specify the files or folders a command should operate on. Using the FSUtil.ReadDir method to enumerate the contents of a folder also returns an Item object. You can create an Item from a file path using the FSUtil.GetItem method.
Property Name |
Return Type |
Description |
---|---|---|
<default value> |
string |
Returns the full pathname of the item (i.e. path plus filename). |
access |
date |
Returns the "last accessed" date, in local time. |
access_utc |
date |
Returns the "last accessed" date, in UTC. |
attr |
int |
Returns the item attributes. This value is a series of flags that are
logically OR'd together. The attributes supported by Opus are: |
attr_text |
string |
Returns the item attributes as a string, as displayed in the file display. |
checked |
bool |
Returns True if the item was checked (in checkbox mode), or False otherwise. |
create |
date |
Returns the "creation" date, in local time. |
create_utc |
date |
Returns the "creation" date, in UTC. |
current |
bool |
For Item objects obtained from a Viewer, this property is True if the item represents the currently displayed image and False otherwise. For Item objects obtained from a file display, the property indicates whether or not the item is the one with focus. The focus property is the more proper way to check this, but both work in case you forget which is which. |
display_name |
string |
Returns the display name of the item. Only a few items have a display name that is different to their actual name - some examples are certain system folders (like C:\Users which might have a translated display name in non-English locales). |
ext |
string |
Returns the filename extension. |
ext_m |
string |
Returns the filename extension, taking multi-part extensions into account. For example, a file called "file.part1.rar" might return ".rar" for ext but ".part1.rar" for ext_m. |
failed |
bool |
Returns True if the item failed when used by a command. This is only meaningful in conjunction with the Command.files collection - once the command has returned, this property will indicate success or failure on a per-file basis. |
fileattr |
object:FileAttr |
Returns a FileAttr object that represents the item's attributes. |
filegroup |
object:FileGroup |
If the file display this item came from is grouped by a particular column, this property returns a FileGroup object representing the group the item is in. If the item has no group this will return an empty string. |
focus |
bool |
For Item objects obtained from a file display, this property is True if the object represents the item with focus, and False otherwise. Only one item can have focus at a time. The item with focus is typically shown with an outline around it, and is usually the last item which was clicked on, or which was moved to with the keyboard. The item with focus is often also one of the selected items, but not always; selection and focus are two separate things. For Item objects obtained from a Viewer, the property indicates if the file is the one currently shown in the viewer. The current property is the more proper way to test this, but focus also works. |
got_size |
bool |
Returns True for folder items if their size has been calculated by, for example, the GetSizes command. If False, the size property will be unreliable for folders. |
groups |
Returns a Vector of FiletypeGroup objects representing any and all file type groups that this file is a member of. If you only want to check membership of a particular file type group, see the InGroup method in the section below. | |
groupsobject |
object:FiletypeGroups |
Similar to the groups property, except a FiletypeGroups object is returned instead of a Vector. |
id |
int |
This is a unique ID for the item; it is used internally by Opus. |
is_dir |
bool |
Returns True if the item represents a folder, and False for a file. |
is_junction |
bool |
Returns True if the item is a junction to another folder. |
is_reparse |
bool |
Returns True if the item is a reparse point. |
is_symlink |
bool |
Returns True if the item is a symbolic link. |
metadata |
object:Metadata |
Returns a Metadata object that provides access to the item's metadata. |
modify |
date |
Returns the "last modified" date, in local time. |
modify_utc |
date |
Returns the "last modified" date, in UTC. |
name |
string |
Returns the name of the item. |
name_stem |
string |
Returns the filename "stem" of the item. This is the name of the item with the filename extension removed. It will be the same as the name for folders. |
name_stem_m |
string |
Returns the filename "stem" of the item, taking multi-part extensions into account. For example, a file called "file.part1.rar" might return "file.part1" for name_stem but "file" for name_stem_m. |
path |
object:Path |
Returns the path of the item's parent folder. This does not include the name of the item itself, which can be obtained via the name property. |
realpath |
object:Path |
Returns the "real" path of the item. For items located in virtual folders like Libraries or Collections, this lets you access the item's underlying path in the real file system. The realpath property includes the full path to the item, including its own name. |
selected |
bool |
Returns True if the item was selected, or False otherwise. |
shortpath |
object:Path |
Returns the short path of the item, if it has one. Note that short paths are disabled by default in Windows 10. |
size |
object:FileSize |
Returns the size of the item as a FileSize object. |
Method Name |
Arguments |
Return Type |
Description |
---|---|---|---|
InGroup |
<string:group> |
bool |
Tests the file for membership of the specified file type group. Each file type group has two names: An internal name which is always the same in all languages, and a display name which may be translated differently for each language. The display name is what you see in the File Types editor. Groups that come pre-defined when you install Opus have internal names like "Archives" and "Music" (which are also their English display names). User-defined groups have internal names which are unique, automatically generated GUID strings like "{C4B716ED-2A9C-43C6-B325-7DADDEEFADA9}". The group argument should be the name of the group you wish to test against, e.g. "Music". By default, both the internal name and the display name are checked, and a match on either will return true. Prefix the group argument with "name:" to restrict the search to internal names, or with "disp:" to restrict the search to display names. To get a list of all file type groups which the file matches, use the groups property instead (see the section above). |
Labels |
<string:category> |
Vector:string |
This method returns a Vector of strings representing any labels that have been assigned to the item. Both arguments are optional. The first is a wildcard pattern that lets you filter the returned labels based on their category. For example, pass "Status" to only retrieve a list of status icons assigned to a file. The second optional argument contains flags keywords that control how the labels are returned. The only defined flag is "explicit" - if specified, wildcard and label filters will not be considered - only explicitly assigned labels will be returned. Note that if you want to provide the second argument but don't want to filter by category you should pass "*" for the first argument to match all categories. |
Open |
<string:mode> |
object:File |
Opens this file and returns a File object
that lets you access its contents as binary data. When opening in write mode, you can also specify optional flags that
control how the file is opened:
A File object is always returned, even if the file could not be opened. Check File.error on the returned object immediately after creating it to see if opening the file succeeded. Even if the file was not be opened, some of the object's methods may still work. For example, if a file doesn't exist then you can't open it or set its attributes, but permissions on an existing file may allow you to set its attributes while blocking you from modifying it or vice versa. |
ShellProp |
<string:property> |
variant |
Returns the value of the specified shell property for the item. The property argument can be the property's PKEY or its name.
If you provide a name then the optional second argument lets you
control how the properties are looked up by name. If the value of
type is "R" then the first property whose raw name matches the
supplied name will be used. If the value is "D" then the first property
whose display name matches the supplied name will be used. If
type is omitted then both raw and display names can
match. Note that if a shell property is returned by the system as a SAFEARRAY type, it will be converted automatically to a Vector object. |
Update |
none |
none |
Updates the Item object from the file on disk. You might use this if you had run a command to change an item's timestamp or attributes, and wanted to retrieve the new information. |