CommonDialog Reference

Reference for the CommonDialog object, which handles the "Open" and "Save As" dialogs (Win32 OPENFILENAME).

• Related: te Reference, api Reference

Notation: P = property (read/write), M = method. Member names are matched case-insensitively.

Table of Contents

1. How to Obtain
2. Methods
3. Properties
4. OFN_ENABLEHOOK (Folder Selection)
5. Notes
6. Constants
7. Examples

1. How to Obtain

const commdlg = api.CreateObject("CommonDialog");   // recommended
const commdlg2 = te.CommonDialog;                   // te.CommonDialog is also the same (a new object is created on every reference)

• At creation time, the owner window is set to the foreground window at that moment.
• The initial value of MaxFileSize is 260 (MAX_PATH).

2. Methods

Both of them, if the file name buffer has not been allocated yet before showing the dialog, allocate MaxFileSize characters and initialize it with an empty string.

3. Properties

• String properties (InitDir, DefExt, Title, Filter) are updated only when a string is passed (passing a number or anything else is ignored).
• If you pass a non-string argument to Filter, the current filter is discarded and becomes empty.

4. OFN_ENABLEHOOK (Folder Selection)

If you include OFN_ENABLEHOOK (0x20) in Flags for ShowOpen, TE's own behavior applies (it has no effect with ShowSave).

• Unlike ordinary file selection, when the dialog's "Open" button (OK) is pressed, the path of the folder currently displayed, or of the focused item, is stored in FileName. Folders and virtual folders (such as Control Panel) can also be selected.
• If an item is selected, that item (a folder or a file) is the result; if nothing is selected, the result is the displayed folder itself.
• The result is the parsing name of that path (SHGDN_FORPARSING | SHGDN_FORADDRESSBAR).
• When you call ShowOpen, the OFN_ENABLEHOOK bit is removed from Flags internally (if you read Flags after the call, this bit is not included). If you use it repeatedly, set it on Flags again each time.
• The return value is also true when the selection was made this way.

OpenDialogEx in sync.js sets this flag when bFilesOnly is false, so that both files and folders can be selected.

5. Notes

• Change MaxFileSize before setting FileName. The file name buffer is allocated the first time FileName is set, or the first time the dialog is shown. Increasing MaxFileSize after the allocation does not enlarge the buffer.
• The dialog is shown modally, and the call is blocked until it is closed.
• When TE's dark mode is enabled, the dark mode theme is applied to the controls in the dialog.
• If you call ShowOpen without setting FileName, the file name field starts out empty.

6. Constants

Defined in consts.js.

OFN_* (Flags) OFN_READONLY = 1 / OFN_OVERWRITEPROMPT = 2 / OFN_HIDEREADONLY = 4 / OFN_NOCHANGEDIR = 8 / OFN_SHOWHELP = 0x10 / OFN_ENABLEHOOK = 0x20 / OFN_ENABLETEMPLATE = 0x40 / OFN_ENABLETEMPLATEHANDLE = 0x80 / OFN_NOVALIDATE = 0x100 / OFN_ALLOWMULTISELECT = 0x200 / OFN_EXTENSIONDIFFERENT = 0x400 / OFN_PATHMUSTEXIST = 0x800 / OFN_FILEMUSTEXIST = 0x1000 / OFN_CREATEPROMPT = 0x2000 / OFN_SHAREAWARE = 0x4000 / OFN_NOREADONLYRETURN = 0x8000 / OFN_NOTESTFILECREATE = 0x10000 / OFN_NONETWORKBUTTON = 0x20000 / OFN_NOLONGNAMES = 0x40000 / OFN_EXPLORER = 0x80000 / OFN_NODEREFERENCELINKS = 0x100000 / OFN_LONGNAMES = 0x200000 / OFN_ENABLEINCLUDENOTIFY = 0x400000 / OFN_ENABLESIZING = 0x800000 / OFN_DONTADDTORECENT = 0x2000000 / OFN_FORCESHOWHIDDEN = 0x10000000

A commonly used combination: OFN_FILEMUSTEXIST | OFN_EXPLORER | OFN_ENABLESIZING | OFN_HIDEREADONLY | OFN_NODEREFERENCELINKS (the same as OpenDialogEx in sync.js)

7. Examples

// Open a file
const commdlg = api.CreateObject("CommonDialog");
commdlg.InitDir = "C:\\Users";
commdlg.Title = "Select an image";
commdlg.Filter = "Images|*.jpg;*.png;*.gif|All files|*.*";
commdlg.FilterIndex = 1;
commdlg.Flags = OFN_FILEMUSTEXIST | OFN_EXPLORER | OFN_ENABLESIZING | OFN_HIDEREADONLY | OFN_NODEREFERENCELINKS;
if (commdlg.ShowOpen()) {
    const path = commdlg.FileName;
}

// Save as (confirm before overwriting an existing file)
const save = api.CreateObject("CommonDialog");
save.FileName = "output.txt";
save.DefExt = "txt";
save.Filter = "Text|*.txt|All files|*.*";
save.Flags = OFN_OVERWRITEPROMPT | OFN_EXPLORER | OFN_ENABLESIZING | OFN_NOCHANGEDIR;
if (save.ShowSave()) {
    const dest = save.FileName;
}

// An "Open" dialog that can also select folders (OFN_ENABLEHOOK)
const dlg = api.CreateObject("CommonDialog");
dlg.InitDir = "C:\\";
dlg.Filter = "All files|*.*";
dlg.Flags = OFN_FILEMUSTEXIST | OFN_EXPLORER | OFN_ENABLESIZING | OFN_ENABLEHOOK;
if (dlg.ShowOpen()) {
    const folderOrFile = dlg.FileName;
}

// Enlarge the buffer first, to be ready for long paths
const big = api.CreateObject("CommonDialog");
big.MaxFileSize = 1024;     // before setting FileName
big.FileName = "";

sync.js has OpenDialogEx(path, filter, bFilesOnly) and MakeCommDlgFilter, which builds the filter string. In TE's standard scripts, calling the dialog through these is the common usage.

Related

• te Reference
• api Reference