Window Objects

PinballY provides a set of pre-defined Javascript objects corresponding to the on-screen windows:

• mainWindow: the main playfield window
• backglassWindow: the backglass window
• dmdWindow: the dot-matrix display (score area) window
• topperWindow: the "topper" window (an extra window that can display custom graphics for pin cab systems that have a third monitor in the backbox, in addition to the more typical backglass and DMD windows)
• instCardWindow: a dedicated window that displays the instruction cards for the current game, for pin cab systems with an extra monitor in the apron area
• Custom Windows: windows you create through Javascript code, using mainWindow.createMediaWindow()

These objects let you get and set information about the windows from Javascript code. In addition, the mainWindow object serves as the Event Target for most user input events, such as keyboard keys and joystick buttons.

With the exception of mainWindow, all of the windows are instances of the Secondary Window class, which has some additional methods and properties that can be used with those windows.

Common properties and methods

All of the UI window objects define the properties and methods listed below. Some of the windows add their own additional features beyond this basic set; see the individual window descriptions for details.

window.borderlessMode: Gets or sets the window's current "borderless" display status. Reading the property returns a boolean (true/false) indicating whether the window is currently in borderless mode: true means that it's bordlerless, which means that the normal Windows caption bar and sizing borders are hidden, so that only the graphic content area of the window is visible. Set this property to true to hide the borders; set it to false to show normal Windows frame controls.

window.createDrawingLayer(zIndex): Creates a custom drawing layer in the window. A drawing layer is a graphics layer where you can display videos, image files, or draw custom graphics. The graphics can use alpha transparency to layer images on top of other layers.

zIndex is an integer that specifies the new layer's position in the "stack" of drawing layers. This can be from 0 to the the maximum integer value of 2147483647. If you think about each drawing layer as a piece of transparency film, and imagine that the layers are arranged in a stack, one on top of another, then the Z index gives the position in the stack. The layer with the highest Z index is on top of the stack, so its graphics will be drawn in front of the layer with the next lower Z index.

For most of the windows, all of the custom drawing layers created through scripting are drawn in front of the background image or video that the system displays in the window. The main playfield window is the exception, because it uses several different layers of its own, and it allows you to interleave custom scripting layers with the built-in layers. This is described in more detail in layer ordering in the mainWindow object section.

window.fullScreenMode: Gets or sets the current full-screen status of the window. Reading this property returns a boolean (true/false) indicating whether or not the window is currently in full-screen mode. Setting it to true switches the window to full-screen mode; setting it to false switches the window to normal windowed mode.

See Drawing Layers for more information on how to use a drawing layer once you create one.

window.hwndFrame: a read-only property returning an HWND object representing the system window handle for the frame of the window. The frame is the main UI window, which includes the caption bar and sizing borders.

Some of the windows, such as the DMD and instruction card window, are normally shown in "borderless" mode, with no frame controls. Despite this, all of the windows use the same frame/view layered structure, whether or not the frame decorations are visible. The frame window for a borderless window will have the same size and location as its view content window, but it will nonetheless still exist as a distinct operating system window from the view, and will thus have its own separate window handle. Even though this doesn't matter to the user, it allows the program to internally treat all of the windows uniformly, since they have the same frame/view structure.

hwndFrame retrieves the raw system handle for the window, so you can use it with Windows API functions via the DLL Import facility. Direct Windows API calls are generally safe for retrieving information about the window, but it's not advisable to make changes to the window through the system APIs (e.g., repositioning it, changing its title or other properties), since the main PinballY program won't necessarily be notified of such changes. This could cause unexpected behavior. Instead, you should only make changes through the Javascript methods described in this section, since those will coordinate properly with the main program.

window.hwndView: a read-only property returning an HWND object representing the system window handle for the "view" portion of the window. This is the interior graphics content area of the window, which excludes the caption and borders. All of the Direct3D drawing for the graphical content is done in this window.

From the user's perspective, this is simply the interior of the same window as the frame, but it's actually implemented as a separate operating system object, thus the need for this separate property. In Windows terms, this is a "child" window of the frame window.

As with the frame handle, this is the raw system window handle, which you can use in direct calls to Windows API functions. However, it's not advisable to make changes to the window though system APIs, since the main PinballY code won't necessarily be notified of such changes.

window.name: a string giving the name of the window ("playfield", "backglass", "dmd", "instCard", "topper"). This is mostly for debugging purposes; if you have a reference to one of the window objects and need to identify it programmatically, it's better to compare the reference to the named window objects (mainWindow, etc), as that insulates you from any future changes to the names.

window.removeDrawingLayer(layer): Removes a custom drawing layer that you previously created via createDrawingLayer(). layer is the drawing layer object that was returned from createDrawingLayer() when you created the layer. This deletes the layer and removes any on-screen video or graphics being displayed in the layer. After calling this method, the layer is no longer valid, so any attempts to load media or draw graphics will be ignored.

window.setWindowState(state): Minimizes, maximizes, or restores the window position. state can be one of the following string values:

• "min" = minimize the window
• "max" = maximize the window
• "restore" = restore the window from minimized or maximized state

If the window is currently in full-screen mode, it will automatically be returned to normal windowed mode first.

window.setWindowPos(afterWindow, x, y, width, height, flags): Sets any combination of the window's position, size, and Z order. First, if the window is currently in full-screen mode, it's switched to normal windowed mode. Then, the standard Windows API function SetWindowPos() is called with the provided arguments.

afterWindow is a window handle (an HWND object) that's used to determine the new Z order, by moving this window immediately behind the specified window. This is ignored if the SWP_NOZORDER bit (0x0004) is included in the flags value. The following special values can be set to set absolute positions:

• HWND.BOTTOM = place the window behind all other windows on the screen
• HWND.NOTOPMOST = if this window currently has the "topmost" attribute, make it non-topmost by moving it behind the last topmost window. There's no effect if this isn't currently a topmost window.
• HWND.TOP = move the window to the front of the Z order
• HWND.TOPMOST = give the window the "topmost" attribute, and move it ahead of all other windows. The window will continue to stay in front of all other non-topmost windows even when deactivated.

x, y give the new top left position of the window, in screen pixel coordinates, relative to the desktop origin. This is the same coordinate system that hwnd.getWindowPos() returns in the windowRect rectangle. x and y are ignored if the SWP_NOMOVE bit (0x0002) is included in flags.

width, height give the new window size, in pixels. This is the size of the outer frame area of the window, which is the same size reported in the windowRect rectangle returned by hwnd.getWindowPos(). These values are ignored if the SWP_NOSIZE bit (0x0001) is included in flags.

flags is a bitwise combination (with the "|" operator) of the following flags bits:

• SWP_NOACTIVATE (0x0010) prevents the window from being newly activated. If this isn't provided, the function normally activates the window a side effect. This flag leaves the activation status unchanged. (Note that it doesn't deactivate a window that's already activated; it simply prevents any change in activation status.)
• SWP_NOMOVE (0x0002) tells the function to ignore the new position (x, y) arguments and leave the window at its current top left coordinate position.
• SWP_NOOWNERZORDER (0x0200) prevents any effects on the "owner" window's Z order. All of the secondary PinballY windows (backglass, DMD, etc) are owned by the main playfield window, so without this flag, the playfield window will be moved to a new Z order along with the secondary window. This flag lets you move the windows independently, without affecting the playfield window's Z order.
• SWP_NOSIZE (0x0001) tells the function to ignore the new size (width, height) arguments and leave the window's size unchanged.
• SWP_NOZORDER (0x0004) tells the function to ignore the hwndAfter argument and leaves the window's Z order unchanged.

window.showWindow(show): Shows or hides the window. show is a boolean (true/false) specifying whether to show (true) or hide (false) the window.