Tips - mIRC Dialogs (paiRC)

ContentZone Network

News

Techniques

Articles
Identifiers
Numerics
Lessons

pai's scripts
More Info
Interactive
Webboard

Site Map

More quality sites:

Link to paiRC!

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