TabCtrl Reference

Reference for the tab control (CTRL_TC) of Tablacus Explorer.

Notation: P = property (read with TC.Name, write with TC.Name = v), M = method (TC.Name(...)).

Table of Contents

  1. How to Obtain
  2. Basics and Getting Tabs
  3. Selecting and Operating on Tabs
  4. Position, Size, and Style
  5. Controlling Updates
  6. Constants
  7. Examples

1. How to Obtain

const TC = te.Ctrl(CTRL_TC);            // the current tab control
const arTC = te.Ctrls(CTRL_TC, true);   // all visible tab controls
const TC2 = FV.Parent;                  // the tab control a view belongs to
const TC3 = te.CreateCtrl(CTRL_TC, Left, Top, Width, Height);  // create a new one

For the arguments of te.CreateCtrl(CTRL_TC, ...), see the te Reference.

2. Basics and Getting Tabs

Name Kind Description
Type P (read-only) Always CTRL_TC
Data P A value the script can hold freely
hwnd P (read-only) The window handle of the tab control
Id P (read-only) The identification number of the tab control (corresponds to the id of te.Ctrl(CTRL_TC, id))
Count / length P (read-only) The number of tabs
Item(index) M Returns the view (FolderView) of the tab at index (0-based). Empty if out of range or not yet created
_NewEnum P For enumeration (all tabs can be enumerated with for...in / Enumerator)
TC[i] - A tab can also be obtained with a numeric index (the same as Item(i)) 
for (let i = 0; i < TC.length; ++i) {
    const FV = TC[i];
}
for (let i = 0; i < TC.Count; ++i) {
    const FV = TC.Item(i);
}
for (const FV in TC) { /* ... */ }

3. Selecting and Operating on Tabs

Name Kind Description
Selected P Returns the view (FolderView) of the selected tab. If you assign a view, the tab position number of that view is selected in this tab control (note that even if you pass a view of a different tab control, that view's position number is used as it is). If it has not been created yet, a new view is created and returned
SelectedIndex P The position number (0-based) of the selected tab. Assigning to it switches the selection
Move(src, dest [, TC2]) M Moves a tab. Move(view, dest): moves the tab of the view you pass to position dest of this tab control (a view of a different tab control also works). Move(src, dest [, TC2]): moves the tab at position src of this tab control to position dest of TC2 (if TC2 is omitted, it moves within this tab control)
SetOrder(arr) M Rearranges the tabs according to an array. For arr[i], specify the original position number to place at position i in the new order. If the length does not match the number of tabs, nothing is done. The selected position keeps pointing at the same tab after the rearrangement
HitTest(pt [, flags]) M Finds the tab under the screen coordinates pt. flags is TCHT_* (TCHT_ONITEM if omitted). If flags is omitted, the view (FolderView) is returned; if it is specified, the position number (a negative value if there is none) is returned
Close() M Closes the tab control itself. All the views it contains are closed and the window is destroyed. It does nothing during navigation or when it cannot be closed (for example when there is a locked tab; the exact conditions need verification). To close only some of the tabs, use each FV.Close()
Visible P Show / hide. Assigning toggles it (true sets it as the current tab control). When hidden, the window is hidden

If the view at the currently selected position has not been created yet, Selected creates a new view and returns it. Be careful of this side effect.

4. Position, Size, and Style

Name Kind Description
Left / Top / Width / Height P The position and size of the tab control (the whole view area). Numbers are in pixels, and strings such as "50%" are ratios. On reading, a ratio specification is returned as a string in the "50%" form, and a pixel specification as a number. Ratios are capped at 100% and held in units of 0.01%
Style P The Win32 style of the tabs (TCS_*). If TCS_SCROLLOPPOSITE / TCS_BUTTONS / TCS_TOOLTIPS changes, the tab control is recreated
Align P The tab placement. 0 = none (tabs hidden), 2 = top, 3 = bottom, 4 = left, 5 = right. The meaning of 1 needs verification (when te.Tab is false, it is always treated as "none")
TabWidth P The width of the tabs (px). For left/right placement (Align 4/5), it is also used as the width of the tab area
TabHeight P The height of the tabs (px) 
TC.Left = "0%";
TC.Width = "50%";     // half of the screen
TC.Align = 2;         // tabs on top
TC.TabHeight = 28;

5. Controlling Updates

Name Kind Description
LockUpdate() M Temporarily suspends the re-layout of this tab control (counter based)
UnlockUpdate() M Releases LockUpdate. When the counter returns to 0, the layout is updated

When opening or closing a large number of tabs, wrapping the work in LockUpdate and UnlockUpdate lets the screen update only once (use te.LockUpdate to control the whole main window).

TC.LockUpdate();
try {
    for (const path in paths) {
        TC.Selected.Navigate(path, SBSP_NEWBROWSER);
    }
} finally {
    TC.UnlockUpdate();
}

6. Constants

Defined in consts.js.

TCHT_* (flags of HitTest) TCHT_NOWHERE = 1 / TCHT_ONITEMICON = 2 / TCHT_ONITEMLABEL = 4 / TCHT_ONITEM = 6

TCS_* (Style) TCS_TABS = 0 / TCS_BUTTONS = 0x100 / TCS_SINGLELINE = 0 / TCS_MULTILINE = 0x200 / TCS_RIGHTJUSTIFY = 0 / TCS_FIXEDWIDTH = 0x400 / TCS_RAGGEDRIGHT = 0x800 / TCS_FOCUSONBUTTONDOWN = 0x1000 / TCS_OWNERDRAWFIXED = 0x2000 / TCS_TOOLTIPS = 0x4000 / TCS_FOCUSNEVER = 0x8000 / TCS_SCROLLOPPOSITE = 1 / TCS_BOTTOM = 2 / TCS_RIGHT = 2 / TCS_MULTISELECT = 4 / TCS_FLATBUTTONS = 8 / TCS_FORCEICONLEFT = 0x10 / TCS_FORCELABELLEFT = 0x20 / TCS_HOTTRACK = 0x40 / TCS_VERTICAL = 0x80

CTRL_TC CTRL_TC = 0x30000 (the value returned by Type)

7. Examples

const TC = te.Ctrl(CTRL_TC);

// List the paths of all tabs
for (let i = 0; i < TC.length; ++i) {
    const FV = TC[i];
    const path = FV.FolderItem.Path;
}
// List the paths of all tabs (alternative)
for (let i = 0; i < TC.Count; ++i) {
    const FV = TC.Item(i);
    const path = FV.FolderItem.Path;
}

// Open in a new tab
const FV = TC.Selected.Navigate("C:\\Windows", SBSP_NEWBROWSER);

// Switch and move tabs
TC.SelectedIndex = 0;
TC.Move(TC.Selected, 0);          // move the selected tab to the front

// Reverse the order
const order = [];
for (let i = TC.Count; i--;) {
    order.push(i);
}
TC.SetOrder(order);

// Get the tab under the mouse position (a view is returned when flags is omitted)
const pt = api.Memory("POINT");
api.GetCursorPos(pt);
const target = TC.HitTest(pt);
if (target) {
    target.Close();
}