WindowCreate
Script function

world.WindowCreate

DOC_scripting Read about scripting

Type

Method

Summary

Creates a miniwindow

Prototype

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

DOC_data_types View list of data type meanings

Description

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.

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

PARAMETERS:

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

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.

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:

http://www.gammon.com.au/mushclient/mw_creation.htm

Lua example

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


Return value

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


DOC_errors View list of return code meanings

See Also ...

Topic

DOC_miniwindows Mini Windows

Functions

FNC_GetDeviceCaps GetDeviceCaps (Gets screen device capabilities)
FNC_SetCursor SetCursor (Changes the shape of the mouse cursor)
FNC_TextRectangle TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)
FNC_WindowAddHotspot WindowAddHotspot (Adds a hotspot to a miniwindow)
FNC_WindowArc WindowArc (Draws an arc in a miniwindow)
FNC_WindowBezier WindowBezier (Draws a Bézier curve in a miniwindow)
FNC_WindowBlendImage WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)
FNC_WindowCircleOp WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)
FNC_WindowCreateImage WindowCreateImage (Creates an image in a miniwindow)
FNC_WindowDelete WindowDelete (Deletes a miniwindow)
FNC_WindowDeleteAllHotspots WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)
FNC_WindowDeleteHotspot WindowDeleteHotspot (Deletes a hotspot from a miniwindow)
FNC_WindowDragHandler WindowDragHandler (Adds a drag handler to a miniwindow hotspot)
FNC_WindowDrawImage WindowDrawImage (Draws an image into a miniwindow)
FNC_WindowDrawImageAlpha WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)
FNC_WindowFilter WindowFilter (Performs a filtering operation over part of the miniwindow.)
FNC_WindowFont WindowFont (Loads a font into a miniwindow)
FNC_WindowFontInfo WindowFontInfo (Returns information about a font)
FNC_WindowFontList WindowFontList (Lists all fonts loaded into a miniwindow)
FNC_WindowGetPixel WindowGetPixel (Gets the colour of a single pixel in a miniwindow)
FNC_WindowGradient WindowGradient (Draws a gradient in a rectangle)
FNC_WindowHotspotInfo WindowHotspotInfo (Returns information about a hotspot)
FNC_WindowHotspotList WindowHotspotList (Lists all hotspots installed into a miniwindow)
FNC_WindowHotspotTooltip WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)
FNC_WindowImageFromWindow WindowImageFromWindow (Creates an image from another miniwindow)
FNC_WindowImageInfo WindowImageInfo (Returns information about an image)
FNC_WindowImageList WindowImageList (Lists all images installed into a miniwindow)
FNC_WindowImageOp WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)
FNC_WindowInfo WindowInfo (Returns information about a miniwindow)
FNC_WindowLine WindowLine (Draws a line in a miniwindow)
FNC_WindowList WindowList (Lists all miniwindows)
FNC_WindowLoadImage WindowLoadImage (Loads an image into a miniwindow from a disk file)
FNC_WindowMenu WindowMenu (Creates a pop-up menu inside a miniwindow)
FNC_WindowMergeImageAlpha WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)
FNC_WindowPolygon WindowPolygon (Draws a polygon in a miniwindow)
FNC_WindowPosition WindowPosition (Moves a miniwindow)
FNC_WindowRectOp WindowRectOp (Draws a rectangle in a miniwindow)
FNC_WindowSetPixel WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)
FNC_WindowShow WindowShow (Shows or hides a miniwindow)
FNC_WindowText WindowText (Draws text into a miniwindow)
FNC_WindowTextWidth WindowTextWidth (Calculates the width of text in a miniwindow)
FNC_WindowWrite WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowCreate)

DOC_contents Documentation contents page