Item

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:

1 - read only
2 - hidden
4 - system
32 - archive
1024 - reparse point (junctions, etc.)
2048 - compressed
4096 - offline storage
8192 - not content-indexed
16384 - encrypted
524288 - pinned

Using the fileattr property, which returns a FileAttr object, may be easier than dealing with the raw attribute flags.

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

Vector:FiletypeGroup 

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>
<string:flags>

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:window>

object:File 

Opens this file and returns a File object that lets you access its contents as binary data.

By default the file will be opened in read mode - specify "w" for the optional mode parameter to open the file in write mode. Note that you cannot both read and write with the same File object.


When opening in write mode, you can also specify optional flags that control how the file is opened:

wc - create a new file, only if it doesn't already exist.
wa - create a new file, always. If the file already exists it will be overwritten. (This is the default.)
we - open existing file. The file will not be created if it doesn't already exist.
wo - open existing file. If the file doesn't exist it will be created.
wt - truncate existing file. If the file exists it will be truncated. The file will not be created if it doesn't already exist.
d - delete-on-close. The file will be automatically deleted when closed.

When using write mode, you may add f (force) to any of the above mode strings to tell Opus to clear the read-only file attribute if it blocks modifying an existing file; otherwise, attempting to open a read-only file for writing will fail. For example, "wof" is like "wo" mode but also clears the read-only attribute.

If you only want to make changes to the file's attributes without modifying its data you can also specify "m" to open it in modify mode.

The optional window parameter lets you associate the File object with a Tab or a Lister, which will be used if Opus needs to display any dialogs (e.g. a UAC elevation dialog). You may also specify the string "NoElevate" to prevent UAC elevation entirely, or "ElevateNoAsk" to prevent UAC prompts while still gaining elevation if something else has already performed it.

 

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>
<string:type>

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.