Dialogs let you create custom windows with buttons, text boxes, checkboxes, radio buttons, lists, tabs and menus - to ask the user for input or build small interfaces inside a script. Full coverage of the official mIRC documentation, with a few simplifications explicitly noted below.
$dialog() (unlike
/dialog -m) is modal: it blocks script execution until the user closes the dialog, and
returns its result as a return value. Our scripting engine runs synchronously on a single JavaScript
thread (Yoake's engine, not a real mIRC interpreter) and can't suspend mid-line waiting for a user
click without freezing the whole interface - it's a platform limit, not something workable with more
effort. Here $dialog() still opens the dialog (with an overlay that dims the rest
of the app, to still give a "modal" feel), but the script continues right away - the field results must be
read in the on dialog:...:close event, or in the %variable linked to the control via the
result style, not from $dialog()'s return value (which here only returns the
name of the dialog just opened).Defined with the dialog prefix, in aliases.ini/remote.ini/popups.ini like an alias or an
on event:
dialog myTable {
title "Window title"
size -1 -1 300 200
option pixels
text "Name:", 1, 10 10 60 20
edit "", 2, 80 10 150 20
button "OK", 3, 10 170 60 20, ok default
button "Cancel", 4, 80 170 60 20, cancel
}
-1 -1 as x y centers the dialog. id is a number that uniquely identifies each
control (later used by /did/$did()/events). The -l prefix
(dialog -l name {...}, "local table") is accepted for syntax compatibility but ignored: here
aliases/events/popups/dialog tables all already live in a single shared space.
| Control | Syntax | Notes |
|---|---|---|
text | text "text", id, x y w h, style | Static label. Styles: left/right/center, nowrap. |
edit | edit "text", id, x y w h, style | Text box. Styles: left/right/center, multi (multi-line), pass (password), read (read-only), limit N (max length). |
button | button "text", id, x y w h, style | Styles: ok/cancel (closes the dialog on click), default (default button). |
check | check "text", id, x y w h, style | Checkbox. 3state style: three states (off/on/indeterminate) instead of two. |
radio | radio "text", id, x y w h, style | Radio button. group style: starts a new group (the following radios, up to the next group, are mutually exclusive among themselves). |
box | box "text", id, x y w h, style | Labeled box (group box). |
scroll | scroll "", id, x y w h, range N N, pos N, page N | Slider. Rendered as a horizontal <input type=range> (real mIRC's vertical orientation isn't reproduced). |
list | list id, x y w h, style | List. Styles: sort (sorts alphabetically on every change), multsel/extsel (multi-selection with Ctrl/Shift), check (checkbox per row), radio (radio per row). Populated via /did -a/-i/-o/-d, has no initial text. |
combo | combo id, x y w h, style | Dropdown menu. edit style: editable (with suggestions); without it, it's a fixed dropdown. Populated via /did like the list. |
icon | icon id, x y w h, path, index, style | Shows an image from the given path. index (for files with multiple icons, typical of Windows .exe/.dll) is not supported, ignored. noborder style removes the border. |
link | link "text", id, x y w h | Link-style text. On click it triggers the sclick event like any other control - it doesn't automatically open a URL, to stay entirely under the script's control. |
tab | tab "text", id, x y w h (first) / tab "text", id (following) | Creates a tab bar. A control is assigned to a tab with the tab <id> style (the id of ONE specific tab line) - that control is only visible when that tab is active. |
menu/item | menu "text", menuid [, parent-menuid] / item "text", id [, menuid] / item break, id [, menuid] | The dialog's menu bar. If the field after an item's id is ok/cancel instead of a number, that entry closes the dialog like the corresponding button (seen in the official example of the mIRC editor's File menu). |
| Style | Effect |
|---|---|
disable | Disables the control. |
hide | Hides it. |
group | Starts a new group (mainly for radio buttons). |
result | This control's value becomes the dialog's "result" ($dialog(name).result). |
If a control's text field is a %variable (e.g. edit "%name", 2, ...), that
%variable is set to the control's content when the dialog closes - with any button or with
/dialog -x.
/dialog -m <name> <table> ; opens (modeless) using the table
/dialog -m -d <name> <table> ; opens on the desktop
%result = $dialog(name,table) ; opens ("modal" style, see warning above)
name is the identifier used AFTERWARD to refer to this open instance (with /did,
$did(), in on dialog events) - it doesn't necessarily match the table's name.
| Switch | What it does |
|---|---|
-m <name> <table> | Opens a new dialog. |
-d | (with -m) opens "on the desktop" - equivalent here, no real distinction from other windows. |
-a | (with -m) uses the currently active window as parent - accepted, no visible effect here (we don't manage a real parent/child window hierarchy). |
-x <name> | Closes a dialog WITHOUT triggering the close event (linked %variables are still written). |
-t <name> <text> | Changes the title. |
-s <name> x y w h | Changes size/position (x y = -1 -1 to center). |
-r <name> | Centers the dialog. |
-o <name> / -n <name> | Sets/clears "always on top". |
-k <name> / -c <name> | Simulates a click on the ok/cancel button (if present) - closes the dialog, triggering the events normally. |
-v <name> | Brings the dialog to the front. |
-i <name> / -e <name> | Minimize / restore. |
-g <name> <newname> | Renames an already-open dialog. |
-h switch (ties the dialog to the active connection) and -b/-l/-p
(forces dbu/map/pixel on a single -s call) are accepted for syntax compatibility, with minimal or
no effect here: we don't manage multiple connections per dialog, and "map"/"pixels" already coincide in our
simplified model (see "Dbu and pixels" below).on 1:dialog:name:event:id: {
echo $dname $devent $did
}
name is the dialog's name (the one passed to /dialog -m or $dialog(), not
the table's name), id is the id of the control involved. Both accept * as a
wildcard; id also accepts lists/ranges like 1-3,5,7,9,15-20. Inside the block,
$dname/$devent/$did (with no parentheses) return name/event/id without
having to write them out again.
| Event | When it fires |
|---|---|
init | Right after the dialog is created, before it's visible - id is 0. |
close | When the dialog closes (not with /dialog -x, which specifically skips it) - id is 0. |
sclick | Click on a button, check/radio, list/combo row, tab entry. |
dclick | Double click on a list/combo row. |
edit | Text changed in a text box or an editable combo. |
scroll | Scroll/slider position changed. |
menu | Menu entry selected. |
mouse,
uclick, rclick, drop) - these would require tracking mouse
position/clicks across the whole dialog area independent of controls, a scope disproportionate to
the practical benefit in a chat client.ok/cancel button closes the dialog AFTER triggering
"sclick" - if that event's script runs halt, the automatic closing is blocked (same
behavior as real mIRC)./did -switch name id [n] [text|path]
With multiple comma/range-separated ids (e.g. 2,12-16,20) applies the switch to all of them at once.
| Switch | What it does |
|---|---|
-f | Gives focus to the control. On a tab: activates it (equivalent to clicking it). |
-t | Sets it as the default button. |
-e / -b | Enable / disable. |
-v / -h | Show / hide. On a tab: shows/hides the WHOLE tab bar (all tabs and their associated controls), whichever tab id is used to trigger it - per the official documentation. |
-n / -m | Enable / disable an editbox. |
-c | On check/radio: selects. On list/combo (with [n]): selects row N. On an editbox (with [n] start end): selects a character range. |
-u | Deselects check/radio/list row. -c and -u together on a 3state check set it to indeterminate. |
-k | (with -c on a list) keeps the other rows selected, instead of replacing them. |
-s / -l | Check / uncheck a row's checkbox (lists with check style). |
-r | Clears all text/rows. |
-a | On list/combo/editbox: appends a row at the end (or sets the text, on a single-line editbox). On a menu (when the given id doesn't match any control, but a menuid): /did -a name menuid newid text appends an entry at the end of that menu. |
-d | Deletes row N. |
-i | On list/combo/editbox: inserts text at row N. On a menu: /did -i name id newid text inserts a new entry right before the entry with that id (in the same menu that contains it). |
-o | Overwrites row N. |
-g | On an icon control: /did -g name id path changes the shown image. |
-z | On a scroll: /did -z name id min max changes the range. On a list: no effect here (in real mIRC it resizes the horizontal scrollbar). |
-j | Resets an editbox's "edited" state ($did().edited goes back to 0). |
Inside an on dialog event, name is optional: $did(id) already refers
to the current dialog. Without a property (e.g. $did(name,id)) it's equivalent to .text.
| Property | What it returns |
|---|---|
text | The control's text, or row N if given (default). |
len | Length of .text. |
lines | Number of rows (lists/combos/multi-line editboxes). |
sel | Number of the selected row (with N: 1/0 depending on whether row N is selected). |
seltext | Selected text (editbox) or first selected row (list). |
selstart / selend | Start/end of the text selection in an editbox. |
edited | 1/0 depending on whether the text was changed by the user. |
state | 0=off, 1=on, 2=indeterminate (check/radio). |
next / prev | Id of the next/previous control in the table's declaration order (approximates tab order). |
visible / enabled | 1/0. |
isid | 1/0 depending on whether that id exists in the dialog. |
csel | (lists with check style) number of checked rows, or the Nth checked row if N > 0. |
cstate | (lists with check style, with N) 1/0 depending on whether row N is checked. |
| Form | What it does |
|---|---|
$dialog(0) | Number of open dialogs. |
$dialog(N) | Name of the Nth open dialog. |
$dialog(name).property | x/y/w/h/cw/ch/title/modal/table/ok/cancel/result/focus/tab/mapw/maph/active/hwnd of the open dialog name. |
| Identifier/command | What it does |
|---|---|
$didtok(name,id,C) | A control's rows joined by the ascii separator C (like $gettok etc.). |
/didtok name id C text | Replaces a control's rows with text split on the ascii separator C. |
$didwm(name,id,wildtext,N) | Number of the first row (starting at N) matching a */? pattern. 0 if none. |
$didreg(name,id,regex,N) | Like $didwm but with a regular expression. |
$dbuw / $dbuh | dbu→pixel conversion factor (fixed, see below - in real mIRC it depends on the system font). |
With option dbu in the table, x/y/w/h coordinates are in Dialog Base Units instead of pixels -
here converted with a FIXED factor (1 dbu ≈ 1.5px horizontal, ≈ 1.8px vertical), not computed from the
system font like in real mIRC: a visual approximation, not a precise measurement. Without option dbu
("pixels", the default, or "map") coordinates are direct pixels, no conversion.
$dialog() (see the warning at the top of the page).mouse/uclick/rclick/drop).index on an icon control (multiple icons in a single .exe/.dll file)./dialog -m's -a switch and for $dialog(name,table,parent)'s parent parameter (read but not used).icon path, index before any control) is read but not shown - only the titlebar icon set via /window ... iconfile (for @windows) actually works.option disable (disables the whole dialog on creation) and option notheme: interpreted but with no effect.return/hsbar/vsbar/autohs/autovs/rich on edit, flat/multi on button, push on check/radio, size/vsbar/hsbar on list/combo (an automatic scrollbar is always used), top/left/bottom/right/small/large/actual on icon.-1 as a single dimension: only x y together as -1 -1 centers the dialog: w or h alone set to -1 have no real default value./did -a/-i (add/insert an entry) are the only supported operations - enabling/disabling/checking/deleting/overwriting a menu entry via /did aren't implemented (the official documentation lacks concrete syntax for them, unlike add and insert).