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 does not 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

 

 -g        renames existing dialog using <name> <newname>

 

Where name is the name by which you will 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 do not 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 will 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, disable)

 

 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, rich)

 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, radio)

 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 small large actual)

 

 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 do not 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 specify multiple ids by using commas and dashes, eg. 1-3,5,7,9,15-20.

 

You can also detect mouse events that are not 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

isid        returns $true if id exists in the dialog, 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.