mScriptBox Tutorial
Picture Window Tutorial

Written by Kloony
Published with permission.

Table Of Contents

  1. Introduction
  2. Open and closing
  3. Picwins work differently
  4. Mouse events
  5. Usefull Identifiers
  6. Determining sizes of Text and Pictures
  7. Example 1: Progress bar
  8. Example 2: Simple Paint Program
  9. Conclusion

1. Introduction  Back to Top

On the next few paragraphs I would like to give you an Intrucduction to Picture Windows. This tutorial will cover some essentials along with some basic identifiers you can use.


2. Open and closing  Back to Top

I'll start with closing them first, mainly coz I'm lazy and its the easiest one to explain. The command is


/window -c @windowname.

Not much more to understand about that part. Opening windows is done with The /window command also, however it requires The -p switch. The Basic command being /window -p @windowname, however you have soo many options to play around with It'd take forever to go into great detail I'll just give examples of the main functions.

To make a desktop window you need to add a -d switch (and some optional size parameters). Giving you /window -pd @windowname [x y w h] eg. /window -pd @Paint 150 100 300 400 (This would make a window 150 pixels from the left of the screen 100 pixels down, 300 across and 400 high. You can add editboxes by adding the -e switch, or set the window on top of the others using the -o switch also -C (notice its a capital) centers the window when first created. (There are Plenty of other switches hopefully I'll get to the most important ones in this tutorial later) eg.


/window -pdC @progress 1 1 300 130 
This creates a Centered desktop, picture window called @Progress


3. Picwins work differently  Back to Top

Picture windows aren't like conventional windows which means You can't /echo to them or just add text to them with a simple command. You generally have to supply at least an x and a y co-ordinate. To change what we have in our window we use the range of /draw commands.

Firstly I'll do a brief description of the common switches, this being i,h,n and r. The -i switch draws in inverse mode, The -h switch highlites the windows icon if it's minimized, The -n switch stops the display from being updated straight away - this allows you to make lots of changes yet still make the display update look instant-, and -r simply tell mIRC that you want to use and RGB value (RGB stands for red, green, blue and is a specific value for a certain mixture of r, g and b. Slightly over 16 000 000 combinations 255(red) * 255(green) * 255(blue))

Now, to change the base colour of our window we can use the /drawfill command, the base command is /drawfill @windowname colour colour x y. You can use all the i,h,h and r switches plus an additional -s switch, which lets you fill with a border (if You specify different colours).


/drawfill -r @progress $rgb(face) $rgb(face) 1 1 
;this simply fills our window @progress with a dialog type base background 

The /drawfill command doesn't work so well in Windows that already have been drawn in. In which case you can use the /drawrect command.

The /drawrect command is more versatile than you expect when you first look at it, it can draw rectangles (obviously ;)) both filled and lined aswell as elipses (egg shapey thingo) by the command /drawrect @window colour size x y w h [x2 y2 w2 h2 ...] (the x2 y2.. are for additional rectangles with the same command). The -f switch fills the rectangle, -e makes an elipse, -c makes a focus rectangle and -d makes a rounded rectangle (along with an additional width and height to determine the 'roundness' giving you parms - x y w1 h1 w2 h2) ;since /drawrect has so many uses I'll give example of a few...


/drawrect @progress 0 1 10 45 275 30
;draws a simple white outline of a rectangle

/drawrect -e @progress 0 1 10 45 275 30 
;draws an oval in the same place at the rectangle earlier

/drawrect -d @progress 0 1 10 45 275 30 7 7
;draw a rectangle with the out 7 pixles in the corners rounded
;all of these can be easily filled by simply adding a -f switch

You can also draw lines and dots (which have almost the same format) that being /drawdot @window colour size x y [x2 y2 ...] and /drawline @window colour size x1 y1 x2 y2 [x3 y3 ...] (they both have the i,h.n and r switches) again the [bracketed] parameters are for aditional dots/lines. (they have no additional parameters just i,h,n and r).


;these are reletivley simple commands
/drawdot @progress 4 5 10 45
;draws a large red dot centered at our previous rectangle's top left corner

/drawline @progress 4 1 10 45 285 45
;draws a thin red line across the top of our previous rectangle

Now for drawing text to your picture window, with the /drawtext comand. The general form is /drawtext @window colour x y Text. You can use the -p switch to use control codes in the text (colours/bolds ect...), -b is used for setting a background colour (requires an additional colour parameter), -o bolds the text, -c clips the text to fit you specified width and height (specified after the x and y). You can also specify a fontname and size. The total command is in the form /drawtext [-hnrpboc] @window color [color] [fontname fontsize] x y [w h] text (with the [bracketed] parameters being optional).


/drawtext @progress 1 "ms sans serif" 20 72 15 Progress indicator: 
;draws simple black black text on our window @progress bar starting at point (72,15)

You can save your picture window to a .bmp file by typing /drawsave @window filename. You can 're-load' the picture in a sense By using /drawpic. The /drawpic command allows you to draw a .bmp|.png|.jpg Picture in a window (also stretch it). The base command is /drawpic @window x y [w h] filename. You can draw the picture at the same time in multiple places (even different sized), just specifu more x y [w h] values. with the -t switch you can make 'transparent' parts of the pic a certain rgb value (the colour is chosen directly after the window name), -c caches the picture (quicker load time if you want to draw it again), and -l tiles the picture in the width, height you specify. There are a few others but they are not widely used and don't need to be clarified.


/drawpic @progress 0 0 $findfile(c:\,*.bmp,1) 
;this draws the 1st picture in the top left of @progress ($findfile is there so it finds a valid bmp) 

/drawpic -sl @progress 0 0 300 130 $findfile(c:\,*.bmp,1) 
;this tiles/streches the first available .bmp file on c: to @progress


4. Mouse events  Back to Top

Mouse events are the highlight of picture windows, they are what makes them so customisable and versitile. You can return the position of the mouse in the window, whether certain buttons are pressed. You can perform actions When the mouse is single clicked, double clicked, right clicked, when the mouse button is released, when the mouse leaves the picture window area. These events are called in a similar way to Popup menus, in a menu definition: ie.


menu @window {
  Sclick:echo -s This is a single click event
  dclick:echo -s This is a double click event
  uclick:echo -s This is mouse release event 
  rclick:echo -s This single right-click event 
  leave:echo -s This is the window your mouse just left: $leftwin 
  mouse: echo -s you moved the mouse
  ;(if you simple have the mouse: as above Your status will get 
  ;bombarded with the message as fore each different position (x,y) you 
  ;move the mouse to, you get the message)
} 


5. Usefull Identifiers  Back to Top

The are many useful identifiers, I'll try to describe them as best I can Then we can get down to the examples, $mouse isn't just useful, its virtually required to make a functional picture @window. So I'll start with $mouse.

$mouse()
To return information about where you mouse is and what its doing you need $mouse, It has 9 properties: win, x, y, mx, my, dx, dy, key. Some are self explanatory others may not be. Win returns the name of the window; .x .y | .mx .my | .dx .dy | all return the position of the mouse, in the picture window, the mirc main window, and the desktop respectively. The .key property will be discussed later but its for determining if a button is pressed.
$inrect()
Another identifier that makes Like a whole lot easier Is $inrect, Its used to find out if a certain x y co-ordinate are in a specific rectangle. (Its a boolean expression obviously ie. $true/$false) The base syntax is:

$inrect(x,y,x,y,w,h) which positively confusing especially for a first look. To explain it I'll use a simple example for a window called @window, and I want to test if I have sclicked in the first 20 pixels squared of the window.


Menu @window { 
  sclick: if ($inrect($mouse.x,$mouse.y,0,0,20,20) == $true) { 
  echo -s You clicked at $mouse.x $mouse.y In the 20 by 20 square at the top left of @window 
  }
} 

It might look complicated still but at least its easier to explain $mouse.x and $mouse.y are the x,y points you are testing, 0 0, are the x,y, positions of the top left of your rectangle. and the 20,20 are the width and height of your rectangle.

$inpoly()
You can check Odd shapes also with just as much ease by using $inpoly.
The general syntax is $inpoly(x,y,x1,y1,x2,y2...,xn,yn) (this hopefully looks less complicated now you know $inrect). It just checks if the point x,y Is in the polygon defined by the numbered x,y co-ordinates. In our previous example our inpoly command would look something like this:


Menu @window {
  dclick: if ($inpoly($mouse.x,$mouse.y,0,0,0,20,20,20,20,0) == $true) {
             echo -s You double-clicked at $mouse.x $mouse.y 
             echo -s In the 20 by 20 square/polygon at the top left of @window 
          }
}

As you can see this way takes a lot more actual mathematics ;) (*quietly vomits*) well instead of a simple width and height we've had to define each point of our rectangle in terms of x and y. You can have more than four points obviously which makes it so much easier to stray away from squareness ;)

$rgb()
Don't worry you don't have to memorise teh 16 000 000+ colour combinations ;) You have $rgb(Nr,Ng,Nb). This lets you find the RGB value for Nr amount of red (0-255), Ng amount of green (0-255) and Nb amount of blue (0-255).


6. Determining sizes of Text and pictures  Back to Top

You can find the $width() and $height() of any text at any size and font. They are self-explanitory from the syntax:

$width(text,font name,fontsize,[Bold,Control])
if bold, or control, are Non-zero then text is bold or counts control codes respectively. (leave them out if you don't need them) and $height(text,font name,fontsize).

You can use these in any /draw command (technically you can use it anywhere ;) although apparently not when defining a dialog table) Getting the size of a pic is through the use of an aptly named identifier $pic ;) It is in the form of $pic(filename) and has three simple properties: .size, .width, and .height. It can also be used anywhere (not picture window specific)


7. Example 1: Progress Bar  Back to Top

Now that we have our commands, events and identifiers mapped out we can move on to our first example spript, A Progress indicator/bar. The coding is filled with comments so I'll let it explain itself.

Download the example script here.


8. Example 2: Simple Paint Program  Back to Top

Phew we're done. You're not getting away that easily I didn't show you how to make buttons yet or to use any mouse events ;).

Well how about a simple paint program to get familiar with those aspects. You'll notice I use a lot of aliases this helps by increacing the functionality (and decreacing my typing time. Hey, what can I say I'm lazy :P) (This isn't as heavily commented so I'll interupt where necesary).

Download the example script here.


9. Conclusion  Back to Top

You've now seen some of the very cool things you can do with Picture Windows. There are many, many more ideas to be discovered than could ever possibly be covered in an entire web site; the only limitation you have is your own imagination. Have fun...