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

MUSHclient scripting

Description of MUSHclient world function: world.SetForegroundImage

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

View list of data type meanings


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

Note: Available in version 4.35 onwards.

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

View list of return code meanings

Introduced in version 4.35

See also ...

Function Description
SetBackgroundColour Sets a background colour for the output window
SetBackgroundImage Sets a background 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


Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

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


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

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

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]