Editing mirc/dialogs

{{mirc title|Dialogs}}

'''Dialogs''' make it possible to create custom dialog windows inside of mIRC. The [[/dialog command - mIRC|/dialog command]] is the key way to opening new dialogs, and the [[Dialog components - mIRC|Dialog components]] are the objects within the dialog, such as buttons, labels, etc.

=== What dialogs are ===
Dialogs are simply [[graphical user interfaces]] that present options to a user's screen in a graphical form. For instance, a web browser is display through its own dialog. Windows users may have used applications such as notepad, or Microsoft Word. All of these applications use dialogs, or forms of [[graphical user interfaces]] to present their applications in an appealing form.

=== mIRC Dialogs ===
mIRC dialogs are created by users through custom scripts. Through these dialog interactions, the dialogs adhere to an event listener, the [[On dialog - mIRC|ON DIALOG]] event. Through this event, all aspects of the custom dialogs, as well as their controls, can be monitored, tracked, and modified.

=== Scope ===
The scope of this article is to generally familiarize users with the term '''dialogs''', and what exactly it is they are used for within mIRC. Since these components are geared towards more advanced scripters, beginners should make sure they have already gone through the preceding tutorials from the [[Introduction - mIRC|mIRC Introduction]] page, all the way leading up to '''Dialogs'''

=== Two types of dialog ===

They are two type of dialogs - modeless dialog and modal dialog.

Modals dialog are dialog which block the current script execution, you cannot access others windows, usually used to get a quick user input.
mIRC has built-in modals dialog, {{mIRC|$?}}'s famillies and {{mIRC|$input}} are modals dialogs.

Modeless dialog can be opened indefinitely and does not halt the script execution.
mIRC also has modeless dialog, such as the mIRC Options dialog (alt + o).

==== Modeless dialog ====

You can create a modeless dialog using the {{mIRC|/dialog}} command with the -m switch, there are others switch that can be used at creation time and after the creation of the dialog to change various states.

<source lang="mIRC">
/dialog -m <name> <table>
</source>

<name> is the name used to reference the instance of the dialog (you can run multiple instance of the same dialog at the same time)

&lt;table&gt; is the name of the dialog table to use

==== Modal dialog ====

You can create a modal dialog using the {{mIRC|$dialog}} identifier with the following syntax:

$dialog(name,table[,parent])

* name - The name used to reference the instance of the dialog
* table - The name of the dialog table to use
* parent - Optional, this can be a window name or:
** -1 - Desktop window
** -2 - Main mIRC window
** -3 - Current active window
** -4 - Current active dialog if no dialog is open
** The default is -3.

Any control can be used in the dialog with the "result" style, the value returned by $dialog is be the value of that control.

'''Note''': Since modal dialog block the current script execution, you cannot call $dialog that way from remote script event.

=== Creating a dialog table ===

Custom dialogs are created by defining a dialog table, the content of that table represents the look of the dialog, the controls etc, a table is defined by using the <dialog> keyword:

<source lang="mIRC">dialog -l <name> {

    title        "text"

    icon         filename, index

    size         x y w h

    option       type                                   (pixels, dbu, map, 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]

}</source>

The -l switch makes the table local, only that script file can open it. <name> is the name of table which will be used to create an instance of that dialog

* title - Optional, can be used to set the text displayed in the titlebar of the dialog
* icon - Optional, can be used to set the icon of the dialog, the filename parameter is the filename to use for the icon, the index parameter can be used to specify the Nth icon from a file
* size - Required, set the size of the dialog, you can use -1 for any of the x, y, w and h parameter to specify a default position, x and y sets as -1 should center the dialog in the window
* option - Can be used to set different options for the dialog, type is a space seperated list of options:
** pixels - x y w h values are in pixels - this is the default option if you don't use the dbu or map options.
** dbu - x y w h values are in dialog base units (DBUs) - this option attempts to make the dialog look the same on any size display - however anecdotal evidence suggests that there are issues with DBU when user has Windows 10 Settings / System / Display / Scaling set to > 100%.
** map - x y w h values are in MAP units - this (undocumented) option will also try to ensure that the dialog looks the same under any size display even when Windows 10 Display Scaling is > 100%. MAP units are '''not''' the same as DBUs and you will have to recalculate x y w & h values if you switch from DBU to MAP. There are no MAP equivalents for $dbuw and $dbuh identifiers.
** notheme - This option prevents mIRC from applying your current windows theme to the dialog - if you like your dialogs to have a retro Windows XP feel to them which is different to how the style used by the rest of mIRC, then this is the option for you.
** disable - This option can use used to wait a bit before the controls in the dialog can be used, preventing accidents
* Others elements are used to create controls, see the [[Dialog Components - mIRC|dialog Components page]]

You can use a variable name as a style for any control, the variable is set (global variable) with the value of that control when the dialog is closed:

<source lang="mIRC">edit "", 2, 10 10 100 20, autohs %myedit</source>

=== Mnemonic ===

The "text" parameter of controls showing text can include the '&' character to create a mnemonic if you want to get the '&' rendered literaly, use &&.

'''Note''': even if a control renders the mnemonic correctly, the shortcut may not work, it's not working to switch tab for example.

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

<source>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
}
</source>

=== /did command & $did identifier ===

The {{mIRC|/did}} command can be used to change the various state of the control while {{mIRC|$did}} can be used to retrieve values and states of controls.

Check the [[Dialog Components - mIRC|dialog Components page]], which describe the usage of the two per control.

=== Others tools ===

==== /didtok, $didtok, $didwm and $didreg ====

{{mIRC|/didtok}} <name> <id> <C> <text>      will add a tokenized list of item to a list/combo/edit control, for example "/didtok name 1 44 red,green,blue" would add the item "red", "gree", and "blue" to that control

{{mIRC|$didtok}}(name,id,C) returns a tokenized list of item from a combo/edit/list control.

{{mIRC|$didwm}}(name,id,wildcard,N) and {{mIRC|$didreg}}(name,id,regex,N) returns the number of the line that match the expresion, starting at the optional line N, in the the control.

==== /loadbuf, /savebuf and /filter ====

You can {{mIRC|/filter}} from and to a combo/edit/list control.

You can {{mIRC|/loadbuf}} and {{mIRC|/savebuf}} from and to a combo/edit/list control.

== See Also ==
* {{mIRC|dialog components}}
* {{mIRC|on dialog}}
[[Category:mIRC|dialogs]]