Editing mirc/dialogs

{{mirc title|Dialogs}}

'''Dialogs''' make it possible to create custom dialog windows inside of mIRC. The {{mIRC|/dialog}} command opens new dialogs, and the {{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 {{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 {{mIRC|Introduction}} page, all the way leading up to '''Dialogs'''

=== Two types of dialog ===

They are two type of dialogs - modal dialogs which block access to other parts of the mIRC interface until they are closed, and modeless dialogs which can be left open whilst continuing to allow access to the rest of mIRC (i.e. effectively a separate mIRC-based window).

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 families and {{mIRC|$input}} are modals dialogs.

Modeless dialog can be opened indefinitely and does not halt the script execution.

==== 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.

'''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 {{mIRC|dialog components}}

Remember that once the dialog is created, mIRC does not allow you to resize the controls in the dialog. You can use variable and identifiers inside the dialog table to create dialog control with dynamic size
You can also 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">
;use a variable to define the width and an identifier to define the height of the dialog, when the dialog is closed, %myedit will contain the content of the editbox.
edit "", 2, 10 10 %dialog_width $dialog_height, 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 lang="mIRC">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 {{mIRC|dialog components}}, 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 {{mirc|wildcard}} expression, 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]]