Written by Nick Gammon - July 2008. Updated September 2010.
On this page:
SetBackgroundColour function prototype:
long SetBackgroundColour(long Colour);
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.
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.
SetBackgroundImage function prototype:
long SetBackgroundImage(BSTR FileName, short Mode);
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.
|0||Stretch to output view size|
|1||Stretch with aspect ratio|
|2||Strech to owner size|
|3||Stretch with aspect ratio|
|5||Center left-right at top|
|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|
The "stretch" versions expand or contract the image to fit the output window. If you use "with aspect ratio" the image fits exactly top-to-bottom, and may be clipped left-right to preserve the original aspect ratio.
The difference beteween "output view" and "owner size" is that with "output view" (modes 0 and 1) the image will tend to flicker annoyingly if you have automatic resizing of the command window active (as this will make the output window size change, and thus the image size will keep changing) .
SetBackgroundImage ("wolf.bmp", 0)
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.
SetForegroundImage function prototype:
long SetForegroundImage(BSTR FileName, short Mode);
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.
SetForegroundImage ("wolf.bmp", 6)
Obviously if you choose a very large image, or stretch to fit the window, the text arriving from the MUD will be completely invisible.
TextRectangle function prototype:
long TextRectangle(long Left, long Top, long Right, long Bottom, long BorderOffset, long BorderColour, long BorderWidth, long OutsideFillColour, long OutsideFillStyle);
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.
TextRectangle(50, -- left 100, -- top 50 + GetInfo (213) * 80, -- 50 + width for 80 characters -100, -- 100 pixels from the bottom 5, -- BorderOffset, ColourNameToRGB ("gray"), -- BorderColour, 2, -- BorderWidth, ColourNameToRGB ("silver"), -- OutsideFillColour, 8) -- OutsideFillStyle (fine hatch)
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).
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.
GetDeviceCaps function prototype:
long GetDeviceCaps(long Index);
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:
print (GetDeviceCaps (8)) --> 1920 (horizontal width)
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.
t = utils.getfontfamilies () for font in pairs (t) do print (font) end Output Lucida Console Comic Sans MS Georgia Mangal WST_Engl Wingdings Sylfaen Franklin Gothic Medium Courier ... etc ...
GetSysColor function prototype:
long GetSysColor(long Index);
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:
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.
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.
SetCursor function prototype:
long SetCursor(long Cursor);
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:
|10||Arrow - all ways|
|11||(X) cannot do action|
|12||Help (? symbol)|
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.
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.
Gammon Software support
Forum RSS feed ( http://www.gammon.com.au/rss/forum.xml )