Search FAQ

MUSHclient scripting

Description of MUSHclient world function: world.SetBackgroundImage


Name SetBackgroundImage
Type Method
Summary Sets a background image for the output window
Prototype long SetBackgroundImage(BSTR FileName, short Mode);
Description

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.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type. The file name can be the empty string (ie. "") in which case any existing image will be removed.

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

0 = strech 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

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) .


Note: Available in version 4.35 onwards.


Lua example
SetBackgroundImage ("wolf.bmp", 0)
Lua notes
You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0
miniwin.pos_stretch_to_view_with_aspect = 1
miniwin.pos_stretch_to_owner = 2
miniwin.pos_stretch_to_owner_with_aspect = 3
miniwin.pos_top_left = 4
miniwin.pos_top_center = 5
miniwin.pos_top_right = 6
miniwin.pos_center_right = 7
miniwin.pos_bottom_right = 8
miniwin.pos_bottom_center = 9
miniwin.pos_bottom_left = 10
miniwin.pos_center_left = 11
miniwin.pos_center_all = 12
miniwin.pos_tile = 13
Returns eBadParameter: Mode out of range above, or file name less than 5 characters, or file name does not end in .BMP or .PNG

eFileNotFound: File not found

eCouldNotOpenFile: File could not be loaded (perhaps corrupt)

eOK: Success
Introduced in version 4.35

See also ...

Function Description
SetBackgroundColour Sets a background colour for the output window
SetForegroundImage Sets a foreground image for the output window

Search for script function

Enter a word or phrase in the box below to narrow the list down to those that match.

The function name, prototype, summary, and description are searched.

Search for:   

Leave blank to show all functions.


Return codes

Many functions return a "code" which indicates the success or otherwise of the function.

You can view a list of the return codes


Function prototypes

The "prototype" part of each function description lists exactly how the function is called (what arguments, if any, to pass to it).

You can view a list of the data types used in function prototypes


View all functions

[Back]

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.