# 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

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.

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

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