[Home] [Downloads] [Search] [Help/forum]

Graphics helper functions

Written by Nick Gammon - July 2008. Updated September 2010.

On this page:

See also:

Set output window background colour

SetBackgroundColour function prototype:

This changes the default background colour of the output window. This is intended to be used to make "mood" changes to the output window. For example, if you are currently playing in a watery zone, the background colour could change from black to a deep blue.

You simply specify the RGB code for the desired colour, or the constant 0xFFFFFFFF to indicate to use the default behaviour. Normally MUSHclient draws the background in ANSI colour "normal black". If you have set a colour, then any time the background colour for text would have been "normal black", then the background is not drawn and thus the background colour you chose is allowed to stay.

Example of setting background colour

You should exercise caution in your choice of background colour. Too bright a background and the normal white text will be virtually invisible. Probably you want quite a dark colour, as in the example above.

Set output window background image

SetBackgroundImage function prototype:

This sets a background image for output window. The text in the output window is drawn on top of this. If the image does not completely fill the window, the background colour is visible beneath it.

Example of setting a background image

You should exercise caution in your choice of background image. Only a subdued image will let the text appear over it without being distracting. Alternatively a subtle logo in the top right-hand corner might be acceptable.

Set output window foreground image

SetForegroundImage function prototype:

This sets a foreground image for output window. The text in the output window is drawn under this. The function arguments are the same as for SetBackgroundImage described above so they won't be repeated here.

Example of setting a foreground image

Obviously if you choose a very large image, or stretch to fit the window, the text arriving from the MUD will be completely invisible.

Set MUD output text rectangle size

TextRectangle function prototype:

This reduces the rectangle in which normal MUD output is displayed, from the entire output window, to the subset specified. This can be used to make a "desktop effect" where you have room on all sides for miniwindows to be placed. A border can be drawn at the edge of the rectangle to make it obvious where the text ends, to help in resizing the window. The text is clipped to be within the text rectangle.

Example of making a text rectangle

Obviously you don't want too small a rectangle, or it will be hard or impossible to see the MUD output. You could use 'GetInfo (213) * 80' to calculate a suitable width (output font width, multiplied by 80, to allow for 80 columns).

Image and window drawing order

Now that MUSHclient is drawing a whole heap of foreground and background images, it is helpful to see what order they are done in. The graphic below explains it:

You can have both foreground and background window images, plus multiple miniwindows, both behind and in front of the MUD text. The miniwindows themselves are drawn in ascending alphabetical order by miniwindow name, thus the ones drawn later will be on top, as they are drawn on top of the ones earlier down the list.

Get display device capabilities

GetDeviceCaps function prototype:

This asks Windows for the capability of your output screen. The index specifies which attribute you are interested in, and it returns a number corresponding to that. Some useful indices are as follows:

Example of getting device capabilities

Get available fonts

This lets you find the names of all the fonts installed on your current system. It is a Lua-only script function. The intention here is for scripts to decide if a font is available, before setting the output or command window to use that font.

Example of getting fonts

Get system colours

GetSysColor function prototype:

This function directly calls GetSysColor in Windows. It returns the colour used by various items as currently configured in Windows, based on the selector (Index), as follows:

Schedule output window redraw

Redraw function prototype:

This function schedules the output window to be redrawn. You should call this after changing the contents of miniwindows. The function WindowShow calls Redraw automatically. Note that the main window is not actually redrawn at this point, however it is scheduled for redraw next time through the main event loop.

Force output window redraw

Repaint function prototype:

This function forces the output window to be redrawn. This should not normally be called, as the window will be redrawn at the appropriate time through the main "event loop". Unnecessary calls to Repaint will slow the program down. However for "animation" situations (like moving an image over a map) there may be times when you actually want the window redrawn, between "frames". In this case, you could call Repaint to force an immediate redraw.

Change the shape of the mouse pointer

SetCursor function prototype:

This function lets you change the shape of the cursor during a hotspot drag operation.

The argument a number which indicates what shape the mouse pointer is to take when as follows:

ValuePurposeLua symbol
-1 No cursor miniwin.cursor_none
0 Arrow miniwin.cursor_arrow
1 Hand miniwin.cursor_hand
2 I-beam miniwin.cursor_ibeam
3 + symbol miniwin.cursor_plus
4 Wait (hour-glass) miniwin.cursor_wait
5 Up arrow miniwin.cursor_up
6 Arrow nw-se miniwin.cursor_nw_se_arrow
7 Arrow ne-sw miniwin.cursor_ne_sw_arrow
8 Arrow e-w miniwin.cursor_ew_arrow
9 Arrow n-s miniwin.cursor_ns_arrow
10 Arrow - all ways miniwin.cursor_both_arrow
11 (X) cannot do action miniwin.cursor_x
12 Help (? symbol) miniwin.cursor_help

This operation is only effective when the mouse is "captured" - basically after a mouse-down but before the corresponding mouse-up. Otherwise the cursor is likely to be promptly restored by MUSHclient's cursor management code, for example to an I-beam cursor if it moves over text, or to the designated cursor if it moves over miniwindow hotspots.

Tips for avoiding flicker

MUSHclient maintains all miniwindows in offscreen bitmaps, so you can draw to them any way you want to (for example, draw a wall and then punch holes in it for doors). This will not cause any visible flicker.

However, to avoid visible flicker, all drawing should be done in a single script call. Thus anything that cannot be done immediately should be cached until the window can be drawn in a single script call. For example:


Draw an inventory window by updating the miniwindow as each line of inventory arrives. This will cause flicker because the inventory will gradually "creep down" the window.


Draw an inventory window by caching each line of inventory as it arrives. For example, in Lua you could use table.insert to add the inventory line to a table. Then when the inventory has completely arrived, simply traverse the table, drawing each item in quick succession, in a single script call.

Other pages about miniwindows


Written by Nick Gammon - 5K

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( http://www.gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Internet Contents Rating Association (ICRA) - 2K]    [Hosted at HostDash]