mScriptBox Tutorial
Custom Windows Tutorial

Written by Pasmal
Published with permission.

Table Of Contents

  1. Introduction
  2. Opening and Closing Windows
  3. Putting text onto the @Window
  4. Deleting Text from a @Window
  5. Changing the Text Colour
  6. Altering the appearance of a @Window
  7. Putting Popups onto the @Window
  8. Responding to a Users Interaction with your @Window
  9. First Worked Example
  10. Second Worked Example
  11. Scripting Tip 1: Cache .bmps that you use often
  12. Scripting Tip 2: Always on top is not always best
  13. Scripting Tip 3: Listbox hates word wrap

1. Introduction  Back to Top

Custom Windows were first introduced into mIRC in version 5.0, allowing the scripter to give his script a GUI. (Graphical User Interface). Mastering the basics of custom windows is not hard, but it requires a bit of patience and common sense. Seeing as this is just an introduction to custom windows, the /draw commands will not be included. Perhaps at a later date I will make a file on them.


2. Opening and Closing Windows  Back to Top

Opening a window is easy, the /window command is used to do this. To open a plain window, type /window @window-name. Of course you can add attributes, a full list can be found in /help custom windows.

Opening Window Example:

/window @test

Closing a window is just as easy, use the -c switch in the /window command:

/window -c @test

Of course if you wanted to, you could add an editbox or make the window appear on your taskbar (desktop).
If we wanted to give the window an editbox, use /window -e @window. The text entered into this editbox can be parsed using the

on *:INPUT:@windowname: event
. To make the window be on the desktop, type
/window -d @window
.
You can also set the size and location of the window. To do this you need to specify the x value and the y value - remind you of maths? - (And optionally the width and height values. So the format would be (example):

/window -d @Test 100 50 300 460

The 100 means the window should start 100 (pixels) left from the top left corner of your screen.
The 50 tells mIRC to start the window 50 (pixels) down from the top left.
Where these two points intersect is actually the start position of the window.
The 300 is the width of the window.
The 460 is simply the length of the window.

There are many other options, some of which will be discussed later.


3. Putting text onto the @Window  Back to Top

The /window command is supplemented with several *line commands. The most used one is probably the /aline command. It adds a line of text to the specified window. Format:
/aline -switches/colour @window text
. -switches is optional, a full list of switches can be found in the mIRC Help File.
Colour is also optional - though when stating a colour, use the number for it, not the name (So use 4 instead of red etc...).
Example:
/window @Test
/aline 4 @Test Hello World. 

You will notice the text, Hello World., appears at the bottom of the @window. You can change this by using a listbox. To use a listbox, put the -l switch in the /window command. Example:

/window -l @Test

If you want to put some text in the window, but its too long, then use the word wrap switch,

/aline -p @window text
(Word Wrap does not work with a list box).

There are other methods of putting text onto a @window such as /iline and /rline. /iline will insert the text into the line you specified, pushing the previous text aside. Its format: /iline -switches/colour @window Line-number Text.

Example:

/iline 4 @Test 1 Move Over, world!

That line will put "Move Over, World!" in the first line of @test, pushing the "Hello World" down a line.

The /rline command replaces a specified line. Format:

/rline -switches/colour
@window Line-number Text.

Example:

/rline 4 @Test 1 You have been replaced

That should replace the line "Move Over, World!" with "You have been replaced".


4. Deleting Text from a @Window  Back to Top

This requires another /line - /dline in fact. Its format is:
/dline @window line.number1-optional.line.number2

You can delete just one line (Leave out -optional.line.number2) or delete a whole section of rows (Include -optional.line.number2). So for example, I want to delete the first line, I would type:

/dline @Test 1

But if I wanted to delete a whole row of lines, I would use something like:

/dline @Test 1-3

That would delete lines 1,2 and 3 from @Test.


5. Changing the Text Colour  Back to Top

To change the colour of text already on a @Window, use the /cline command. This command will not change the background colour - just the text (foreground) colour. Its format is: /cline colour @window line-number (You can also use it in channel windows).

Example:

/iline 5 @Test 1 Someone Turn Me Blue, Please
/cline 2 @Test 1


6. Altering the appearance of a @Window  Back to Top

One other thing that you can make custom windows do, is to give them a side box - similar to the nicklist boxes. To do this, you need to use the listbox switch again - but with a variation. Its format is:

/window -lwidth-of-side-box @Window

Example:

/window -l15 @ListBox

Now if you wanted to add text to this side listbox, you need to use the -l switch in your line commands.
Example:

/aline -l  @ListBox Topic1
/iline -l @ListBox 1 Topic1


7. Putting Popups onto the @Window  Back to Top

There are two main ways to do this, the first way is to create a text file, and in this text file, write the popups you wish to use. This text file cannot be in an ini format (n1= n2= etc...). Then when opening a window, add the filename of the text file to the end. Example:

/window @Test popup.txt

Of course there can be other things between @Test and popup.txt, for a full list, consult the help file.

The other way is to use the menu command (/help popup menus). Its format (In remotes):

menu @window {
   popups
}


8. Responding to a Users Interaction with your @Window  Back to Top

There are several events which react when a @window has been used. The main ones are: on OPEN, on CLOSE, and menu. The menu one seams to be the most popular with non picture windows.

To do something when a window opens, use the on OPEN event. Example:

on *:OPEN:@test: aline 4 @Test Welcome

To do something when a window closes, use the on CLOSE event. Example:

on *:CLOSE:@test: echo Goodbye 

The menu event will allow you to do something when a person clicks on a window, and it will also allow you to see what line he clicked on. Its format:

menu @window 
{
  commands
}

For this example, I will use the dclick command. The dclick command reacts when a person double clicks in a @window.

Create a window,

/window -l @Dclick-example
Add some text:

   /aline @Dclick-example Nick
   /aline @Dclick-example Join
   /aline @Dclick-example Part

Then in remotes put:

menu @Dclick-example 
{
  dclick:
  {
    ; $sline will return the nth selected line for a window.
    SET %dclick.text $sline(@Dclick-example,1) 
    IF (%dclick.text == Nick) {
      nick $$?="What Do You Want Your New Nick To Be?"
    }
    IF (%dclick.text == Join) {
      join $$?="Enter Channel To Join"
    }
    IF (%dclick.text == Part) {
       part $$?="Enter Channel To Part" 
} } }

See the possibilities?
You could make a control centre for your script settings, or even emulate a IRC channel. I have used it to allow people to design their own Nick Completors.

$sline is not the only identifier, there are others such as $fline and $line.
$fline uses a wildcard to find a line in a window.
$line returns the specified line.


9. First Worked Example:  Back to Top

This example is of a away message logger. It uses a normal window.
on *:TEXT:*:?: {
  ; this on TEXT responds to any private message
  if ($away == $true) {
    ; this above if checks to see if you are set away.
    if ($window(@away) == $null) {
      ; this above if-then-else checks to see if the window, @away is open. 
      ; If it was, then $window(@away) would  return@away. 
      ; If it was not open, then $window(@away) would return nothing.
      window @away
      ; Opens the window if the window is  not already open
    }
  aline -p @Away [ $+ $time $+ ] < $+ $nick $+ > $1-
  ; puts the message onto the @away window. 
  ; Notice the -p switch so if the message 
  ; is too long, it will be wraped.
  .notice $nick Thank You, your message has been noted.
}


10. Second Worked Example:  Back to Top

This example will log anyone who says a swear word, and display it on a window. You can then double click on his/her nickname in the @window to kick/ban him/her.
on *:TEXT:*:#: {
IF (fuck isin $1-) || (shit isin $1-) || (dick isin $1-) {
  ; if fuck or shit or dick is in the text, script will react
  IF ($window(@swearwords) == $null) {
    ;if the window is not open, script will open in
    window -l @Swearwords
    }
  aline @Swearwords $nick in $chan said: $1-
  ;puts the nickname, channel and what was said onto the window.
  }
} 

menu @Swearwords { dclick: { ;dclick reacts when there was a double click in a @window SET %text $sline(@swearwords,1) ; $sline(@swearwords,1) returns the whole line of the text you double clicked on ban $gettok(%text,3,32) $gettok(%text,1,32) 3 ; You need to use tokens here. Chan is represented by: $gettok(%text,3,32) in this example ; Nick is repersented by: $gettok(%text,1,32) in this example kick $gettok(%text,3,32) $gettok(%text,1,32) Swearing Is Not Allowed in Here! } }

There is another custom window example in the FAQ, in the Whois section.

See also:
/textaligncenter, /textalignright


11. Scripting Tip 1: Cache .bmps that you use often  Back to Top

When using /drawpic, use the flag -c to cache (temporally store) the picture file into mIRC's memory. This will speed up loading and displaying the picture over and over again.
/drawpic -c @picutre 1,1 20,20 weave.bmp
Note: When mIRC is closed, the picture will need to be re-cached when mIRC is restarted


12. Scripting Tip 2: Always on top is not always best  Back to Top

Be careful when deciding to make a @window -o (If on desktop, always on top), as some people prefer to be able to easily switch between @windows and their main mIRC window. The problem is that "-o" prevents a person from doing so, and they have to minimize the @window first, then restore it when they want it again. The only times when you may want or need a "-o" window is when you are doing a script setup, script logo, or an important/system message screen such as "Important: I can't find my popup file!".


13. Scripting Tip 3: Listbox hates word wrap  Back to Top

When making a listbox (-l), you can't word wrap sentences, which renders the /aline -p @window text etc... useless if the text is too large. You have three choices:
  1. Don't worry too much and try to keep the text small.
  2. Use another /*line for the extra text
  3. Don't use a listbox.