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


Script function


Read about scripting




Creates a miniwindow


long WindowCreate(BSTR WindowName, long Left, long Top, long Width, long Height, short Position, long Flags, long BackgroundColour);

View list of data type meanings


This creates (or re-creates) a miniwindow of the given name. It is not initially shown so it will be invisible until you call WindowShow. If there is an existing, visible, window of that name, then it will be marked invisible, so you will need to call WindowShow to make it visible again.

If you want to change the size of a miniwindow you don't need to delete it, simply call WindowCreate again, which causes it to be recreated in the new location / size. However you can call WindowDelete to completely delete an existing miniwindow.

Alternatively, call WindowResize which resizes the window, keeping all fonts, images and hotspots.

It is reasonable to use WindowCreate to create a very small window (eg. 0 x 0 pixels) simply to load images or fonts into it. Thus you can find out font sizes, in order to calculate what size window needs to be re-created, so it is the correct size to hold a particular piece of text.

If you call WindowCreate on an existing window then:

* The existing offscreen image will be discarded, and the memory it used freed.

* A new offscreen image will be created, using the new dimensions. Thus you can use WindowCreate to resize a window. For example, you might do this for an inventory window, if you get more inventory.

* The image will be cleared to the background colour you specify.

* Any hotspots you added are removed - unless flag 0x10 is set (create_keep_hotspots), see below. The assumption is that if you are starting drawing from scratch, any hotspot items will probably appear in a different place.

* The window's "show" flag is set to false. Thus you need to call WindowShow before it will become visible.


WindowName - the name we are calling it - needed for all subsequent operations on this miniwindow. We suggest you use GetPluginID () to get a unique name for this window. If you plan to use more than one window in a plugin, simply append "A", "B", etc. to the plugin ID. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Width, Height - the width and height of the window, in pixels. The example window above is 200, 200. The minimum size is 0, 0.

These are required, and lock in the size of the window for subsequent drawing operations. Any attempts to draw outside these boundaries will be clipped.

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

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

Positions 0 to 3 probably aren't that useful (they are also used for loading background images), and position 13 (tile) would probably not be used often either. However you might use these if you set the "draw underneath" flag described below, so that a subtle window could appear under main output window.

The corner positions (4, 6, 8, 10) always put the miniwindow in that corner, and 12 (centre all) always puts the window dead-centre of the main output window.

The other positions (5, 7, 9, 11) are used for centering the window between the corners. MUSHclient tries to fit the miniwindow exactly in the middle between any corner windows. Also, if more than one window is designated as centered on that side (eg., the right side) it tries to fit them all in, evenly spaced.

If the centered windows can't all be fitted, some are temporarily hidden until they do, in order to avoid overlaps.

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

WARNING: If you set the "draw underneath" flag then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events.

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow.

WARNING: If you set the "ignore mouse" flag then you cannot use hotspots, as mouse clicks and movement will not be detected.

BackgroundColour - this is the RGB code for the colour that the window is initially filled with, and is used when doing transparent drawing, as described above.

For more information, see:


Available in MUSHclient version 4.34 onwards.

Lua example

win = "win_" .. GetPluginID ()  -- get a unique name
WindowCreate (win, 0, 0, 200, 200, miniwin.pos_center_all, 0, ColourNameToRGB("white"))  -- create window
WindowShow (win,  true)  -- show it

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

You can use the following constants for the flags:

miniwin.create_underneath = 1
miniwin.create_absolute_location = 2
miniwin.create_transparent = 4
miniwin.create_ignore_mouse = 8
miniwin.create_keep_hotspots = 16

Return value

eNoNameSpecified - miniwindow name must be specified
eBadParameter - width or height less than zero
eOK - success

View list of return code meanings

See Also ...




(GetDeviceCaps) Gets screen device capabilities
(SetCursor) Changes the shape of the mouse cursor
(TextRectangle) Specifies the size of the rectangle in which text is displayed in the output window.
(WindowAddHotspot) Adds a hotspot to a miniwindow
(WindowArc) Draws an arc in a miniwindow
(WindowBezier) Draws a B├ęzier curve in a miniwindow
(WindowBlendImage) Blends an image into a miniwindow, using a specified blending mode
(WindowCircleOp) Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow
(WindowCreateImage) Creates an image in a miniwindow
(WindowDelete) Deletes a miniwindow
(WindowDeleteAllHotspots) Deletes all hotspots from a miniwindow
(WindowDeleteHotspot) Deletes a hotspot from a miniwindow
(WindowDragHandler) Adds a drag handler to a miniwindow hotspot
(WindowDrawImage) Draws an image into a miniwindow
(WindowDrawImageAlpha) Draws an image into a miniwindow respecting the alpha channel
(WindowFilter) Performs a filtering operation over part of the miniwindow.
(WindowFont) Loads a font into a miniwindow
(WindowFontInfo) Returns information about a font
(WindowFontList) Lists all fonts loaded into a miniwindow
(WindowGetImageAlpha) Draws the alpha channel of an image into a miniwindow
(WindowGetPixel) Gets the colour of a single pixel in a miniwindow
(WindowGradient) Draws a gradient in a rectangle
(WindowHotspotInfo) Returns information about a hotspot
(WindowHotspotList) Lists all hotspots installed into a miniwindow
(WindowHotspotTooltip) Changes the tooltip text for a hotspot in a miniwindow
(WindowImageFromWindow) Creates an image from another miniwindow
(WindowImageInfo) Returns information about an image
(WindowImageList) Lists all images installed into a miniwindow
(WindowImageOp) Draws an ellipse, rectangle or round rectangle, filled with an image
(WindowInfo) Returns information about a miniwindow
(WindowLine) Draws a line in a miniwindow
(WindowList) Lists all miniwindows
(WindowLoadImage) Loads an image into a miniwindow from a disk file
(WindowMenu) Creates a pop-up menu inside a miniwindow
(WindowMergeImageAlpha) Merges an image into a miniwindow based on an alpha mask
(WindowMoveHotspot) Moves a hotspot in a miniwindow
(WindowPolygon) Draws a polygon in a miniwindow
(WindowPosition) Moves a miniwindow
(WindowRectOp) Draws a rectangle in a miniwindow
(WindowResize) Resizes a miniwindow
(WindowScrollwheelHandler) Adds a scroll-wheel handler to a miniwindow hotspot
(WindowSetPixel) Sets a single pixel in a miniwindow to the specified colour
(WindowSetZOrder) Sets the Z-Order for a miniwindow
(WindowShow) Shows or hides a miniwindow
(WindowText) Draws text into a miniwindow
(WindowTextWidth) Calculates the width of text in a miniwindow
(WindowTransformImage) Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing
(WindowWrite) Writes the contents of a miniwindow to disk as a graphics file

(Help topic: function=WindowCreate)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Search for:   

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]