Miniwindows in MUSHclient - Introduction

Written by Nick Gammon - July 2008.

See also:

Introduction

For many years now MUSHclient has been purely a "text" client, after all, it is designed to work with text-based MUD games.

However over recent years there have been various requests for:

The ability to display images, such as maps.
Cursor addressing (to show stuff anywhere on the screen)
Status-bar windows (eg. to show HP and Mana in bar-graph format)
Other subsidiary windows (eg. chats, inventory, quests)

So far, some of these have been possible by using separate, "dummy world" windows, but this has been a bit unwieldy, particularly if you want to resize or move things around.

The new additions make it possible to have "floating miniwindows" which appear on top of, or to the side of, the main output window. As these are part of the main window, if you move or resize the main window, the extra windows automatically move with it.

An example of some miniwindows in operation:

General characteristics of miniwindows

Miniwindows are created and manipulated purely by script commands, generally intended to be inside plugins.
You can have any number of miniwindows at once. Each one has a name which is used by the script to refer to it. Your only limitation would be available screen space, and your imagination.
Miniwindows do not necessarily have to be visible. Thus you could be adding to a miniwindow (such as your inventory) during combat, when you might not want to see it. Later, you can show it, and its most recent contents will be displayed.
Each miniwindow is rectangular in shape, and can be any size you like. They start off with a background colour you specify, however you can change that partly or completely by drawing in the window.
You can position the miniwindows whereever you want to, however there are various auto-positioning options, such as top left corner, middle of top of window, top right corner, and so on.
Miniwindows are drawn in an off-screen buffer (bitmap), and then automatically copied to the main output window, whenever the output window is redrawn. This provides fast, flicker-free operation.
Miniwindows can be drawn either above or below the normal output window text. Normally for a floating-style window you would want it above (and thus the text scrolls underneath it), however for some background information you can choose to have the text scroll over the miniwindow.
Miniwindows can capture mouse-down, mouse-move, and mouse-up events, in order to react to the player clicking on them. This can be used to implement hyperlinks, buttons, and "mouse-over" help.
Miniwindows can be resized and moved as desired.
Miniwindows can be drawn transparently, so that they can have holes in them, wherever the transparent colour appears.

What can you draw in miniwindows?

Basically almost all of the low-level Windows graphics drawing operations are available. These include the following. In the screenshots the grid has been drawn to make it clearer the dimensions of each item, it would not normally be there.

Straight lines
Arcs (partial circles)
Polygons (shapes with multiple sides, such as an arrow shape)
Rectangles (including squares)
Ellipses (including circles)
Bezier curves

(The red dots are the Bezier control points, shown purely for illustrative purposes)
Rounded rectangles
Chords

(A chord is basically an ellipse with part chopped off)
Pies

(A pie is basically an ellipse with part removed, with lines drawn from the centre)
Bitmap images (ie. from a xxx.bmp file)
Image tile-sets - that is, choosing part of an image which consists of lots of small sub-images. For example, a large image with lots of trees, houses, rocks etc. in it.
Text using any font you choose, in any size or style. Any number of fonts can be used in the same window. Unicode may be used if you supply UTF-8 strings (with a suitable font).
Flood filling an area with a colour

All operations are pixel-addressable - that is, you can do them anywhere in the miniwindow, to the nearest pixel.

All operations give you control over the colour - so you can have blue lines, or a red box filled with green, with purple text in it.

Most of the above operations allow you to specify a line width, line colour, and line style (including "no line").

Many operations allow you to specify a fill colour and style (including "no fill"). Some allow you to fill with a bitmap pattern (constructed from an 8 x 8 pixel pattern). The bitmap pattern can be used to make "wave" or "grass" effects.

Some operations (rectangle, rounded rectangle, ellipse) allow you to fill the object with an image, either a 8 by 8 pixel monochrome pattern that you can specify, or from an external xxx.bmp file.

Items can overlap, as much as you want. Whatever is drawn later, will be on top of whatever was drawn earlier.

Hotspots

In order to allow you to interact with the miniwindows, you can designate hotspots (really, "hot rectangles"). When the mouse is moved inside these designated areas (of which there can be any number per miniwindow), script functions in your plugin can be called. These functions can handle:

Mouse over the hotspot - this lets you pop up an "information box" if you want to, or make the area change colour to indicate it is important in some way. For example, a hyperlink might change colour.
Mouse moved away from a hotspot - this lets you cancel the information box, or change the colour back to what it normally is.
Mouse down in a hotspot - this is to "prime" a mouse-click. Most Windows programs, if you watch carefully, do not actually do anything important on a mouse-down - they do it on the corresponding mouse-up. However a mouse-down event is a good time to redraw a button in a "pushed" state, as a visual cue that letting the mouse go will have some effect.
Mouse up in a hotspot - generally this is when you react to the mouse click. For example, on a hyperlink, you do the hyperlinked action. On a button, you carry out the button-press action.
Mouse-down cancel - this is when they have clicked on a hotspot, but moved the mouse away, and let go, effectively cancelling the mouse down. Here is where you might redraw the button in a non-pressed state, to indicate the button is no longer pressed.

In addition, you can specify tooltip text, which automatically appears if the mouse hovers over a hotspot, after a short delay. This can be used to provide short help messages.

Other pages about miniwindows

Comments to: Gammon Software support
Forum RSS feed ( http://www.gammon.com.au/rss/forum.xml )