MUSHclient scripting

This creates (or re-creates) a miniwindow of the given name. It is not initially shown so it will be invisible until you call WindowShow. If there is an existing, visible, window of that name, then it will be marked invisible, so you will need to call WindowShow to make it visible again.

If you want to change the size of a miniwindow you don't need to delete it, simply call WindowCreate again, which causes it to be recreated in the new location / size. However you can call WindowDelete to completely delete an existing miniwindow.

Alternatively, call WindowResize which resizes the window, keeping all fonts, images and hotspots.

It is reasonable to use WindowCreate to create a very small window (eg. 0 x 0 pixels) simply to load images or fonts into it. Thus you can find out font sizes, in order to calculate what size window needs to be re-created, so it is the correct size to hold a particular piece of text.

If you call WindowCreate on an existing window then:

* The existing offscreen image will be discarded, and the memory it used freed.

* A new offscreen image will be created, using the new dimensions. Thus you can use WindowCreate to resize a window. For example, you might do this for an inventory window, if you get more inventory.

* The image will be cleared to the background colour you specify.

* Any hotspots you added are removed - unless flag 0x10 is set (create_keep_hotspots), see below. The assumption is that if you are starting drawing from scratch, any hotspot items will probably appear in a different place.

* The window's "show" flag is set to false. Thus you need to call WindowShow before it will become visible.

PARAMETERS:

WindowName - the name we are calling it - needed for all subsequent operations on this miniwindow. We suggest you use GetPluginID () to get a unique name for this window. If you plan to use more than one window in a plugin, simply append "A", "B", etc. to the plugin ID. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Width, Height - the width and height of the window, in pixels. The example window above is 200, 200. The minimum size is 0, 0.

These are required, and lock in the size of the window for subsequent drawing operations. Any attempts to draw outside these boundaries will be clipped.

Position - a number indicating where you want the window positioned on the screen. Whenever the screen is resized or redrawn the contents of the window are drawn in the requested position:

0 = stretch to output view size
1 = stretch with aspect ratio
2 = strech to owner size
3 = stretch with aspect ratio
4 = top left
5 = center left-right at top
6 = top right
7 = on right, center top-bottom
8 = on right, at bottom
9 = center left-right at bottom
10 = on left, at bottom
11 = on left, center top-bottom
12 = centre all
13 = tile

Positions 0 to 3 probably aren't that useful (they are also used for loading background images), and position 13 (tile) would probably not be used often either. However you might use these if you set the "draw underneath" flag described below, so that a subtle window could appear under main output window.

The corner positions (4, 6, 8, 10) always put the miniwindow in that corner, and 12 (centre all) always puts the window dead-centre of the main output window.

The other positions (5, 7, 9, 11) are used for centering the window between the corners. MUSHclient tries to fit the miniwindow exactly in the middle between any corner windows. Also, if more than one window is designated as centered on that side (eg., the right side) it tries to fit them all in, evenly spaced.

If the centered windows can't all be fitted, some are temporarily hidden until they do, in order to avoid overlaps.

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

WARNING: If you set the "draw underneath" flag then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events.

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow.


WARNING: If you set the "ignore mouse" flag then you cannot use hotspots, as mouse clicks and movement will not be detected.


BackgroundColour - this is the RGB code for the colour that the window is initially filled with, and is used when doing transparent drawing, as described above.


For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Note: Available in version 4.34 onwards.