world.SetForegroundImage

MUSHclient script function (Method) — introduced in version 4.35

Sets a foreground image for the output window

Prototype

long SetForegroundImage(BSTR FileName, short Mode);

Data type meanings

Description

This sets a foreground image for output window. The text in the output window is drawn under this.

With "stretching" or "tiling" modes, the text from the MUD will not be visible.

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

Lua example

SetForegroundImage ("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

Return value

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

Return code meanings

Related topic

Utilities

See also