MIRC DIALOGS by pai03/22/99 This article attempts to teach all the important, basic stuff about mIRC dialogs. However, you MUST be reasonably proficient at scripting, as this tutorial will be very fast-paced and condensed, to cover a lot of material. For those who do not know, dialogs are those neat informative boxes in Windows that pop up to let you enter or change options. mIRC's options dialogs are examples. As of mIRC 5.5, features have been added to let a script create and use these dialogs. (sometimes referred to as GUI.) The following file does NOT contain the same samples used in this article, although some are similar. They are useful as examples for you to work from and learn more about dialogs. Download dialog-samples.mrc (Dialog examples ) A MINIMAL DIALOG Dialogs are created using dialog tables. A dialog table defines all the parts of the dialog, and is stored in a remote script file. Here is a very basic dialog table. ; This is a simple dialog example- the bare minimum. dialog bare { title "Test" size -1 -1 -1 -1 button "Done", 100, 20 20 40 40, OK } By itself, this code does nothing. You must tell mIRC to open a dialog using the /dialog command or $dialog identifier. $dialog opens 'modal' dialogs- these dialogs require you to respond before you can return to mIRC. /dialog opens 'nonmodal' dialogs- like normal windows, you can switch back and forth without closing the dialog. When you open a dialog, you need to name TWO things- the dialog table, and a name for the dialog. These are often the same, but do not need to be the same. Only one dialog with a given name can open at once; many dialogs can share the same table however. The table tells mIRC what to put in the dialog; from that point on, the dialog is referred to by it's name. Think of the table as a 'template' to build the dialog from. To open the above dialog, use the following- /dialog -m bare bare The first 'bare' is the dialog name. The second 'bare' is the dialog table. '-m' means to open a modeless (nonmodal) dialog. (this is required when opening a new dialog with /dialog.) This will open a basic dialog with nothing more than a button to close it. Let's examine the dialog table in detail. (make sure you understand the details, as later elements build on these concepts) dialog bare { The dialog prefix names the table, and the opening brace is required to start the table. title "test" This line simply names the dialog. It is not required, but usually used. size -1 -1 -1 -1 This line positions and sizes the dialog. Negative ones are to use default sizes. The first two numbers are X and Y position onscreen- Negative ones mean to center the dialog, and are commonly used. The second pair of numbers represent the width and height of dialog in pixels. These are usually given, but you can specify negative ones for 'default' sizing. (not recommended) button "Done", 100, 20 20 40 40, OK All remaining lines create controls in the dialog. This creates a push button- hence the word 'button'. The "Done" is the label for the button, always enclosed in quotes. The next number is the control's ID. An ID is a number from 1 to 250 that represents the control. All controls must have unique IDs, they are used to refer to the controls within events, etc. The next four numbers represent the X position, Y position, width, and height of the button. All numbers are in pixels. This will create a button 40 wide, 40 high, at 20 pixels across and 20 pixels down. Finally, special 'styles' are listed. In this case we give the 'OK' style, which makes this button close and accept the dialog. Styles are OPTIONAL, and more than one can be given. } The closing brace ends the dialog. This is the bare minimum dialog- ALL dialogs MUST have at least one button with the 'OK' or 'Cancel' style. It is important that you understand how to position and size this button, understand it's ID number, and styles, as all controls use this format. A SIMPLE AWAY DIALOG Here we will look at a slightly more complex dialog, with an editbox, text, and some checkboxes. dialog awayd { title "Set Away" size -1 -1 300 120 text "Away message?", 202, 14 10 80 20 edit "", 1, 10 30 280 22, result autohs check "&Pager on", 2, 10 60 65 16 check "&Logging on", 3, 95 60 75 16 button "OK", 101, 10 86 80 25, OK default button "Cancel", 102, 110 86 80 25, cancel } Don't get too worried- Most of this is pretty simple stuff to understand if you got the last example. The title is the same, and the size specifies the width and height of the dialog. The next line specifies a text control. This is simply plain, static text. '202' is the id of the control (remember, all controls have an ID) and then you have the position, width, and height of the control. (if you don't make the control big enough, the text will wrap or clip.) The next line defines an editbox. This is editable text. Similar to the static text, except there is no text given ("" means empty, so the editbox starts empty) and the two new styles. The 'result' style means that this editbox will be returned from a $dialog. (we'll discuss this later.) The 'autohs' style means that the editbox scrolls horizontally as needed. (automatic horizontal scroll) Without this style, you can only enter as much text as will fit. The next two lines define checkboxes. They are defined exactly like text. They will appear as a standard checkbox, with on and off states. All checkboxes default to off. The final two lines define two buttons. This is the same as the button from the last example, except for the styles. 'OK' marks the accept button, 'cancel' marks the cancel button, and 'default' marks the default button- the one that is pressed if you simply press Enter. (in most cases.) To run this dialog, use this alias- alias dlg2 { echo -s You entered $dialog(awayd,awayd,-4) } This will pop up the dialog, and if you press OK, display the reason you entered. $dialog is used to pop up this dialog. The first parameter is the dialog name, the second is the dialog table, and the third tells mIRC the 'parent' for the dialog. This isn't really that important usually- Negative four makes the active dialog/window the parent, and is usually the best choice. The $dialog identifier, unlike /dialog, STOPS all script processing until the dialog completes. It then returns whatever was entered in the 'result' control- the editbox with the 'result' style in this case. The end result- $dialog pops up the dialog, you enter an away reason, click OK, and then $dialog returns to the alias and returns the away reason you entered. WORKING WITH CHECKBOXES The above dialog has two nice checkboxes that don't do a damn thing. Let's learn some dialog events and how to interface to these checkboxes. All dialog events are of the following form- on *:DIALOG:name:event:id:{ } 'name' is the dialog name, (not table) event is an event type, (such as 'sclick' for a click) and 'id' is the ID of the control, or * for any control. Make sure you still have the away system dialog loaded from the last example, and add the following code- on *:DIALOG:awayd:sclick:2:{ set %checkpager $did(2).state if ($did(2).state) echo -s Pager on else echo -s Pager off } on *:DIALOG:awayd:sclick:3:{ set %checklog $did(3).state if ($did(3).state) echo -s Log on else echo -s Log off } These events 'detect' clicking on the checkboxes, and display appropriate messages. Notice the format of the event, first- 'awayd' is the dialog name, 'sclick' is the event type, and '2' and '3' are the IDs of the checkboxes. The first line then stores the state of the checkbox into a variable. $did() is used to retrieve info on dialog controls. $did(2) retrieves info on dialog control 2. $did(2).state gets the state of the checkbox that is control 2. It will return 0 for unchecked (off) and 1 for checked. (on) So this stores a 0 or 1 in the variable, depending on whether the checkbox is selected. The code then checks $did().state again. If it is selected (1) an 'on' message is displayed, otherwise an 'off' message is displayed. This works great so far, except the state of the checkboxes isn't restored when you open the dialog. Try this event for that- on *:DIALOG:awayd:init:*:{ if (%checkpager) { did -c awayd 2 } if (%checklog) { did -c awayd 3 } } This event, the 'init' event, is called when the dialog opens. The ID given is '*'- when the init event is called, the ID is 0, but * works as well, for 'any id'. Each line checks one of the variables, and if set, checks the specified checkbox in the dialog. This is done with the /did command- used to manipulate dialog controls. '-c' is used to select (check) a control. 'awayd' is the dialog name. '2' and '3' are the IDs for the checkbox controls. Once this section and the previous sections are entered, the away dialog will remember it's settings each time it opens, unless the variables are cleared. RADIO BUTTONS Radio buttons are similar to checkboxes, except you can only have one radio button out of a group selected at one time. Try this dialog- dialog grouping { title "Radio Buttons" size -1 -1 300 200 radio "Option A", 1, 5 5 120 16, group radio "Option B", 2, 5 25 120 16 radio "Selection A", 3, 150 5 120 16, group radio "Selection B", 4, 150 25 120 16 radio "Selection C", 5, 150 45 120 16 button "OK", 100, 120 120 60 25, ok } on *:DIALOG:grouping:init:*:{ %@opt = A %@sel = A did -c $dname 1 did -c $dname 3 } on *:DIALOG:grouping:sclick:1:{ %@opt = A } on *:DIALOG:grouping:sclick:2:{ %@opt = B } on *:DIALOG:grouping:sclick:3:{ %@sel = A } on *:DIALOG:grouping:sclick:4:{ %@sel = B } on *:DIALOG:grouping:sclick:5:{ %@sel = C } on *:DIALOG:grouping:sclick:100:{ echo -s Option %@opt and Selection %@sel unset %@opt %@sel } alias dlg4 { dialog -m grouping grouping } This is a large chunk of dialog code, but it shouldn't be too hard to understand. The dialog table is similar to what you've already seen. The only change is 'radio' controls. They are EXACTLY like checkbox controls, except they appear as round dots instead of squares with 'X'. Also, only ONE radio can be selected at a time, within a group. This is what the 'group' style signifies- The start of a group. As you can see here, we have two groups of radio buttons. The 'init' event presets some variables, and preselects some radio buttons. Like checkboxes, radio buttons are never selected to begin with, so you should use /did -c to select one radio button in each group in the 'init' event. We check radio buttons 1 and 3 here. The 'sclick' events all store values in our variables according to the radio button selected. The radio buttons automatically 'deselect' the other buttons in the group- we simply use 'sclick' events to keep track of which option is selected in each group. Finally, in the 'sclick' event for the button (id 100) we display in status which options were selected, and unset our variables. Note that we do NOT have to track these with variables if we do not want- $did().state works on radio buttons just like it does on checkboxes. However, it still returns only 0 or 1 for each button, so you have to check EACH button in a group to find the one that is selected. EDITBOXES This dialog shows how to make various types of editboxes, for entering in text. dialog editbox { title "Editbox Samples" size -1 -1 500 400 text "Basic editbox", 1, 5 5 240 20 edit "", 2, 5 25 100 22 text "Multi line with enter", 3, 250 5 240 20 edit "", 4, 250 25 200 70, multi return text "Password field", 5, 5 100 240 20 edit "", 6, 5 120 200 22, pass result text "Horizontal auto-scroll", 7, 250 100 240 20 edit "", 8, 250 120 50 22, autohs text "Large box with scrollbars", 9, 5 200 240 20 edit "", 10, 5 220 200 80, multi return hsbar vsbar text "Can't edit it!", 11, 250 200 240 20 edit "Hahahahaha", 12, 250 220 200 22, read button "OK", 100, 200 340 100 25, ok } alias dlg5 { echo -s password: $dialog(editbox,editbox,0) } Open this dialog, and notice how each editbox works. Editboxes are controls of the 'edit' type. The width and height determines how large the box itself is. Other than that, the only new things here are the various styles. However, these are very important- editboxes have many important styles. The basic editbox only contains one line and you cannot type past the boundaries. Add the 'multi' capability, and you can type multiple lines if you type past the right edge. (word wrap) The 'return' capability adds the ability to press Enter for a new line. The 'autohs' capability sets an editbox so that it automatically scrolls horizontally. This allows entering more data than will show in the editbox. You can do this for vertical scrolling using 'autovs'. The 'hsbar' and 'vsbar' styles add horizontal and vertical scrollbars, respectively. This allows manual scrolling. The 'read' style makes a box read only, and the 'pass' style makes an editbox show '***' for password entry. (the 'password' is not encrypted in any way) Play with the styles (especially the scrolling and multiline styles) to get a feel for which ones are needed in which circumstances. OPENING MULTIPLE DIALOGS The last important point that needs to be made is having one dialog open another dialog. (or a $? query box, a $dir directory listing, etc.) mIRC CANNOT call popup boxes from within an event. This includes $dialog, $?, $dir, and applies to dialog events. mIRC 5.51 could not call /dialog from an event either, but mIRC 5.6 can now use /dialog directly in an event. However, you still cannot use $dialog, $dir, etc. from within an event, so this technique is still very important. There is a simple workaround, and that is the use of /timer. Here's a simple example. dialog first { title "First" size 50 50 110 100 button "Click me!", 100, 5 5 100 25, default button "Close", 200, 5 50 100 25, ok } dialog second { title "Second" size 150 150 110 80 button "Close", 200, 5 50 100 25, cancel default } on *:DIALOG:first:sclick:100:.timer 1 0 dlg6b alias dlg6 { /dialog -am first first } alias dlg6b { %temp = $dialog(second,second,-4) } /dlg6 will open one dialog, and /dlg6b will open the second. Also, when you have the first open, clicking 'Click me!' will open the second. Notice that the 'sclick' event does NOT just call /dlg6b. Instead, it uses a timer. The timer runs once (1) and executes immediately (0) so the user sees no delay. Whenever you use this workaround, you should always put the desired code in a NEW alias. Don't try to do the following-\ .timer 1 0 set %var $dir="select file:" c:\ Instead, do- .timer 1 0 doit alias doit { set %var $dir="select file:" c:\ } This is because timers immediately evaluate their contents, then reevaluate them again when they fire. This is good sometimes, and can be worked around, but the easiest way to prevent problems is to just use seperate aliases. If you ever have problems making dialogs open more dialogs or file selection boxes, etc. this is the trick you need. MORE INFO For more help, you can look up /dialog info in the mIRC help file. Some important things we didn't cover- Listboxes/comboboxes Icons/bitmaps Boxes Various styles (disable, hide, etc.) Some dialog events Most uses of /did Extended uses of /dialog Extended uses of $dialog As you can see, dialogs are a very large topic. Future tutorials at paiRC may cover specific areas in depth, but this tutorial and the samples file can hopefully get you started. The following file contains further examples to work from- some are similar to the ones in this article, some are unique to the file. Download dialog-samples.mrc (Dialog examples ) If you have any suggestions or additions for this article or wish to submit an article or idea, please contact webgoddess@pairc.com Copyright and usage restrictions