mScriptBox Tutorial
Introduction to Dialogs
Written by Pasmal
Published with permission.

Table Of Contents

    Introduction
  1. Creating a Dialog
  2. Putting Stuff onto the Dialog
    1. Writing Text onto a dialog
    2. Creating a Button
    3. Creating an Editbox
    4. To add a Check Box
    5. To add a Radio Button
    6. Creating a Box (frame)
    7. Adding An Icon
    8. Creating a Listbox
    9. Creating a Combo
    10. Creating a Tab
  3. What size was that?
  4. Adding and Removing Text to an already created Dialog
  5. Grouping Radio Boxes
  6. More Appearance changes (Part 1)
    1. Checking/Unchecking A Check/Radio/Combo Box
    2. Selecting Text In An Edit Box
    3. Adding/Removing Focus on an item
    4. Enable/Disable Items
    5. Hiding and Showing Items
  7. More Appearance changes (Part 2)
  8. The $Did Identifier
    1. Am I Invisable?
    2. Returning the Text in a Dialog Item
    3. Returning the Selected Text in a Dialog Item
    4. Returning the Length of Text
    5. Returning the Number Of Lines of Text
    6. Returning the State of a Checkbox or Radio
  9. DidTok
  10. Dialog Switches
  11. Other Dialog Identifiers
  12. A Closer Look at Dialog Events
    1. Event INIT
    2. Event SCLICK
    3. Event DCLICK
    4. Event EDIT
  13. $Dialog & Modal Dialogs
  14. Dynamic Dialog Names
  15. Designing An Interface
  16. Providing Responses When They Are Needed
  17. Other Dialog Scripts/Examples
  18. Scripting Tip 1: Say to yourself "uniform"
  19. Scripting Tip 2: I need breathing room!
  20. Scripting Tip 3: Alias out Repetitive Tasks
  21. Scripting Tip 4: Use Wildcards in events
  22. Scripting Tip 5: Icons can be buttons
  23. Scripting Tip 6: Animations
  24. Scripting Tip 7:Divide and Conquer
  25. Conclusion


Introduction

Dialogs were first introduced into mIRC in version 5.5. Dialogs are, simply put, a type of GUI - or graphical user interface. They are, to some, more complex than picture windows, and to others, like myself, easier. mIRC 5.51 brought along alot of bug fixes and improvements to dialogs. You should consult your versions.txt file for a full listing. mIRC 5.6 also contained a few minor changes. mIRC 5.61 gave us the ability to create tabs - but alas no coloured text yet.

Dialogs can be difficult to grasp at first, but after a few attempts you will start to get used to it.


1. Creating a Dialog  Back to Top

Dialogs are opened using the /dialog command. Its basic format is: /dialog -switches name table. The name is simply what you want to use to refer to it in remotes. The table is the basis for the dialog - or simply put the building blocks. When creating a table, I prefer to use a modeless table (that is, it will not stop the script processing, and will operate independently of the script which called it). To create a modeless table, use the -m switch.

The table is placed in a remote file, with the prefix dialog. Inside it you need to put the commands to create the dialog, and put objects in it. Its format:

DIALOG tablename
{
  commands
}

All items put in the table require their own individual identifier tag (id for short). There are many items you can put in the dialog table. Most items put into a table requires an id. An id is just a way of assigning an item a name, which can then be used with the on DIALOG event, and the /did command. The id's do not have to be in sequential order. (i.e. not 1 2 3 4 5 etc...) but you will find it easier to organise your dialog that way. The lowest id you can use is 1 and the highest is 3000. Every id you put into the table has to be unique - so you cannot have two items in the table with an id of 7 as an example.

Its similar with real life. For example, parents give their children individual names. Now imagine a family with 5 children, all with no names - the parents would not know who is who. Now imagine if you have twins, and called them both Jeff? It is also likely to cause confusion.

A simple table requires at least 2 items:

  1. The Size. This item determines the basic shape of your dialog. Its similar to the xy wh values on the /window command. Its Format: size x y w h. If you want to put the dialog box in the centre of your screen, replace x and y each with -1. The w and h stand for the width and height of the dialog.
  2. An OK/Cancel Button. If not present, a dialog will not open. Its format is:

    button "text",id, x y w h,style (The style can be default, ok, or cancel).

    The x is the amount of distance the button should be placed, right from the top-left point of the dialog. The y is the amount of distance the button should be placed down from the top-left point of the dialog. The w is the width of the button, and the h is how tall the button is.

  3. The title. Quite simple to do. In your table put Title "text to use as a title". This item is not required, and if you leave it out the title will be "mIRC Input Request".

Now to apply these items to create our first dialog.

In remotes put:

DIALOG first {
  title "This is our first dialog"
  size -1 -1 300 100
  ; this size creates a window in the middle (-1 -1) of the screen. 
  ; It will be 300 wide and 100 tall.
  button "OK",1 ,1 75 120 25, OK
  ; An OK or Cancel button IS required. I gave this button an id of  1. 
  ; It will be placed 1 across , and 75 down  from the
  ; top left of the dialog. It will be 120 wide, and be 25 tall. 
  ; 25 is about the same size as a normal button.
}

Then to create the dialog, type /dialog -m first first
Something similar to the below should appear:

1. This is the OK button we made, (button "OK" etc...). It does not have to have OK as its name, you can change the text to whatever you wish. Its id is 1.

2. This is our title, (title "this is our first dialog"). You can change this at any time using the /dialog -t name text.


2. Putting Stuff onto the Dialog  Back to Top

Below is a list of various items that you can use in your table. Each item comes with an example. When attempting a new example, its recommended you remove any previous example (Do not remove the Title,Size and Button tag). To activate the example, type /dialog -m first first


2a. Writing text onto a dialog  Back to Top

This requires you to use the item in the dialog table. Its format is: text "text",id,x y w h, style
The style is simply the way you want the text to be displayed - this is optional.
The styles are:

Right:
This puts the text as far right in its area as it can.
Center:
This puts the text at the center of the area.
Tab <N>:
Tells it which tab it should appear in if you want to place it in a tab.

By area I refer to the area defined by the w(idth) and h(eight).

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
text "Hello World",2, 1 1 100 25
}



2b. Creating a Button  Back to Top

To insert a button you need to use the button item. Its format is: button "button text",id,x y w h,style

The styles are: ok,default,cancel
OK is just to designate that particular button as the OK button (though it does not need to say OK for the button text). It also closes the window.

Cancel is just to designate that particular button as the CANCEL button (though it does not need to say CANCEL for the button text). It also closes the window. When a user closes a dialog via its [x] button your cancel id is activated even though the actual button has not been pushed. To close the window without setting off remotes use /dialog -x dialog.

Default is to designate what button will be "pushed" when the user presses the enter key. This does not close the window.

You do NOT have to give every button a style.

Example:

Dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 5 120 25, OK
button "Close",2, 1 35 120 25, CANCEL
button "Default",3, 1 65 120 25, DEFAULT
button "Other Button",4, 130 5 100 25
button "Another Button",5, 130 35 100 25
button "Press Me!",6, 130 65 100 25
}



2c. Creating an Editbox  Back to Top

The item to create an editbox is edit. Its format is: edit "text",id,x y w h, style
A typical editbox looks like:

The styles are:

Right, center, multi, pass, read, return, hsbar, vsbar, autohs, autovs, tab

Multi allows you to create a multi line edit box. (Just make your h value larger to add extra lines).
Pass gives the same effect as $?* - it changes text to * (password entry box).
Read makes the editbox uneditable, the area is shaded gray. This can be used for information windows.
Hsbar adds a horizontal scroll bar.
Vsbar adds a vertical scroll bar.
Autohs adds an "invisible" horizontal scroll bar that lets you keep typing past the length of the editbox.
Autovs is the same, except it uses a vertical scroll bar.
Return lets you put multiple lines of text into a multi editbox.

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
edit "Default Text",2, 10 30 150 20
}



2d. Adding a Check Box  Back to Top

Use the check item. Its format is: check "text",id, x y w h,style
Its styles are: left, push, 3state, tab

Push: Creates a push button, not a check box.
3state: This creates a 3 state button: 1) unchecked 2) checked 3) Checked with gray background

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
check "3State Checkbox",2, 5 30 170 25,3state
}

One advantage of using a 3 state checkbox is that you can "lock" certain settings on or off. To lock a setting on, using the checkbox example, in any mIRC window type /did -cu first 2.


2e. Adding a Radio Button  Back to Top

Item needed: radio. Format: radio "text",id,x y w h,style
A typical radio button looks like:

Styles: left, push, tab

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
text "Select Gender:",2, 1 1 140 25
radio "Male",3,1 20 60 25
radio "Female",4,1 40 60 25
}

You can also do groups of radio buttons, but this will be explained later.


2f. Creating a Box (frame)  Back to Top

Item needed: box. Format: box "title text",id, x y w h,style
No known styles available except tab.

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
box "Script Info",2, 20 5 110 60
text "Name: Dialog Script",3, 25 20 60 25
text "Version: 1.0",4, 25 45 60 25
}



2g. Adding An Icon  Back to Top

Item needed: icon Format: icon id, x y w h, filename, index, style
Styles: tab

The index is the picture number inside an icon file you wish to use. Usually icon files only have 1 icon in them, thus for your index you would use 1 or it can even be omitted. If you use Windows 95 (And maybe Win98/NT), a good index example is C:\WINDOWS\SYSTEM\PIFMGR.DLL (Substitute c:\windows for your windows folder).

The w and h designates an area in the dialog which the picture can be drawn in. If the picture is bigger than this area, then mIRC will shrink it down to fit in. The file does not need to have a .ico extension. What matters is that its in bitmap format.

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
icon 2, 1 1 36 36, C:\WINDOWS\SYSTEM\PIFMGR.DLL,1
icon 3, 40 1 36 36, C:\WINDOWS\SYSTEM\PIFMGR.DLL,2
icon 4, 80 -1 36 36, C:\WINDOWS\SYSTEM\PIFMGR.DLL,5
}

The first icon line displays the first icon located in pifmgr.dll into an area 36 wide by 36 high.
The second icon line displays the second icon located in pifmgr.dll into an area 36 by 36.
The third icon line displays the fifth icon located in pifmgr.dll into an area 36 by 36.

We can change the image using the dialog command. The format to do so is: /did -g name id [n] filename
[n] is the optional index number. If the file only has one graphic - then [n] can be omitted (left out).

So if we wanted to change the first icon to lets say a picture of a keyboard, we would type:

/did -g first 4 12 c:\windows\system\pifmgr.dll

Don't have pifmgr.dll ? Click here - its part of windows.

Another idea that I have been experimenting with is animations with dialogs. The Scripting Tips section dabbles into this.


2h. Creating a Listbox  Back to Top

Item needed: list Format: list id,x y w h, style
Typical List Box:

Styles: sort, extsel, hsbar, tab

Sort: Any text put into the list will be arranged in alphabetical order.
Extsel: Gives the listbox greater selection capabilities

To add text to the list, you need to use the did -a name id text command. You may use it as many times as you want. If you add more lines than there is visible space, a scroll bar will appear. The easiest way to create a list when a dialog is created is to use the on *:DIALOG:first:init:0: event. (This event will be explained later).

Example:

on *:DIALOG:first:init:0:{
;this event reacts when the dialog is created (init)
;then uses did -a to put some text into the item whose id is 2 (which is the list in this example)
did -a first 2 Pear
did -a first 2 Banana
did -a first 2 Orange
did -a first 2 Apples
did -a first 2 Pineapple
}

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
list 2, 1 1 70 70, sort
}

Note that the text in the list has been sorted alphabetically.


2i. Creating a Combo Box  Back to Top

Item needed: combo. Format: combo id,x y w h, style
Typical Combo:

Styles: sort, edit, drop, hsbar, tab
Drop: Creates a drop down box.

Example:

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1, 1 75 120 25, OK
combo 2,1 25 120 140,drop
text "What Is Your Fav. Fruit?",3, 1 1 180 25
}

on *:DIALOG:first:init:0:{
;this event reacts when the dialog is created (init)
;then uses did -a to put some text into the item whose id is 2 (which is the combo in this example)
did -a first 2 Pear
did -a first 2 Banana
did -a first 2 Orange
did -a first 2 Apples
did -a first 2 Pineapple
}



2j. Creating a Tab  Back to Top

Item needed: tab. Format: tab "Tab Title",id,x y w h
Please be aware that you only have to specify the x y w h for the FIRST TAB. It sets the dimensions for any other tabs to come.

When you want to place other items into a particular tab, you need to use the tab <n> style. I usually place it at the end of all my styles for that particular item - so you can easily see what tab that item refers to. Example: We want to place a "Hello World" text item into a tab (lets say its tab 15). We could use:

text "Hello World",id,x y w h,right tab 15

This also means that somewhere earlier on in the dialog table we would have had a tab line. It should look similar to:

tab "Somename",15,x y w h

Example:

dialog tab {
  title "Our First Dialog"
  size -1 -1 212 100
  option dbu

  tab "Flood",1, 5 5 150 95
  tab "Repeat",2
  tab "Clone",3
  tab "About",4

  button "Done",6,160 85 50 20,ok

  check "Enable Flood Kicker",7, 20 25 80 20, tab 1
  check "Enable Repeat Kicker",8, 20 25 80 20, tab 2
  check "Enable Clone Kicker",9, 20 25 80 20, tab 3

  box "Created By Me!",11,20 25 115 4,tab 4
  text "Pasmal",12,20 50 100 20,tab 4
  text "pasmal@zaz.net",13,20 60 100 20,tab 4
  text "#HelpDesk Dialog Introduction",14,20 70 100 20,tab 4
  text "http://home.dreamhaven.net/~hdesk",15,20 80 100 20,tab 4

  box "",17, 20 40 115 4,tab 1
  text "React after",18,20 50 27 20,tab 1
  edit "",19,48 49 16 10,autohs tab 1
  text "lines in",20,67 50 18 20,tab 1
  edit "",21,86 49 20 10,autohs tab 1
  text "seconds",22,108 50 25 20,tab 1
  check "Kick person",23,20 60 60 10,tab 1
  check "Ban person",24,20 70 60 10,tab 1
  check "Ignore person",25,20 80 60 10,tab 1

  box "",26, 20 40 115 4,tab 2
  text "React after",27,20 50 27 20,tab 2
  edit "",28,48 49 16 10,autohs tab 2
  text "repeats in",29,67 50 25 20,tab 2
  edit "",30,92 49 20 10,autohs tab 2
  text "seconds",31,114 50 25 20,tab 2
  check "Kick person",32,20 60 60 10,tab 2
  check "Ban person",33,20 70 60 10,tab 2
  check "Ignore person",34,20 80 60 10,tab 2

  box "",35, 20 40 115 4,tab 3
  text "React after",36,20 50 27 20,tab 3
  edit "",37,48 49 16 10,autohs tab 3
  text "clones join a channel",38,67 50 70 20,tab 3
  check "Kick clones",41,20 60 60 10,tab 3
  check "Ban site",42,20 70 60 10,tab 3
  check "Ignore site",43,20 80 60 10,tab 3
}

To open the dialog, I strongly advise you to type /dialog -mdo tab tab. Please note that its only a table, not actually a flood/repeat/clone kicker.

If you want to know what tab is currently selected, you need to use $dialog(dname).tab


3. What size was that?  Back to Top

Size is an item in the dialog table, but I felt that I should explain it seperatly. You can omit this item and your dialog -should- appear as it used to. If you do include this item, you will probably need to rewrite some of the table. So why do it?

DBU - Dialog Based Units
This type of measurement means that no matter what display size the dialog is run on, it will always look the same. I tend to find this option very useful for dialogs which contain tabs. To use dbu's, in the dialog table insert: option dbu. There is an example of this in the dialog/tab section of the help file, and in the TAB section of this document.
Pixels
This is the way that dialogs have been done so far. By default if no option is given, then pixels are used. Try remove "option dbu" from my tab.mrc example or Khaled's example in the mIRC help file - both become very distorted and 'crunched' up. If you are concerned about consistency, then dbu is the way to go. If you wish, you can use the $dbuw and $dbuh identifiers to return dbu per pixel width and height.


4. Adding and Removing Text to an already created Dialog  Back to Top

This task requires you to use the /did command. Its basic format is: /did -switches name id [n] [text | filename]
Anything in []'s is optional. Since we want to add text to an item, we need to use the -a switch. We also need to know the id of the item we wish to add to. For example, we could rename the OK button using the did command. To do so, type (after opening a dialog):

/did -a first 1 Push This!

We used 1 because the OK buttons ID is 1. You are not limited to renaming buttons, you can also add text to most items. For example, in the last example (combo) if we wanted to change "What Is Your Fav. Fruit?" to "What Fruit Do You Hate The Most?" we would use the did command. I gave the "what fruit etc..." item an id of 3, so we need to include this in the did command.

/did -a first 3 What Fruit Do You Hate The Most?

If you try and change the text of an item, be sure that it will fit. The w value in most items sets the max length the text for that item can be. If you make a large h value, then if the text is to large, it will continue on a new line (Word Wrap).

Removing all text in an id is similar to adding text. Its format is: /did -r name id. Example (using the combo box example again). Open the dialog, then type /did -r first 2. Click on the combo box - it should have no listings.

But what if you wanted to delete just one listing? Then use the /did -d name id line-number command. Using the combo box again, type /did -d first 2 3. "Oranges" should have disappeared from the combo box.


5. Grouping Radio Boxes  Back to Top

Without groups, mIRC assumes every radio box in a dialog is related to each other. This means that in your whole dialog, you can only have one filled radio box. The solution? Group your radio boxes. Unlike remote groups, you do not specify a groupname, nor is the group started with #group on and ended with #group end. To start a group, for the style for the first radio button of a group you wish to make, enter group. Don't enter group as your style for any other radios in the group you want. These groups do not effect other items like check boxes. To start another group (and end the last group), simply put group as the style for the start of your next group. Sound confusing? It did to me. Perhaps an example will help (this uses the "first dialog" example):

dialog first {
title "This is our first dialog"
size -1 -1 300 100
button "OK",1,1 75 120 25, OK
text "Gender:",2,1 1 60 25
;this is the start of the first group
radio "Male",3,50 1 50 20,group
radio "Female",4,100 1 60 20
text "Marital Status:",5,1 25 120 25

;this second group starter automatically ends the first group
radio "Single",6,70 20 50 25,group
radio "Married",7,125 20 60 25
radio "Other",8,190 20 60 25
text "Age:",9,1 45 30 25

;this next group also tells the script that the last radio item before this group was the last item for the last group
;yes i know - a tongue twister.
radio "Under 10",10,30 40 65 25,group
radio "10 to 20",11,100 40 65 25
radio "Over 20",12,165 40 65 25

}

The first group for this table starts at id 3, and ends with id 4.
The second group starts at id 6, also contains 7 and 8.
The third and last group starts with id 10, and also has 11 and 12 in it.

There are more group examples in gui-kick.mrc which can be found in the "Other Dialog Scripts/Examples" section.


6. More Appearance changes (Part 1)  Back to Top

Not only can you add and remove text from the dialog, you can also hide/show, focus/unfocus, enable/disable, check/uncheck + more. Most of these changes are made with the /did command. But before I can explain them properly to you, you need to know more about the on DIALOG event. The on DIALOG event reacts whenever something happens which effects any item in a dialog. Its format is:

on *:DIALOG:name:event:id:

When activated, the on DIALOG event allows you to use three new identifiers, $dname, $devent, and $did. $dname stands for the name of the dialog which activated the event. $devent stands for the event. $did stands for the id of the item effected.

There are several different types of events: init,sclick,edit,dclick.

init: reacts just before a dialog is displayed, controls can be initialized in this event. id is zero.
edit: reacts when text in editbox or combo box changed.
sclick: reacts when a single click in list/combo box, or check/uncheck of radio/check buttons, or click of a button occurs.
dclick: reacts when a double click in list/combo box occurs.

If you wish to debug your dialog use the following:

on *:DIALOG:name:*:*: {
;this is nearly a copy/paste from the help file.
echo $dname $devent $did
}

Look at this Setup Script Example

Please copy paste the code above into your remotes. To run the dialog, type /ss . When you type /ss, a dialog similar to the image below, should appear.

Now back to changing appearances.
Below is a list of the majority of changes you can do, with its command and example. Also, since mIRC 5.6, the /did command can now do multiple id's in one line.
So you could check multiple checkboxes using /did -c dname id1,id2,id3,id4,etc... Guess this kills my mdid aliases :(.


6a. Checking/Unchecking A Check/Radio/Combo Box  Back to Top

If you wish to tick/fill/highlight a check/radio/combo box, the command you will need is the /did -c command. Its format is: /did -c name id [number]. The [number] is only used for checking combo boxes.

Examples:

To check the "Join Channels On Connect" checkbox, open the dialog (type /ss) and in your status window type:
/did -c setup 18

To put a dot in "Male" in the Gender selection, open the dialog, and in the status window type:
/did -c setup 11

To highlight a channel in the Favorites List, open the dialog, and in the status window type:
/did -c setup 14 2

This should highlight the second favorite channel in your list. If it does not, then you have not set a second favorite channel.

If you wish to untick/unfill a Check/Radio Box, then the command you should use is the /did -u command. Its format is: /did -u name id

If you wish to select a line in a drop down combo, then the command you should use is the /did -c command. Its format is: /did -c name id

Examples:

To uncheck the "Join Channels On Connect" checkbox, in your status window type:
/did -u setup 18

If you are using a 3state checkbox, then by using -cu as your switch, it grays the check box (Makes it intermediate).

To remove the dot (unfill) in Male in the Gender selection, in your status window type:
/did -u setup 11


6b. Selecting Text in A Edit Box  Back to Top

If you want to select some specific text in an editbox and are using mIRC 5.7 or higher you can do so using the /did -c command. The format you want to use is:

/did -c dname id [n] [start [end]]

This lets you select the N'th line in an editbox (and thus scroll down to the selected text). If you want you can select just a portion of the text of that line using the [start [end]] values. Start is the location of the first character to select - e.g. 5 would start the selected at the 5th character. If your end value exceeds the total length of the line then mIRC will just keep highlighting until it highlights as many characters as you specified in your end value.


6c. Adding/Removing Focus on an item  Back to Top

To put a Focus on an item is to basically add a thin dotted line around the item (Like in "Join Channels On Connect" in the above image).

The format to add focus to an item is: /did -f name id.
The format to remove focus from an item is: /did -t name id.

Examples:

To place focus on the "Add Chan" button, type /did -f setup 14
To remove the focus from "Add Chan", type /did -t setup 4


6d. Enable/Disable Items  Back to Top

When you disable an item, it appears grayed out. To remove this gray use the enable command.

To disable an item: /did -b name id
To enable an item (which is disabled): /did -e name id

Examples:

To disable the "Remove Chan" button, in your status window type:
/did -b setup 16

To enable the "Remove Chan" button, in your status window type:
/did -e setup 16

One exception to this command are editboxes, which instead of -b to disable use -m, and they use -n to enable.


6d. Hiding and Showing Items  Back to Top

By hiding items, you can effectively have different dialogs in one dialog window. You can hide the ok button if you only to use the window for display purposes (Like channel stats). Or lets say you have a survey dialog, you could hide every question, and only show the current one - this way you can cut down on the amount of monitor space the dialog takes up. You could also display different sections of a setup screen using the hide commands. Of course these are just a few ideas - I know there are many more.

To hide an item, type /did -h name id
To show an item, type /did -v name id

Examples:

Lets say we don't want the person using the Script Setup dialog to use the "Join Chan" button, in the status window type:
/did -h setup 17

Or if we want to make it visible again, in the status window type:
/did -v setup 17


7. More Appearance changes (Part 2).  Back to Top

Now you ask: "But I want to do these changes automatically, HOW?". This is where the on DIALOG event comes in again. Like I said before, the on DIALOG event reacts when certain things happen with the dialog window. If you wanted to change the appearance of some items when the dialog is first loaded, then use: on *:DIALOG:name:init:0: commands.

This is also how you can insert variables/identifiers into a dialog as the /did and /dialog command both evaluate variables and $identifiers.

This example can be found in setup.mrc:

on *:DIALOG:setup:init:0: {
;setup is the name of the dialog. init is the event that occurs when the dialog is first created. 0 is the default id for when
; an init occurs.
did -a setup 21 < 5
did -a setup 21 5 to 9
did -a setup 21 10 to 14
did -a setup 21 15 to 19
did -a setup 21 20 to 24
did -a setup 21 25 to 29
did -a setup 21 29 to 34
did -a setup 21 34 to 38
did -a setup 21 38 to 42
did -a setup 21 43+
;those did -a's add items to the drop down combo that selects your age.
;this is how you add text to a combo (both normal and drop down).
if (%setup.connect == $null) { set %setup.connect off }
if (%setup.connect == on) { did -c setup 18 }
;this did -c checks the "Join Channels On Connect" if you had previously ticked it
if (%setup.nick != $null) { did -a setup 5 %setup.nick }
;if you had already filled in a nick then this will display it
if (%setup.alt != $null) { did -a setup 7 %setup.alt }
;if you had already filled in a alt. nick then this will display it
if (%setup.real != $null) { did -a setup 9 %setup.real }
;if you had already filled in a real name then this will display it
if (%setup.gender == male) { did -c setup 11 }
; if you selected male as the gender, then did -c setup 11 will put a dot in the male radio box
if (%setup.gender == female) { did -c setup 12 }
; if you selected female as the gender, then did -c setup 12 will put a dot in the female radio box
update.setup
;update.setup is a custom alias that adds all the favorite channels to the fav. channels combo.
}

When someone does a single click (sclick) on an item in a dialog, the dialog event sclick is activated.
The $did identifier stands for the id of the item that was just clicked on.

If the sclick was on a checkbox an easy way to tell what state the checkbox is now in, is to use $did(id).state. If the checkbox is checked, it will return 1, if it is unchecked it will return 0. If the checkbox is intermediate, then it will return 2.

There is an sclick dialog event in setup.mrc

When someone types/removes text in an edit box, the dialog event EDIT is activated. When used in an on DIALOG event, $did(id).text will return the text in the editbox. An example of this can also be found in setup.mrc

There are many other things you can do with the $did identifier. They are listed in /help dialogs.
The setup.mrc file is annotated to help you understand dialogs a bit better.

NOTE: Since mIRC 5.51 you can now insert %variables into certain parts of a dialog table.


8. The $Did Identifier  Back to Top

The did identifier is not the /did command (like $nick is not /nick). As you may already know, the $did identifier is used to return information about certain aspects of the dialog.

It can, among things, return the text you selected in a listbox, the current state of a checkbox or radio, and even the length of text. Its basic format is:

$did(dialog-name,id,N).property

Though when you use this identifier within a dialog event the dialog-name can be omitted.

Below is a list of possible uses, some with examples. All the examples are based upon the Script Setup dialog (/ss). I have put //echo -a in the examples for ease of use purposes but you do not have to use //echo -a as its just an identifier after all.


8a. Am I Invisible?  Back to Top

With the release of mIRC 5.6, the $did identifier now supports two new properties. .visable and .enable. The .visable property will return $true if the specified id is visable (/did -v dname id), if not, it will return $false. The .enable property will return $true if the specified id is enabled (/did -e dname id), if not, it will return $false.

Visable Format:

$did(dialog-name,id).visable

Enable Format:

$did(dialog-name,id).enable


8b. Returning the Text in a Dialog Item  Back to Top

This text can be the name on a button, the n'th word in a listbox or what have you. The basic format is:

$did(dialog-name,id,N).text

N is optional, as some id's like a Close button may only have one line of text. Things like the listbox can have more, thus the N value is needed.

Examples (Using the Script Setup Dialog):

//echo -a $did(setup,5).text

This will return a nickname if it was entered in the edit box (id number 5).

If you wanted to return the text in the auto join combo editbox, you would use:

//echo -a $did(setup,14).text


8c. Returning the Selected Text in a Dialog Item  Back to Top

By selected text, I mean when you select something with a mouse in, say, a listbox or combo.
The format is:

$did(dialog-name,id,$did(dialog-name,id).sel).text

The $did(dialog-name,id).sel returns the number of the selected line. $did().sel is explained futher on in this intro.

Examples:

To return the line number selected in the "AGE" drop down combo, use:

//echo -a $did(setup, 21).sel

Now to return the text that the line holds, use:

//echo -a $did(setup,21,$did(setup,21).sel).text


8d. Returning the Length of Text  Back to Top

To return the length of text a line holds, I use the following format:

$did(dialog-name,id,N).len

When getting the length of an editbox or combo, you should always specify the line number, even if the item is only one line. Of course if you wanted to, you could always just use $len($did(dialog-name,id,N).text) but $did().len takes up less space.

Examples:

To return the length of text in the nickname editbox (id 5) use:

//echo -a $did(setup,5,1).len

To return the length of the 2nd channel in the combo box (id 21) use:

//echo -a $did(setup,21,2).len


8e. Returning the Number Of Lines of Text  Back to Top

To return the number of lines of text in an item such as a listbox, you should use the .lines property, its format is:

$did(dialog-name,id).lines

Examples:

//echo -a $did(setup,14).lines

This will return the number of channels you have in your "auto join on connect" combo.


8f. Returning the State of a Checkbox or Radio  Back to Top

I consider this one of the most important properties for $did. To see if a checkbox is checked, or if a radio has a dot in it, you need to use the .state property. Its format is:

$did(dialog-name,id).state

If the checkbox or radio is filled, then $did(dialog-name,id).state will return 1. If the item is not filled then it will return 0. If the item is not a checkbox or radio then it will return nothing (i.e. == $null).

Examples:

//echo -a $did(setup,11).state

This will return 1 if you checked male as your gender, or 0 if did not.

//echo -a $did(setup,18).state

This will return 1 if you checked the "Join Channels On Connect" checkbox, or 0 if its unchecked.


9. DidTok  Back to Top

Didtok is something new to mIRC 5.7. It consists of an identifier ($didtok) and a command /didtok. As you can probably guess by the name, it is related to Tokens. It is basically an easy way of placing data into a list/combo/editbox and reading the data in the form of a tokenized list. To help explain I will use the Setup Dialog example.

/DidTok:

This identifier is used to put some text into a combo/list/editbox. Each part of the tokenized text will be placed on its own line. So in the setup dialog, instead of having to use

did -a setup 21 < 5
did -a setup 21 5 to 9
did -a setup 21 10 to 14
did -a setup 21 15 to 19
did -a setup 21 20 to 24
did -a setup 21 25 to 29
did -a setup 21 29 to 34
did -a setup 21 34 to 38
did -a setup 21 38 to 42
did -a setup 21 43+
everytime we want to add all those age values to the combo, we can use

/didtok setup 21 46 < 5.5 to 9.10 to 14.15 to 19.20 to 24.25 to 29.29 to 34.34 to 38.38 to 42.43 +

Now let me explain the format for this command. It is:

/didtok dname id C text

The 46 that I used is the ASCII value for a period (.). 21 was the id of the combo to put the text into, and the blue text is the tokenized text. Note how each 'line' in the combo box is actually in this text, but seperated with a period. To use this you really need to learn about tokens first.

$DidTok:

This identifier does the opposite of /didtok. It returns the text in a combo/list/editbox in the form of one line, with each line from the combo seperated by the other lines by a common character (C). Its format is as follows:

$didtok(dname,id,C)

So if we wanted to return the favourite channels in our setup dialog (/ss) we could use the following:

//echo -a $didtok(setup,14,46)

This will return the channels in your 'favourites' combo, each seperated by a period (46 is the ascii value for a period).

See, now you have a fast and easy way of storing and retrieving groups of data without having to use loops or anything complex (*sigh* shame it wasn't with us all along).


10. Dialog Switches  Back to Top

Here are some of the other commands/switches I have not explained yet:

Makes the dialog a desktop dialog: /dialog -d name
Changes the dialogs title: /dialog -t name TITLE
Changes the size of the dialog: /dialog -s name x y w h (good for animations, see dialog-fx alias)
Makes the dialog be onto of all windows: /dialog -o name
Removes the ontop setting: /dialog -n name
Clicks the ok button (thus closing window): /dialog -k name
Clicks the cancel button (thus closing window): /dialog -c name
Makes the dialog become the active window: /dialog -v name
Closes the dialog without activating any events: /dialog -x name
Centers the dialog: /dialog -r name
Minimize or Restore a desktop dialog: /dialog -ie name
Insert text into item: /did -i name id line
Overwrite text in item: /did -o name id line text
Reset the width of a hsbar: /did -z name id


11. Other Dialog Identifiers  Back to Top

This section is made to cover some of the dialog related identifiers.

$didwm(name,id,wildtext,N):
This identifier "returns the number of the line that matches wildtext, with the search starting at line N, N is optional.". So for instance if you wanted to find what line "25" is on in the Setup dialog that we made, we would use something like:

//echo -a $didwm(setup,21,*25*)

It should return 6. I know that this seems like a bad example, as I really can't think of anything good to do with it that /filter could not.

$did().seltext:
This identifier is used to return the selected text in an editbox.
$did().selstart:
This identifier is used to return select start character in editbox line
$did().selend:
This identifier is used to return select start character in editbox line

For the above three identifiers, I can't see much use for them, although if you are using voice commands with you script it could become handy for 'editing' text, e.g. 'delete selected text" or "select text" (Using did -c) etc...

$did().edited:
Depending on if the text in an editbox has changed, this identifier will either return $true (yes it has been changed) or $false (no it hasn't). You can reset this (i.e. so mIRC thinks the text has not changed) by using the /did -j switch.


12. A Closer Look at Dialog Events  Back to Top

This article is designed to expand your knowledge of dialogs. If you don’t know how to make a dialog, I strongly suggest you read over the Introduction To Dialogs first. This article contains information on the on DIALOG event, modal dialogs, dynamic dialog names and general design layout.

I use a few abbreviations which I use when discussing something (But never in any code).

Instead of saying on DIALOG:dname:eventname:id:

I will usually say eventname event e.g. the dclick event instead of on DIALOG:dname:dclick:id: (I’m sure you all know this, but I’m just covering my back here =) )


12a. Event INIT  Back to Top

As a reminder, this event reacts when a dialog is first opened. The dialog becomes ‘visible’ after this event is called (So if you did a long loop in this event it would take a long time for the window to appear, however you can still use /did to change things on the dialog.). The ID you should use is 0.

Why do we use this event? I use it mainly with settings dialogs. When the dialog is opened I need to show what everything in the dialog is set to.

Lets say I had a Talker script. It’s settings dialog lets me choose if I want to talk using the talker all the time, and what my default talking style should be (eg. bold, underline, rainbow, reverse, plain, random). Not only when I sclick on the Save button do I need to store the settings, but when the dialog is opened again I need to show the new/relevant settings. This is where the init event takes place.

Dialog Code:

dialog talker.settings {
title "Talker Settings"
size -1 -1 300 115

box "Default Talker Type",1, 5 5 230 100
combo 2, 15 25 210 90, drop

check "Use talker always",3, 15 60 150 25

button "Save",4, 245 5 50 50, ok
button "Cancel",5, 245 60 50 50, cancel
}

on *:DIALOG:talker.settings:init:0: {
did -a $dname 2 1) None
did -a $dname 2 2) Bold
did -a $dname 2 3) Underline
did -a $dname 2 4) Reverse
did -a $dname 2 5) Rainbow
did -a $dname 2 6) Random
did -c $dname 2 %talker.settings.type
if (%talker.settings.always == 1) did -c $dname 3
}

on *:DIALOG:talker.settings:sclick:4: {
if ($did(2,$did(2).sel).text) set %talker.settings.type $left($did(2,$did(2).sel).text,-1)
set %talker.settings.always $did(3).state
}

So basically the init is used by scripters to load dynamic information into a dialog (or non dynamic text in a listbox, combo, or read only edit). This information doesn’t always have to be just for settings. For example if you made a news ticker like the 7am News Ticker that I made, the init event is used to load the news items into the dialog. The process is quite long, which brings me to another point. If you are doing something that will tie down/lock up mIRC for a few seconds or more its probably a good idea to put in something showing the scripts progress and maybe an ETA - more on this later in the interface section but for now lets just stick to the events themselves.


12b. Event SCLICK  Back to Top

As a reminder, this event reacts when you click once on most items in a dialog. Exceptions to this are the text, edit, and box (And with some combo & list) items.

Why do you use the sclick event? Some people such as myself have picked up a bad habit of using this event to track changes in settings. So when someone for example checks/unchecks the “save window position” check box I would have a sclick event ready to change a variable to the tune of set %var $did(id).state.

Of course in hindsight I really should not do this. What if someone makes a mistake and doesn’t want to use the changes? Well most programs provide a save or done button and a cancel button. So as a general rule it seems to be better to save the settings once the user sclicks on the Save button and not on the individual setting.

You can also use the sclick event to change items in the dialog depending on what the user is doing. By this I mean doing stuff like disabling a button when it cannot be used, or enabling it when it can. Or hiding/unveiling new controls when someone pushes a button. Here are a few examples:

i. You have an autojoin list. Channels are listed in a combo. There is an add and a remove button. The buttons add/remove the selected channel in the combo’s list area. Now if there is no channel selected in the list (which is what happens when the dialog first opens) then you cannot remove the channel (because there is no channel to remove!). Now if we click on a channel we can enable the Remove button. How do we know we clicked on a channel? We use the sclick event of course. ?
ii. You have an away script. It has a simple and an advanced mode (Like ICQ). Normally the dialog would just show the simple stuff like away message, away nick, pager + logger status. Use a push checkbox which to flip between Simple and Advanced mode. When depressed it should put us in advanced mode. We could show & enable (did -v and did -e) the advanced functions like auto deop, logging directory, anti idle, auto away etc… By using a sclick event you can switch between the two modes whenever the user clicks on that push check box.


Another thing that I should mention is that whenever you click on the [x] button to close the dialog, the button with the cancel style is sclicked. So lets say your script saves the window positions whenever the window is closed. The follow buttons would close the dialog: ok & cancel & the [x] button. Now insert some code into the script. On *:DIALOG:dname:sclick:*: if ($istok(1 2,$did,32)) set %xy $dialog($dname).x $dialog($dname).y

Now the above event was scripted assuming that your OK and Cancel buttons were id 1 & 2. But some scripts don’t have a need for a cancel button, so why include one? For that sort of script you could just use a hidden (style: hide cancel) cancel button.


12c. Event DCLICK  Back to Top

As a reminder, this event reacts when you double click on certain items in a dialog. Such items could be some text in a list or combo, an icon etc.

So why do we use this event? The main thing I see useful about this event is it lets you extend the capabilities of the mouse. For my 7am news ticker there are two lists in a dialog. One list contained the news sources I want to view, the other list displays the sources I do not want to view. There is an Add and a Del button to add/remove news sources that I want to view. So if I want to add a source, I select that source then click on the Add button. If I want to remove a source, I select that source then click on the Del button. With the dclick event you can speed up this procedure by double clicking on the source instead of selecting then clicking a button. You will find this sort of feature in most dialogs with editable lists of any sorts (For Windows and not just mIRC). If you are using Netscape to view this page check out the history window (Communicator/Tools/History I think). If you double click on any of the URL’s listed in the window Netscape will go to them. Now imagine if you could not double click? You would probably have to select the item, click on a menu, then click on Open Location or something like that.

I have to admit that I haven’t used this event a lot, and have just recently started to catch on to its goodies ?.


12d. Event EDIT  Back to Top

As a reminder, this event reacts whenever you edit the contents of an edit box (adding and removing text). So every time you hit a key on the keyboard that places text into the editbox or edit section of a combo, this event will react. Lets say you decided to write “xmas” into an editbox. Something similar to below would happen:

[x]
on dialog edit event reacts
[m]
on dialog edit event reacts
[a]
on dialog edit event reacts
[d]
on dialog edit event reacts (Opps we pressed d not s!)
[Backspace]
on dialog edit event reacts
[s]
on dialog edit event reacts
What I am trying to show (and badly at that) is that every time a change - no matter how small - to the text in the edit box occurs the on dialog edit event reacts. That’s every time, not just after you finish typing a word or after you ‘click’ out of the edit box.

So why do we use it? I have a horrible habit of using it to record settings changes (like when someone enters in a new nickname in say an away settings dialog). Not many ideas spring to mind when I think of the edit event, but here are a few:

i. Computer game which uses the dialog as its display. Make the player click in the editbox (or just place the focus on it as soon as the dialog opens and make the editbox out of view so the user doesn’t actually know you are using an editbox) and then press keys to play the game. I’ll try and use Tetris for my example. You control the falling blocks (we could make them icons) - make them go left,right,rotate and go down faster. You could make [a] = left, [d] = right, [s] = down, [w] = rotate. Then you would need to use some code:
on *:DIALOG:tetris-example:edit:id-of-editbox: {
if ($right($did($did).text,1) = a) move.left.by.one
if ($right($did($did).text,1) = d) move.right.by.one
if ($right($did($did).text,1) = s) move.down.by.one
if ($right($did($did).text,1) = w) rotate.clockwise.by.one
did -d $dname $did
;also because edit boxes have limits to the amount of text you can put into them,
;I feel that clearing the editbox after each button would be a good idea.
}
ii. Spell Check as you type? Nick completion as you type? Maybe use it to replace the old tried and true command line. It could sit on top of your old command line and add extra functions like spell check & nc as you type, and maybe auto complete stuff like URL’s, auto complete commands, etc… It could have a button or combo that lets you select the output type (normal text, coloured, rainbow, reverse, op notice, etc…) or for those who don’t like auto completes another smaller dialog could popup when it thinks it could auto complete for you - that way you could stop bad auto completes.


Problems could occur if its a very lengthy piece of code; the script would have to be called after every little change! I haven’t tested with it myself so I’m not sure if there will be a noticeable slowdown.


13. $Dialog & Modal Dialogs  Back to Top

Most of the time I use the $dialog identifier to get info about an already created dialog (Say its x-y co-ords). However it has a really great but often looked over ability. So what can it do? Create a modal dialog.

A modal dialog is used to return information from an id in a dialog (e.g. the text in an editbox). While a modal dialog is opened the script halts/pauses. In order to continue the script you must do whatever is required by the dialog (e.g. push a button or check a box or whatever).
How do you call a modal dialog?

The format is: $dialog(name,table[,parent])

Now an explantion:

Name - Just like with calling a dialog using the /dialog command you need to give that specific dialog a name
Table - Once again like /dialog. You need to specify what table mIRC should use to make the dialog
Parent - This is optional. It defines what window the dialog is ‘attached’ to. 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.

Now there is one last thing to do- in the dialog table you need to say where mIRC should find the stuff it has to return (Remember this is a $identifier and $identifiers return stuff). You need to give this id the result style. This means ONCE the user clicks on the OK button on the dialog the $dialog identifier that called the dialog will RETURN the value of the ITEM/ID that was given the result style.

Now why would we want to use a modal dialog? The most obvious reason I can think of is because we need immediate input for something and don’t want to use the old standard boring $? type identifiers, and making another /dialog means you have to have more dialog events and such to return the information you wanted.

You can only have one id with the result style and you can have multiple items in a dialog. Now lets say you had a $dialog() that called a dialog that had three buttons. The first says “Overwrite”, the second says “Resume” and the third says “Cancel”. Now you can’t give all three buttons the result style, and you need (should) to give one button the ok style (when the ok button is pressed the $dialog() returns the stuff from the result id. So my suggestion is to create a hidden editbox with the result style. When the user sclicks any button use the on DIALOG:dname:sclick:id: did -ra $dname id.of.editbox $did | dialog -k $dname. Where $did is, feel free to put whatever you want the modal dialog to return (I used $did because it will make the dialog return the id of the button pressed).


14. Dynamic Dialog Names  Back to Top

What is this and why should I even be reading about it? It is about not giving a dialog a hard coded name (That is, writing the dialog name in the script so it can only be changed when the user edits the script file). Instead the dialog name is dynamic, thus allowing you to open multiple dialogs. You don’t need to use a dynamic name for every dialog you open. Settings and options dialogs should have a fixed name. Dialogs that show error messages or other types of messages would benefit from a dynamic dialog name - that way they can show more then one error dialog at a time.

The way to decide on what type of dialog name to use is easy: If many dialogs will be called, and each dialog is to display different information (eg, like Getright, it displays multiple windows each about a single download. Each window has the same ‘look & feel’ to it - the same layout) then use dynamic dialog names. If you only need one dialog to be open (eg, a settings or setup dialog) then you don’t need to use dynamic dialog names.

So if you do use dynamic dialog names you need to be careful when dealing with the on DIALOG events, $did /did $dialog & /dialog. If you are using the on DIALOG event then instead of using the dialog name for anything use $dname. $dname returns the name of the dialog that made the event react. See the Error Message section for an example.


15. Designing An Interface  Back to Top

Why do we use dialogs?

For the above reason: its use as an interface from the script to the user. It provides an easy and simple means for the user to interact and use the script. Mostly this interaction is used to change settings for the script (eg. away script, channel protection script) but some others use dialogs to display information that the script has made from the settings it was given (eg. 7am news ticker, second IRC connection channel window, channel stats, userlist editor, etc…). To help the user use the script
So what makes a good interface?

The layout of items in the dialog is very important. You have to decide what the dialog will be used for. Is it for settings? Is it to view results? Is it something completely different? Whatever it is, you need to give the user what they want - the tools that they need. Customization is king.

General layout tips:

  • Keep the dialog Clutter Free and Easy To Use. Don’t go awol with your item placement. If you find there is not enough room for all the items that you wanted to put in it you should consider sectioning off the settings to their own dialogs or tabs. Clutter = confusion for the user. Confusion creates frustration and frustration results in them ditching your script for something easier to use.
  • Keep buttons (and boxes to a certain extent) at the same size as any other button you used in your script. There are a few exceptions to this, such as a large OK or DONE or HELP button - which I usually use as a space filler. Generally I like to use 80 25 or 80 30 as my w/h for the buttons.
  • If your dialog contains tabs then please please please use the dbu option in your table so things actually fit! Also remember if you are placing in “option dbu” into a table that was made without this option you will need to go over the x y w h parts of all the items in your dialog. This is why pre planning would be a good thing to do next time: Do I need to use tabs? Or Could it need tabs at a later point? Yes - well then I had better put “option dbu” in there at the very start.
  • Keep your dialogs uniform. If you use multiple dialogs, give every dialog the same feel/look. So if you used a box with a height of 2 to separate a text item from the rest of the dialog (So it makes the text seem like the heading) in one dialog, do the same for other titles in other dialogs. This point is a larger extension of the Keep Buttons tip. The general idea is that familiar looking dialogs are easier to use first time round, and don’t seem as hard to use. It also makes the script less ‘jumbled up’ when all the dialogs are in uniform - just like a theme script.


Settings Specific Tips:

  • Box off each section of settings (eg. away settings in one box, auto away in another box, user info in yet another box).
  • Clearly label each option. If you have an auto away function which is enabled with a check box then make the text say “Enable Auto Away” or at least “Auto Away”. Don’t just put “Auto” or even no text at all (I realise that this is an extreme example but I can’t think of anything else at the moment!).
  • Disable settings that a user cannot modify (Using the did -b/e command). So if a user doesn’t want to use the Auto Away feature of an away script, disable the controls for it (This is why its a good idea to put boxes around settings). Of course when the user wants to use the Auto Away you just need to enable the controls again.
  • Only save the settings once the user clicks on the OK button.
  • If you need the user to enter a number (say for the time before you set auto away), don’t use an edit box or a massive line of radio buttons or a list box. Instead use a drop down combo. This is good for several reasons: It conserves space on the dialog. It minimises the chance of the user making an error because the user has to choose from a preset list of valid options. If we used an edit box instead, the user could instead of entering a number, enter letters (And we want them to the auto away time not some letters!) which would bring up errors. With the edit box the user could also type in other invalid values like “5mins” “5 minutes” “five minutes” “an hour” etc… Now you could be bothered to write an alias to parse and return the numerical value of this but wouldn’t it be a LOT easier to just let them choose from a pre-made list?
  • Give the user what they want. Once again I have to say Customization is king. Some people call it ‘options overload’. All it is, is letting the user change nearly every aspect of what the script does. We will use the away script as our example again. Now what could the user do to make this script function differently?

  • We should include the standard on/off feature. But what if the person wants to display a message when they go away? What about an option that lets you have a default away nickname (Or even better an editable list of away nicknames). We should include at least an editbox for the away message, an option that sets where the message should be shown (one channel, channels, none) and even a combo that lets you choose if you want to redisplay the message at a later time. What about a CTCP/Private Message/When someone says your name in the channel logger. What about letting you say where the log should be placed. Maybe there could be an option to send a reply to the person who just messaged/ctcp/page etc… it could even be based on user levels. How about an option to enable/disable the pager, and another option to play a sound when you are paged or to open a message window. How about a “come back from away on keypress” option that removes you from away once you start talking again. Next there is the auto away. It needs an enable/disable feature. It could also use a combo to select how long you have to be idle before it sets auto away, another to select the auto away message, another to use verbose (message the channel) mode, another to auto change nicks or not. Maybe the auto away should have an auto deop yourself option as well. I’m sure there are tons more options just for an away script. Like I said before, don’t clutter things. Maybe have an advanced/simple switch (Another example of customization).

    Wow that took a long time to do. However its a lot easier to read when the settings are made accessible by a dialog.


16. Providing Responses When They Are Needed  Back to Top

Now I know I have gone on a bit about “Disabling settings the user cannot modify” which does provide a response to a users actions or in-actions, but what I’m going to talk about now is different. This time its about informing the user what has happened, or what is about to happen. Some Examples:

  • “Please Wait While Script Loads…”
  • “Loading… xxx%”
  • “Cannot Find Required File, Halting Script”
  • “Insufficient Parameters”
  • “You must select an xxxx first”
  • “Someone just paged you”
  • “You are now set away”
  • “You are now set back”
  • “Error… blah blah blah has gone wrong, please do blah blah blah to fix it”
Now these are just a few examples of responses from a script. It is easy to give a response - all you need is the echo command. But why use echo when you can use a dialog? Well its really up to you to decide which fits for your script. If you find that your script is fairly visible to the user (Will the user have to tinker with the script constantly or does it run by itself without much intervention) then maybe a dialog would be better, but if it prefers to ‘run in the background’ then maybe an echo would be better.

So how could you display these messages and more in a dialog? Here are a few suggestions:

For Loading/Please Wait Messages, in particular ones that ‘lock up’ mIRC until the script has finished:

I recommend you use a separate small modeless dialog with these items:

  • A text item to show the user what is loading, and maybe how much has already been loaded (In percent).
  • A long row of icons to use as a percentage bar. In the table itself give each of the icons the hide style so when the dialog first opens the ‘percentage bar’ won’t be full. As the progress of the script increases, make more and more icons visible. If you want an example of this try the 7am News Ticker.
  • A button with the styles “hide ok”. Why hide it? Well why would you use it? Its unlikely that you would use it to close the dialog, especially if the script it is reporting on locks up mIRC. If you think you would use it by all means put it in, but I can’t really see a good reason to do so.
  • If you can figure out the time remaining then by all means you should have another text item to display that information.
Don’t forget to close the dialog as soon as the script has finished doing whatever it was doing!

For frequently occurring messages and/or which are not too important:

I recommend you use a ‘status bar’ at an edge of the existing dialog. You can see programs like Netscape Communicator, WS FTP, McAfee Virus Scan, etc… using this a lot. Its small, out of the way, but still gets the message through. All you need to do is to make a read only edit box. In my email checker I used “read autohs” for the edit style. Just make sure that whatever you put in this ‘status bar’ fits.

For Error Messages:

I recommend you use a separate modeless dialog. It should have the following:

  • Modeless Table, dynamic dialog name
  • Always On Top setting
  • A visible OK button, and if you want a button that opens some sort of help (Like a readme file)
  • Title saying “Error” along with a text item saying “Error” or other appropriate title.
  • An item to display the actual error. It could be a text item or maybe a ready only edit box.
You could also possibly include the following:
  • An icon for the script’s logo
  • A check box that lets you choose not to see this particular error message again
I made a script to simplify it (It's a modification of my previous error message attempts):
dialog scriptname.error {
title "ERROR"
size -1 -1 300 155
box "Error:",1, 5 5 4 105
text "",2, 20 20 230 105
check "Do not &display this error again",3,5 130 170 25
icon 4, 260 120 32 32, mirc32.exe
button "&OK",5,255 5 40 50, ok
button "&Help",6,255 60 40 50, cancel
}

alias scriptname.error {
if ($readini $scriptdirerror.dat noshow $1 == 1) return
var %scriptname.error.dialogname = scriptname.error. [ $+ [ $1 [ $+ [ . [ $+ [ $ticks ] ] ] ] ] ]
dialog -mdo %scriptname.error.dialogname scriptname.error
.timer -m 1 1 did -a %scriptname.error.dialogname 2 $2-
}

on *:DIALOG:scriptname.error.*:sclick:*: {
if ($istok(5 6,$did,32)) writeini $scriptdirerror.dat noshow $gettok($dname,3,46) $did(3).state
if ($did == 6) run scripts-help-file.ext
}

Now to use this error system, whenever an error occurs and you wish to inform the user, use the /scriptname.error alias. Its format is /scriptname.error <error reference number> <error message>. The error reference number is a number that you make up (no order or pattern is needed) to identify the type of error message you want to display. Why? Well so when people click on the “Do not display this error again” check box the script will record the <error reference number> to an ini file. Whenever you try and create an error message again with that reference number the error alias will just ignore it.

So why, you ask, do I have to write out the error message each time? Can’t I just let the error alias read an ini file using the error reference number? In short you could. I don’t because it lets my error messages be more dynamic: I can change the error message to suit the needs of the user. I will use a WWW Downloader script for the example this time. Lets say it has the following message types (Reference numbers included)

1 File not found
2 Cannot connect to server
3 Cannot resolve host
4 File not fully downloaded
5 Unexpected File Size
6 Connection Reset by Peer
Now for the File not found message we can personalize it by saying what file was not found:
/dload.error 1 I’m sorry but I cannot find %dload.file from %dload.server

For the Unexpected File Size error, we can say what file size we expected and what file size we got:
/dload.error 5 The size of the file we downloaded ( $+ %dload.downloaded.size $+ ) does not match the anticipated download size ( $+ %dload.anticipated.size $+ ). Perhaps you should download %dload.url again.

(Please note that I just made up all the variables off the top of my head)


17. Other Dialog Scripts/Examples  Back to Top

Web Search:

This script by PsychoGuy uses a dialog to enter a search query and then open your browser at a search engine of your choice (Search engines supported include Altavista, Yahoo!, InfoSeek and Many More). This script is a good example of dialogs potential. To activate it, once loaded into remotes, type /wwwsearch.
Download Here.

Misc Dialog Aliases:

This selection of aliases by Pasmal allows you do cut down on some repetitive /did coding. Also included is an alias that creates a type of "fx" when a dialog window is opened. An animation if you will.
Download Here.
The first alias, /mdid, has no use anymore since mIRC 5.6 with the same functions added to the built in /did command.

GUI Kick/Ban:

This script by Pasmal uses a dialog to easily customise a kick/ban. Options include: optional kick, optional ban, adjustable ban mask, customisable preset kick reasons,Optional URL. To use it, once loaded into remotes, a new item in your nicklist should appear. Its called Special KB. Click on it and the dialog window will open. You can also change the preset kick reasons and other options in a Special KB menu in your Menubar. Download Here.

Filter Editor:

This script by Pasmal demonstrates some of the new loadbuf and filter abilities, which allow the use of dialogs.
Download Here.

AutoJoin:

This script by Pasmal uses dialogs in an auto join script, which joins certain channels when you connect to an IRC server. The channels do not have to be the same with every server, this is where the dialog comes in, allowing the user to easily customise the script. Once loaded into remotes, a new menu in your Status popups is created, called AutoJoin.
Download Here.


18. Scripting Tip 1: Say to yourself "uniform"  Back to Top

One of the worst things you could possibly do is make many dialogs, each with a different 'style'/format. By using the same type of structure in all your dialogs, it makes it easier for the user to interact with each. An example would be to keep your buttons all the same size, if possible use 25 to 30 as your h value, as this creates a button similar to ones used in many windows applications and dll's.


19. Scripting Tip 2: I need breathing room!  Back to Top

Try and keep items away from each other so that they don't touch. I find that a 5 pixel spacing works well with most items. By doing this you give items a more 'definitive' position - people will know where one button ends and another button starts.

You should take extra care when doing the w h values for the text item, as even though you may not have much text in that item, the item will still take up the w h values. This can cause other items such as editboxes to be partially covered up when selected. Do a test first, fill up the text value with garbage text (e.g. "asdf asdf asdf etc..."), view the dialog, then ajust the w h values until the text ceases to interfer with other items.

The one exception to this breathing room could be boxes. Put two boxes into a dialog, one above the other. Now position the below box so that its top (y) value is that of the bottom of the first box (first boxe's y + h values). You now get what seems like a split box (imho).


20. Scripting Tip 3: Alias out Repetitive Tasks   Back to Top

A common annoyance with dialogs is with the /did command. I waste many bytes up on repeating a did command with a slight variation in the id or switch. It would be nice to have an alias do it for you. I like to use the following aliases:
alias mdid { 
  ;mass /did command 
  ;used for un/checking many id's in one go. 
  ; Can be used for other things. Cannot be used for -a type switches 
  ; (writing text to an id). You need to use /mdid2 for that :) 
  ;format: /mdid -switch dname id1 id2 id3 id4 id5 etc.... 
  SET %hd-mdid-ids $calc($count($3-,$chr(32)) + 1) 
  SET %hd-mdid-ids-count 0 
  :start 
  INC %hd-mdid-ids-count 1 
  did $1 $2 $gettok($3-,%hd-mdid-ids-count,32) 
  IF (%hd-mdid-ids-count < %hd-mdid-ids) { GOTO start } 
} 

alias mdid2 { 
  ;mass /did command 
  ; mdid2 is like /did -switch dialog id1,id2,id3,id3,etc.... TEXT 
  ; you can use this alias to write text to multiple id's 
  ; (i.e. for settings windows). 
  SET %hd-mdid-ids $calc($count($3,$chr(44)) + 1) 
  SET %hd-mdid-ids-count 0 
  :start 
  INC %hd-mdid-ids-count 1 
  did $1 $2 $gettok($3,%hd-mdid-ids-count,44) $4- 
  IF (%hd-mdid-ids-count < %hd-mdid-ids) { GOTO start } 
}
How lucky for me that since mIRC 5.6 lets you have multiple id's in the /did command :( Well there you go all 5.5 users.


21. Scripting Tip 4: Use Wildcards in events   Back to Top

Do you have hundreds of on DIALOG events? If you ask me it wastes valuable space. Try to combine your events, all of each 'sub-event' could go off from one on dialog, or heck if you wanted to every event could go into the one dialog. Examples:
on *:DIALOG:blah:SCLICK:*:{ 
  IF ($did == 1) { echo -s id 1 sclicked! } 
  IF ($did == 2) { echo -s id 2 sclicked! } 
  IF ($did == 3) { echo -s id 3 sclicked! } 
}
or even:
on *:DIALOG:blah:*:*:{ 
  IF ($devent == init) { commands | halt } 
  IF ($devent == sclick) { 
    IF ($did == 1) { echo -s id 1 sclicked! } 
    IF ($did == 2) { echo -s id 2 sclicked! } 
    IF ($did == 3) { echo -s id 3 sclicked! } 
    HALT 
  } 
  IF ($devent == edit) { 
    IF ($did == 4) { SET %var $did(4) } 
    IF ($did == 5) { SET %var $did(5) } 
    HALT 
  } 
}


22. Scripting Tip 5: Icons can be buttons   Back to Top

What? Icons can be buttons? We kinda. When you click on a icon, the sclick event reacts, thus allowing you to do some commands, just like when a button is clicked. What this means is that you could insert several icons into your dialog and have only 1 (which you could ,hide) button. The icons could be pictures of, for example, Green light (go/ok), Red Light(stop/cancel), Yellow question mark (help). I would imagine those who like skins and theme scripts would make good use of this. Imagine clicking on star trek buttons - enterprise or borg or klingon or whatever, it adds something to the atmosphere of the script.


23. Scripting Tip 6: Animations  Back to Top

Still on the icon track, using timers, it is possible to make animations. Perhaps a spinning earth as in Internet Explorer, or a N symbol with a comet streaming by. You could even attempt to do a 3D object, slowing rotating. Or slightly off the track of animations, a progress meter. Ideas on how to do animations:
alias doanimation-dialogname { 
  ;a 4 frame animation perhaps 
  IF (%dialogname.frame) { 
    IF (%dialogname.frame == 1) { did -g id dialogname frame1.bmp } 
    IF (%dialogname.frame == 2) { did -g id dialogname frame2.bmp } 
    IF (%dialogname.frame == 3) { did -g id dialogname frame3.bmp } 
    IF (%dialogname.frame == 4) { 
      did -g id dialogname frame4.bmp 
      set %dialogname.frame 1
      halt
    } 
    INC %dialogname.frame 
    HALT 
  } 
  SET %dialogname.frame 1 
}
Then from the command line, or more likely the on dialog init event, use something similar to:
/timerNAME -m 0 speed-of-animation /doanimation-dialogname
The speed-of-animation can be whatever speed you want (remember I've used the -m switch for miliseconds). I feel that a speed of 700 to 800ms seams ok. Of course depending on your animation you may wish to use another figure.

For that above alias, I could 'compress' it down to something like:

alias doanimation-dialogname { 
  IF (%dialogname.frame) { 
    did -g dname id $scriptdiranimation\anim1\ [ $+ [ %dialog.frame $+ .bmp ] ] 
    IF (%dialogname.frame < LAST-FRAME-NUMBER) { INC %dialogname.frame | HALT } 
  } 
  SET %dialogname.frame 1 
}
By the above alias, you would have files numbered 1.bmp to x.bmp (I use x to represent the last frame number) locatied in
drive:\folder-where-script-is-located\animation\animation-name\.

For example, lets say my script is in c:\mirc\works\, and my animation was called 'emailspin' - which has 15 frames, I would use $scriptdiranimation\emailspin\ [ $+ [ %dialogname.frame $+ .bmp ] ] - and in c:\mirc\works\animation\emailpain\ I would put files named 1.bmp to 15bmp.

Please be aware that this is just another crazy idea of mine, and probably needs a fair bit of tweaking from you :) It is also recomended not to use black backgrounded animations as the flickering is more apparent.


24. Scripting Tip 7: Divide and Conquer   Back to Top

Don't put all your settings for every part of your script onto one dialog.

Some scripts do try and put alot of their settings onto one dialog (e.g. Peace & Protection 4) - notice how long it takes to move from section to section? Well I sure do and thank god for tabs. mIRC 5.61 and above lets you insert tabs into your dialogs. These allow you to easily section off each section of your settings without having to write events to hide/unhide items according to if they are wanted or not.

Just be aware that even though tabs make things less cluttered, you can still over do it :)


25. Conclusion  Back to Top

Well that’s about all I can think of at the moment. Designing dialogs is still a new territory for mIRC scripters. Don’t be afraid to explore different techniques. Be creative & Enjoy :)