Dialog HOWTO

NOTE: This document is also available in a text format at: Dialogs-HOWTO.txt.

This is a short document to help people get the grasp of the /DIALOG command set in mIRC v5.5 and later versions. We will look at all of the different aspects in basic detail, allowing you to get a grasp of how they all work.

First thing we will look at is the dialog table, and how the different items go into it. First thing to mention are those items which are "Required" in the table in order for the dialog to work *AT ALL*. Below is the most basic of tables. Anything less, and the /dialog will not work.

Note: ALL of the table examples in this file can be used via the /dialog -m <dialogname> <table name>. ie. "/dialog -m Minimum minimum".

DIALOG TABLES:-

From this basic dialog table, you can add all sorts of items. The items following are the valid items. We'll explain what they do in more detail later..

And new to 5.71..

All of these items have various flags (options) that are attached to it. Most have a "Text" field which is a label which goes onto the control, all have an X, Y, W, and H values (X position, Y position, Width, Height), most also have an ID field (so it can be distinguished from it's compatriots with the /did command, and associated identifiers), and most have a Style available to it. We will go through all of the options here, and explain what happens with most. A quick note here before we continue, all of the options which use a 'Style', also have the available styles of "Hide", "Group", "Result", and "Disable". Hide hides the control, Disable turns the control off (so it cant be altered), Result is what gets returned when someone clicks the "OK" button, and Group is for use with radio box groupings.

A note about ID values. Each item must be a completely unique Number for in order for the Dialog table to be valid. If you think about it, it is inherently logical. If we had two items with the same ID, how would we tell them apart?

TITLE:

Title is fairly obvious. This is what goes into the title bar of the dialog window. It requires the title text to be surrounded by double quotes ("). ie.

SIZE:

The size option sets the default size of the dialog box. You can however over ride this from the /dialog command by specifying it on the command line. ie. "/dialog -ms TitleExample TitleExample 20 50 200 80". The size option takes the X Y W H values.

OPTION:

The option option sets the default way the units you mention for positioning and sizing are to be interpreted. Whether they are 'pixels' or whether they are 'dbu' (Dialog Base Units, a standard Windows unit). If using dbu, dialog boxes will look the same on everybody's screen, regaurdless of settings. Read the versions.txt for more information.

TEXT:

This puts a text string in a dialog window at the position mentioned in the dialog table, with the string mentioned (surrounded by double quotes (")), and requires an ID value. It can also take a style option. If left off, the text will be defaulted to left aligned, however you can put use the style of Right or Center.

EDIT:

An edit box is an integral part of most dialog boxes. It allows for text to be entered into a field and handled at a later stage. It requires a Text value to be used (however, you can use "" (a null string) for no text), an ID, X Y W H, and takes a Style. The styles here can be a little tricky. Their functions are listed below:

BUTTON:

A button is the easiest way to get something done. The text passed onto the button (as shown in the previous examples) gets placed on the button it's self (centered). The ID is so it can be manipulated at a later stage (or captured with the ON DIALOG event), and it has 3 style options: Ok, Cancel, and Default. OK makes the dialog close, and values get passed to the parent (if used with the $dialog() form). Cancel closes the dialog, and takes no further action, whilst Default is for you to capture, and manipulate as you desire.

CHECK:

A Check box is very useful for setting things in an ON or OFF state. The text accosiated with these check boxes is put to the right of the text. The width is how wide the text will go (as with the Edit and Text items). If this is too low, the text will be cut off at the specified width.

RADIO:

The radio boxes (dots) are most used where a setup can have multiple set values. They can be a little tricky to use, but can be very useful. The text option is the same as the Check item, as with the ID number. The style however can be very important. We will mention one of the global styles here.

ie.

BOX:

This draws those lovely boxes around controls. The Text option is what is written in the top left hand corner of the border. The Width and height are very important to get right, otherwise they will cross over other controls and create a mess. There are only the default styles for this item. The ID must not be forgotten either.

LIST:

This makes a list box. Whilst items cannot be put into the list box at this time, you must get the size right otherwise you will not be able to see any records (this might however be the desired effect). A height of approximately 20-25 is required. The sort style sorts the items in the list box, whilst the extsel allows for Multiple Selections in the list box (disabled by default).

COMBO:

This makes a combo box. The same height rule that applies with list applies to this control as well. Items are once again added later with the /did command. The styles are somewhat strange however. The default style is 'Edit' (creates an edit box with a list box underneath it for selections). The drop style creates a single line drop down box which drops down the Height mentioned. As with all controls, you can mix and match the controls (so you can create an edit-able drop down box!).

ICON:

This allows you to insert a bitmap, or icon into your dialog control. This takes an ID, X Y W H, and a Filename (either a quoted long file name ("C:\Program files\some.bmp") or a standard short file name (C:\Progra~1\some.bmp)). This also takes an Index value for the index number of an icon in an icon library (such as a DLL or a EXE).

TAB:

This allows you to create those window tab sheets that windows uses in situations like the Dial-Up-Networking configuration. Only one set of tabs can be put on any given dialog box (Sucky limitation if you ask me!). The first instance of the tab line in your dialog table takes a text name, an ID number, and the dimensions of the control. Any successive tab reference just takes a text value, and an ID number. To use tabs, you enter a style of 'tab ' for your control (button, listbox etc.). The simplest example of this is in the mIRC help file. I suggest you copy and paste this into a remote script.

MENU:

This allows you to create pull-down menus in mIRC Dialog boxes. They are relatively simple to use, and the help file explains them reasonably well. What you have to be careful of is the inheritance orders of the items, and even the sub-menu's.

ITEM:

This allows you to create menu items under the 'menu' type items. You have the choice of saying which 'menu' id they fall under, otherwise they will just be put under the last mentioned menuid. An example is below.

ITEM:

THE /DID COMMAND:-

The /did command is command you use to manipulate all of the items you can put into a /dialog box. The different switches are as follows:

If you are using a 3 state check box, using -cu (check and uncheck simultaneously) will make the check box at it's 3rd state.

The /did command allows us to manipulate the items we have put into our dialog table (all except the Size and Title items. These two however can be over ridden from the command line with /dialog -s and /dialog -t switches respectively). Using the switches mentioned above, we can do almost anything to our dialog boxes.

First, we will create a dialog box with one of every item, so you can get the feel of how to put together and control the appearance of a dialog box.

Now we will create an alias to set the default options and default focuses:

Now we will add some text to the list boxes, and drop boxes:

Now we will disable some functions of which we don't need access too:

Now we will insert some more lines into the drop down and list boxes. We will also overwrite some of the spelling mistakes of the addins we did earlier:

And now one tidy little alias so we can get it all done in one hit!

Now that we have learned how to use most of the functions /did can perform, we will move on to how to create more interactive dialog boxes, using the ON *:DIALOG: event.

The ON DIALOG event catches such things as Single Clicks, Double Clicks, Editing of Edit boxes and Combo boxes, and the initilisation of the dialog it's self!

First we will take a look at the Initilisation event. For our dialog above, we can use an event which looks like this:

By typing /DrawOurDialog, we will have our dialog box come up, and all of our settings created with a simple hit of the enter key! Easy huh?

Now we will look at our push styled Radio Buttons. We already know that the selection changes automatically when we press the other option (the button beside it), but what we will do now is some actions on those clicks. First, let us change the text on the buttons to something more meaningful, and add some default text to our Edit box:

The ON DIALOG event requires a number of things to work. To do what we want this one to do, we will use the following line:

This will trigger whenever someone presses the UPPER button. We will get it to convert all the text in the edit box to Upper Case. Now we will couple this with a matching event for our lower button:

Notice how we use the $did() identifier to get the text in our edit box? The $did() identifier can be used to get a great deal of useful information about the contents, and state of our dialog box. Also notice how both the UPPER and lower buttons are unpressed ? The two /did -u lines in the ConfigureOurDialog unpress both of them. Now we will match that activity when we type something in the Edit Box:

Here I have substituted our Dialog Boxes name with the identifier $dname. This points to the dialog box which triggered our event. This is very useful if you are using alot of similar dialog boxes, and you want the same thing to happen for the same action.