~~Title: Tab ~~ The **Tab** object represents a folder tab in a Lister (even if the tab control isn't currently displayed, a Lister always has at least one open tab). You can obtain a collection of **Tab** objects from a **[[lister|Lister]]** object. **Tab** objects are also used with the **[[command|Command]]** and **[[func|Func]]** objects, and if a command results in new tabs being opened, the **[[results|Results]]** object. $$ Property Name $$ Return Type $$ Description $$ all $$ //object://**[[items|Items]]**  $$ Returns an **[[items|Items]]** object that represents all the files and folders currently displayed in this tab. Note: The first time a script accesses this property (and all the other properties that return an **[[items|Items]]** object), a snapshot is taken of all the appropriate items. If the script then makes changes to those items (e.g. by creating a new file, modifying the selection, etc), these changes will not be reflected by the collection. To re-synchronize the collection call the **Update** method on the object. $$ backlist $$ //collection://**[[path|Path]]**  $$ Returns a collection of **[[path|Path]]** objects that represents the paths in the "backward" history list for this tab (i.e. the folders you would get to by clicking the //Back// button). $$ color $$ //string// $$ Returns the tab's assigned color (if one has been assigned via, for example, the **Go TABCOLOR** command). The color is returned as a string in R,G,B format. $$ crumbpath $$ //object://**[[path|Path]]**  $$ Returns the current path from the tab's breadcrumb control (if it has one), including any ghost path. $$ dest $$ //bool// $$ Returns **True** if this tab is currently the [[:basic_concepts:source_and_destination|destination]], and **False** otherwise. Note that you cannot always assume a tab is the source if it is not the destination. Use the separate **source** property for that. $$ dirs $$ //object://**[[items|Items]]**  $$ Returns an **[[items|Items]]** object that represents all the folders currently displayed in this tab. $$ dirty $$ //bool// $$ Returns **True** if the tab is marked as dirty, indicating its list of contents may be out of date. This can happen if the tab is in the background and the user has turned off the **Preferences / Folder Tabs / Options / Process file changes in background tabs** option. $$ displayed_label $$ //string// $$ Returns the currently displayed label of this tab. $$ filegroups $$ //collection://**[[filegroup|FileGroup]]**  $$ Returns a collection of **[[filegroup|FileGroup]]** objects that represents all the file groups in the tab (when the tab is grouped). You can use the **format.group_by** property to test if the tab is grouped or not. $$ files $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the files currently displayed in this tab. $$ format $$ //object://**[[format|Format]]**  $$ Returns a **[[format|Format]]** object representing the current folder format in this tab. $$ forwardlist $$ //collection://**[[path|Path]]** $$ Returns a collection of **[[path|Path]]** objects that represents the paths in the "forward" history list for this tab (i.e. the folders you would get to by clicking the //Forward// button). $$ hidden $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the files and folders currently hidden from this tab. $$ hidden_dirs $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the folders currently hidden from this tab. $$ hidden_files $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the files currently hidden from this tab $$ highlighted $$ //object://**[[items|Items]]**  $$ Returns an **[[items|Items]]** object that represents all the files and folders currently displayed in this tab that have one or more cells [[:basic_concepts:selecting_files:selecting_cells|highlighted]]. $$ label $$ //string// $$ Returns the current assigned tab label. Note that this may be an empty string if no custom label has been assigned. The **displayed_label** property returns the currently displayed label in all cases. $$ linktab $$ //object://**Tab**  $$ If this tab is linked to another tab, returns a **Tab** object representing the linked tab. If this tab is not linked this property returns **0**. $$ lister $$ //object://**[[lister|Lister]]**  $$ Returns a **[[lister|Lister]]** object representing the parent Lister that owns this tab. $$ lock $$ //string// $$ Returns the current lock state of the tab; one of "off", "on", "changes", "reuse". $$ navlock $$ //bool// $$ Returns **True** if this tab is linked in Navigation Lock mode. This property does not exist if the tab is not linked, so make sure you check the value of **linktab** first. $$ path $$ //object://**[[path|Path]]**  $$ Returns the current path shown in this tab. $$ quickfilter $$ //object://**[[quickfilter|QuickFilter]]**  $$ Returns a **[[quickfilter|QuickFilter]]** object providing information about the state of the quick filter in this tab. $$ right $$ //bool// $$ Returns **True** if this tab is currently on the right or bottom side of a dual-display Lister, and **False** otherwise. $$ selected $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the selected files and folders currently displayed in this tab. Note that if [[:basic_concepts:selecting_files:selecting_with_the_mouse_and_keyboard:checkbox_mode|checkbox mode]] is turned on in the tab, this will be a collection of checked items rather than selected. $$ selected_dirs $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** object that represents all the selected folders currently displayed in this tab. $$ selected_files $$ //object://**[[items|Items]]** $$ Returns an **[[items|Items]]** objects that represents all the selected files currently displayed in this tab $$ selstats $$ //object://**[[tabstats|TabStats]]**  $$ Returns a **[[tabstats|TabStats]]** object that provides various information about the tab, including the number of files, number of selected files, total size of selected files, etc. The "selected" counts provided by this object take [[:basic_concepts:selecting_files:selecting_with_the_mouse_and_keyboard:checkbox_mode|checkbox mode]] into account (that is, if checkbox mode is currently turned on, the counts will be for checked files rather than for selected files). $$ source $$ //bool// $$ Returns **True** if this tab is currently the [[:basic_concepts:source_and_destination|source]], and **False** otherwise. Note that you cannot always assume a tab is the destination if it is not the source. Use the separate **dest** property for that. $$ stats $$ //object://**[[tabstats|TabStats]]** $$ Returns a **[[tabstats|TabStats]]** object that provides various information about the tab, including the number of files, number of selected files, total size of selected files, etc. Unlike **selstats**, this object does not take [[:basic_concepts:selecting_files:selecting_with_the_mouse_and_keyboard:checkbox_mode|checkbox mode]] into account (so the "selected" counts will refer to selected rather than checked files). $$ vars $$ //object://**[[vars|Vars]]**  $$ This **[[vars|Vars]]** object represents all defined variables with //tab scope// (that are scoped to this tab). $$ visible $$ //bool// $$ Returns **True** if this tab is currently visible (i.e. it is the active tab in either file display), and **False** otherwise. $$ Method Name $$ **Arguments** $$ Return Type $$ Description $$ CloseFAYT $$ //none// $$ //none// $$ Call this method from a [[:scripting:example_scripts:extending_the_fayt|FAYT extension]] script to forcibly close the FAYT field. $$ Dlg $$ //none// $$ //object://**[[dialog|Dialog]]** $$ Creates a new **[[dialog|Dialog]]** object, that lets you display dialogs and popup menus. The dialog's **window** property will be automatically assigned to this tab. $$ GetFocusItem $$ //none// $$ //object://**[[item|Item]]**  $$ Returns an **[[item|Item]]** object representing the file or folder which has focus in the tab. The focus item is typically indicated by an outline around its name, and is usually the last item which was clicked on, or the last item which was moved to with the keyboard. The focus item is often also selected, but not always; focus and selection are two different things. If no focus item exists, or if the focus item is a special file or folder, such as //This PC//, which cannot be represented by an **Item** object, then this method does not return an object. (In JScript, test if the result //**== null**// and in VBScript test if the result //**is nothing**//.) $$ Notify $$ \\ \\ [] $$ //bool// $$ Displays a notification message associated with this tab. Currently the only defined type is "status", which displays the message in the status bar. The //msg// string will be displayed in the status bar when the tab is active. The //timeout// value lets you specify an optional timeout (in milliseconds) after which the message will automatically be removed. If no timeout is specified the user needs to click the message to dismiss it. $$ Update $$ //none// $$ //none// $$ When a script accesses particular properties of a **Tab** object, a snapshot is taken of the tab's state. For example, if you ask for the **selected_files** property, the list of selected files is calculated and then stored in memory. This can speed things up, and also means you don't have to worry about the list changing under you as you work through it. If the script then makes changes to the tab (e.g. it selects files, creates a new folder, etc.), these changes will not be reflected by the cached snapshot(s) if you access the same properties on the same tab object again. To clear the cached snapshots and re-synchronize the object with the tab's current state, call the **Tab.Update** method. $$ UpdateFAYTSuggestions $$ //array//\\ or //**[[vector]]**:string// or //object://**[[map]]** $$ //none// $$ When you're implementing a [[:scripting:example_scripts:extending_the_fayt|FAYT extension]] script, you can call this method at any time to update the list of suggestions shown to the user. You can provide an array or **[[vector]]** of strings, or a **[[map]]** of string/string pairs. When providing a **[[map]]** each key represents the text that will be inserted if selected by the user, and the value represents a hint or description that's shown in a separate column in the suggestion list. When providing an array or **[[vector]]** of strings, you can provide the second column description by tab-separating it from the main value.