|
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 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 -blp interprets size as dbu, map, 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).
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 mapw,maph return mapped dbu pixel measurements active returns $true if dialog is the active window, otherwise $false hwnd returns dialog window handle
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, map, pixels, notheme, disable)
text "text", id, x y w h, style (left, right, center, nowrap) edit "text", id, x y w h, style (left, 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 (left, right, center) 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.
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.
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.
Note: Dialog events, such as the click event, are triggered by windows messages. Sometimes, clicking in a window can result in multiple window messages being sent, such as activation, focus, mouse movement, clicks, and so on. This means that if you are doing something in an event that affects the GUI, such as using /window, you may need to use a /timer to avoid unexpected behaviours.
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].
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.
Returns the number of the line that matches wildtext, with the search starting at line N. N is optional.
Returns the number of the line that matches the regular expression, with the search starting at line N. N is optional.
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. |