Dialogs

mIRC allows you to create custom Dialogs which can be used to request input from a user, or to perform many other useful tasks.

There are two types of dialog; a modeless dialog, created with the /dialog command, and a modal dialog, created with the $dialog() identifier. Both are described below.

The /dialog command

The /dialog command allows you to create a modeless dialog with the -m switch. This type of dialog doesn't halt or return a value to the calling script, and the dialog can be displayed indefinitely and used for many purposes.

/dialog -mdtsonkcvie name [table] [x y w h] [text]

-m

create a modeless dialog using 'table'

/dialog -m name table

-a

used with -m, uses currently active window as the parent

-x

close a dialog without triggering any events

-d

open dialog on the desktop, used with -m

-h

make dialog work with active server connection

-t

set dialog title

/dialog -t name text

-s

set dialog size/pos

/dialog -s name x y w h

-r

centers dialog

-bp

interprets size as dbu or pixels

-o

set dialog ontop of all windows

-n

unset ontop setting

-k

click ok button

-c

click cancel button

-v

makes the dialog the active window

-ie

minimize/restore the dialog if created on the desktop

Where name is the name by which you'll refer to the dialog, and table is the dialog table name used to create dialog (see below).

The $dialog() identifier

Dialogs created with $dialog() are modal, ie. they halt the script until the dialog is closed, they return a value, and they don't allow access to other windows while the dialog is open. These types of dialogs should only be displayed for immediate user input. The $dialog() identifier works the same way as other identifiers:

%result = $dialog(name,table[,parent])

Where name is the name by which you'll refer to the dialog, table is the dialog table name used to create dialog (see below), and parent is the parent window of the dialog, this can be a window name, or -1 = Desktop window, -2 = Main mIRC window, -3 = Currently active window, -4 = Currently active dialog, if no dialog is open, defaults to -3 behaviour.

Note: This type of dialog cannot be called from a remote script event.

You can also use the $dialog(name/N) identifier to list any open dialogs, where N returns the Nth open dialog. If N is zero, the total number of open dialogs is returned.

$dialog() also supports these properties:

x,y,w,h

returns the size and position of the dialog

cw,ch

returns width and height of client area of dialog

title

returns the title of the dialog

modal

returns $true if the dialog is modal, otherwise $false

table

returns the dialog table that the dialog is using

ok

returns the id of the Ok button if you specified one

cancel

returns the id of the Cancel button if you specified one

result

returns the id of the Result button if you specified one

focus

returns id of control that currently has focus

tab

returns id of tab that is currently displayed

active

returns $true if dialog is the active window, otherwise $false

hwnd

returns dialog window handle

The dialog table

You can use the dialog prefix to create a dialog table called name in a script using this format:

dialog [-l] name {

title

"text"

icon

filename, index

size

x y w h

option

type (dbu, pixels, notheme)

text

"text", id, x y w h, style (right, center, nowrap)

edit

"text", id, x y w h, style (right, center, multi, pass, read, return, hsbar, vsbar, autohs, autovs, limit N)

button

"text", id, x y w h, style (default, ok, cancel, flat, multi)

check

"text", id, x y w h, style (left, push, 3state)

radio

"text", id, x y w h, style (left, push)

box

"text", id, x y w h, style

scroll

"text", id, x y w h, style (top left bottom right horizontal range N N)

list

id, x y w h, style (sort, extsel, multsel, size, vsbar, hsbar, check)

combo

id, x y w h, style (sort, edit, drop, size, vsbar, hsbar)

icon

id, x y w h, filename, index, style (noborder top left bottom right)

link

"text", id, x y w h

tab

"text", id, x y w h

tab

"text", id

menu

"text", menuid [, menuid]

item

"text", id [, menuid]

item

break, id [, menuid]

}

The -l switch makes a dialog table local, so that it can only be accessed by other scripts in the same file.

Where "text" is the default text for a control, id is a number that uniquely identifies a control, x y w h are the position and size of the control, and style consists of a combination of the words in brackets.

Other Styles

In addition to the styles shown in brackets for each type of control, you can also specify these styles:

disable

disables the control

hide

hides the control

group

start of a group

result

identifies the control whose value will be used as the return value to the calling script when the user presses the ok button

Variables

If you specify a %variable name in a dialog item definition, the %variable will be set with the contents of that item when the dialog is closed.

edit "", 2, 10 10 100 20, autohs %result

Tab control

The first tab definition specifies the size of the tab control, and any following tab definitions add tabs to it. You can associate controls with a specific tab by using the tab style followed by the id value for a tab, as shown in the example below.

dialog test {

title "mIRC"

size -1 -1 110 100

option dbu

tab "m", 1, 5 5 100 90

tab "I", 2

tab "R", 3

tab "C", 4

button "m is for ... ;)", 11, 30 50 50 24, ok tab 1

button "I is for Internet", 12, 30 50 50 24, tab 2

button "R is for Relay", 13, 30 50 50 24, tab 3

button "C is for Chat", 14, 30 50 50 24, tab 4

}

You can use /did -fu to set the focus on a specific tab, and /did -vh to show/hide the entire tab control.

Menus

You can add menus and submenus to custom dialogs using the menu and item prefixes:

dialog name {

menu "text", <menuid> [, menuid]

item "text", <id> [, menuid]

item break, <id> [, menuid]

}

If you don't specify a menuid for an item, it will use the last menuid that was created/used in a previous menu/item.

For example, the following menu definition reproduces the File menu of the mIRC Editor dialog:

dialog test {

title "mIRC"

size -1 -1 110 100

option dbu

menu "&File", 60

item "&New", 70

menu "&Load", 80, 60

item "&Script", 90

item break, 100

item "&Users", 110

item "&Variables", 120

item "&Unload", 130, 60

item break, 140

item "&Save", 150

item "&Save As...", 160

item "Save &All", 170

item break, 180

item "Save && &exit", 190, ok

item "&Cancel", 200, cancel

}

You can use the /did command (described below) to enable/disable, check/uncheck, append, delete, insert, and overwrite a menu item.

To add an item to a menu you can use: /did -a name <menuid> <newid> <text>.

To insert an item you must use: /did -i name <id> <newid> <text> where <id> is the item before which you want to insert an item.

Dbu vs. Pixels

The dbu option makes mIRC use dialog base units when creating the dialog, this ensures that the dialog will look the same for all users under any size display, etc. Pixels is the default however to maintain compatibility with previous scripts.

The identifiers $dbuw and $dbuh return the dbu per pixel width and height values for the current display. This may or may not be an integer value.

Ok and Cancel buttons

You can specify an ok and/or cancel button, and when a user clicks the ok or cancel buttons, the dialog is closed. You can prevent the dialog from closing if a user clicks the ok button by using /halt.

Default position and size

If you specify -1 for any of the x y w h values in the size setting for the dialog, a default setting is used. To make mIRC center the dialog in a window, specify x y as -1 -1. The size setting can be over-ridden in the init event (see below) by using /dialog -s name x y w h.

The On Dialog event

If a user changes the state of controls in the dialog, eg. clicks on a button, types text in an edit box, etc., this triggers the on dialog script event which allows you to monitor input from the user:

on 1:dialog:name:event:id: {

echo $dname $devent $did

}

Where name identifies the dialog, id is the id number of the control triggering the event, and event can be:

init

just before a dialog is displayed, controls can be initialized in this event. id is zero.

close

when a dialog is closed.

edit

text in editbox or combo box changed.

sclick

single click in list/combo box, or check/uncheck of radio/check buttons, or click of a button.

dclick

double click in list/combo box.

menu

a menu item was selected.

scroll

scroll control position has changed.

You can also detect mouse events that aren't associated with a specific control:

mouse

mouse moved

sclick

left button down

uclick

left button up

dclick

double click

rclick

right button click

drop

drop click

You can use $mouse to retrieve the current mouse position.

The /did command

The /did command allows you to modify the values of controls in a dialog, eg. changing the text in an edit control, or setting focus to a button, or deleting lines in a listbox.

/did -ftebvhnmcukradiogjsl name id [n] [text | filename]

-f

set focus on id

-t

set id as default button

-e

enable id

-b

disable id

-v

make id visible

-h

hide id

-n

enables editbox

-m

disables editbox

-c

check checkbox/radiobutton list/combo line

-u

uncheck checkbox/radiobutton list/combo line

-k

works with -cu, keeps other selections in a listbox

-s

checks the checkbox of an item in a listcb control

-l

unchecks the checkbox of an item in a listcb control

-r

clear all text in id

-a

add line of text to end

-d

delete Nth line

-i

insert text at Nth line

-o

overwrite Nth line with text

-g

set a new icon/bmp to an icon control

/did -g name id [n] filename

-z

resets the width of horizontal scrollbar in listbox

-j

resets the edited setting in an editbox

Where name identifies the dialog and id is the id number of the control you want to modify.

If you want to modify several controls at the same time, you can specify multiple id numbers separated by commas, eg. /did -b name 2,12-16,20 etc.

You can select a range of text in an editbox using /did -c name id [n] [start [end]]. This selects line N in editbox, and sets selection to specified range of characters.

You can mark a 3state checkbox as indeterminate by specifying both -cu switches.

You can access the edit control in a combobox by using 0 as the N value.

To change the range of a scrollbar control, you can use /did -z name id [min max].

$did(name,id)

You can get the settings and values of controls in a dialog by using the $did() dialog id identifier with the following formats and properties as appropriate to the control to which you are referring.

$did(name,id)

$did(name,id,N)

If used in the on dialog event, name is optional.

The following $did() properties are supported:

text

returns line or Nth line

$did(id) is same as $did(id).text

len

returns length of line or length of Nth line

lines

returns number of lines

sel

returns Line Number of Nth selected line

if N is 0, returns number of selected lines

seltext

returns selected text in an editbox or first selected item in a listbox

selstart

returns select start character in editbox line

selend

returns select end character in editbox line

edited

returns $true if text in editbox was changed

state

returns 0 = off, 1 = on, and 2 = indeterminate

next

returns id of next control in tab key order

prev

returns id of previous control in tab key order

visible

returns $true if the control is visible, otherwise $false

enabled

returns $true if the control is enabled, otherwise $false

csel

returns line number of Nth checked box in a listcb control

if N is 0, returns number of checked lines

cstate

returns 0 = off, 1 = on for item in a listcb control

You can access the edit control in a combobox by using 0 as the N value.

$didwm(name,id,wildtext,N)

Returns the number of the line that matches wildtext, with the search starting at line N. N is optional.

$didreg(name,id,regex,N)

Returns the number of the line that matches the regular expression, with the search starting at line N. N is optional.

$didtok(name,id,C)

Returns a tokenized list of the items in a list/combo/edit box.

You can use /didtok name id C text to add a tokenized list of items to a list/combo/edit box.