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.

dialog minimum {
  size 50 50 50 50
  button "OK", 1, 5 5 25 15, ok
}

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

• title
• size
• option
• text
• edit
• button
• check
• radio
• box
• list
• combo
• icon
• tab

• menu
• item

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.

dialog TitleExample {
  title "Example Dialog Window"
  size 50 50 200 50
  button "OK", 1, 85 15 30 25, ok
}

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:

• (none) : Aligned to the Left
• right : Aligned to the Right
• center : Aligned in the Center
• multi : Multi line edit box
• pass : Password field (shows *'s up in place of they keys pressed)
• read : Read Only (Cannot be typed over)
• return :
• hsbar : Horizontal scroll bar
• vsbar : Vertical scroll bar
• autohs : Automatically scroll horizontally (useful for long strings)
• autovs : Automatically scroll vertically

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.

• (none) : Box is on the left hand side of the text
• Left : Box is on the right hand side of the text
• Push : Box is a button which can be pressed in as against a box to be ticked
• 3state : Check box has an On, Off, and Intermediate setting (3 states)

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.

• (none) : Circle is on the left hand side of the text
• Left : Circle is on the right hand side of the text
• Push : Box (as specified by the width/height) is one of a set of radio buttons
• Group : The group style here can be used to group a set of radios together, thus tying their selections together (ie. only one in a group can be selected).

ie.

dialog CheckExample {
  title "Example Dialog Window"
  size 50 50 200 100
  radio "Item 1", 1, 15 5 70 20, group
  radio "Item 2", 2, 15 25 70 20,
  radio "Item 3", 3, 15 45 70 20,
  radio "Push 1", 4, 90 5 80 20, push group
  radio "Push 2", 5, 90 25 80 20, push
  radio "Push 3", 6, 90 45 80 20, push
  button "OK", 7, 85 75 30 20, ok
}

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.

dialog MenuExample {
  title "Example Dialog Window"
  size 50 50 200 100
  menu "&File", 1
  item "&Open", 2
  item "&Save", 3
  item "Save &As", 4
  item break, 5
  item "&Close", 6
  item break, 7
  item "&Exit", 8

  menu "&Edit", 11
  item "&Copy", 12
  item "C&ut", 13

  menu "&Help", 21
  item "&About", 22

  ; now we put the paste under the edit menu

  item "&Paste", 14, 11

  ; and create an options sub-menu

  menu "O&ptions", 31
  menu "&Default Save Options", 32, 31
  menu "Default &Exit Options", 33, 31

  item "&Save on Exit", 40, 33
  item "&Auto-Save", 41, 32
   
  button "OK", 7, 85 45 30 20, ok
}

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:

-f : Set the focus on this item.
-t : Set the button ID as the default button.
-e : Enable a previously disabled item.
-b : Disable an item so it cannot be changed.
-v : Un-Hide an item
-h : hide an item.
-c : Check a check box, or select a radio box, or put the cursor in an edit box etc. or select a line in a combo box or list box.
-u : Un-Check a check box, or unselect a radio box etc.
-k : Keep previously selected/unselected items in a list box.
-r : clear the text in an item (text/combo/list/edit, etc.)
-a : add <text> to a list box, combo box, or a text string.
-d : delete a line from a list or combo box (as per the specified line number)
-i : Insert <text> into a list or combo box at the specified line number
-o : Overwrite the specified line number with the <text>
-g : Change the bitmap or icon of an ICON item.

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.

Dialog AllDialog {
  Title "Example Dialog Window"
  Size -1 -1 300 200

  Button "Ok", 1, 5 175 55 20, ok
  Button "Cancel", 2, 65 175 55 20, cancel

  Box "Box 1", 3, 5 5 140 70
  Box "Box 2", 4, 5 80 140 85
  Box "Box 3", 5, 155 130 140 60

  Radio "Item 1 - Dotted Radio", 6, 10 20 130 15, group
  Radio "Item 2 - Dotted Radio", 7, 10 35 130 15,
  Radio "Item 3 - Dotted Radio", 8, 10 50 130 15,
  Radio "Item 1", 9, 10 140 60 18, group push
  Radio "Item 2", 10, 75 140 60 18, push

  Check "Item 1 - Checkbox", 11, 165 147 120 15
  Check "Item 2 - Checkbox", 12, 165 167 120 15

  Edit "", 13, 10 95 125 22, autohs

  List 14, 155 50 140 80, sort

  Combo 15, 155 10 140 150, drop

  Text "Edit box", 16, 10 120 125 20
  Text "Drop Down Combo Box", 17, 155 32 140 20
  Text "List box", 18, 155 112 140 20
}

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

Alias SetOurDefaultsInOurDialog {
  Did -c AllDialog 6
  Did -c AllDialog 9
  Did -c AllDialog 12
  Did -f AllDialog 13
}

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

Alias AddTextToOurDialog {
  Did -a AllDialog 14 Line 1
  Did -a AllDialog 14 Lone 2
  Did -a AllDialog 14 Line 3
  Did -a AllDialog 15 Line 1
  Did -a AllDialog 15 Line 2
  Did -a AllDialog 15 Lone 3
}

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

Alias DisableAccessToOurDialog {
  Did -b AllDialog 6
  Did -b AllDialog 7
  Did -b AllDialog 8
}

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:

Alias InsertAndOverwriteOurDialog {
  Did -i AllDialog 14 2 Line 2.5
  Did -i AllDialog 15 1 Line 0.5
  Did -o AllDialog 14 3 Line 2
  Did -o AllDialog 15 4 Line 3
}

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

Alias DoItAll {
  SetOurDefaultsInOurDialog 
  AddTextToOurDialog
  DisableAccessToOurDialog
  InsertAndOverwriteOurDialog
}

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:

ON *:DIALOG:AllDialog:INIT:0: {
  DoItAll
}

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:

Alias ConfigureOurDialog {
  did -a AllDialog 9 UPPER
  did -a AllDialog 10 lower
  did -a AllDialog 13 This is default text! Lovely isn't it?
  did -f AllDialog 13
  did -u AllDialog 9
  did -u AllDialog 10
}

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:

ON *:DIALOG:AllDialog:SCLICK:9: did -o AllDialog 13 1 $upper($did(13).text)

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:

ON *:DIALOG:AllDialog:SCLICK:10: did -o AllDialog 13 1 $lower($did(13).text)

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:

ON *:DIALOG:AllDialog:EDIT:13: {
  did -u AllDialog 9
  did -u $dname 10
}

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.