Secondary Windows

With the exception of the main playfield window object (mainWindow), all of the system window objects are Secondary Windows. This includes Custom Windows, which are windows that you create through Javascript via mainWindow.createMediaWindow. A Secondary Window is a specialization of the basic Window Object class, which has methods and properties common to all PinballY windows.

"Secondary" windows are so named because PinballY considers the playfield window to be the application's "main" window. It's the window that handles most user interaction, such as keyboard and button input, and appearing in the Windows desktop task bar. All of the other windows are considered subordinate to the main playfield window, and they handle many Windows events by simply forwarding them to the main window.

Class inheritance structure

Properties and methods

Since the Secondary Window class is a subclass of the base window class, a Secondary Window has all of the standard properties and methods common to all windows, as described in Window Objects. It also has some extended functionality of its own.

backgroundScalingMode: This property controls how background images and videos are scaled to fit the window. You can change it by assigning one of the string values below, and you can determine the current mode by comparing it to these string values. It has two possible settings:

• "stretch": This is the default. In stretch mode, the image or video is stretched in both the horizontal and vertical directions to exactly fill the window, without trying to preserve the original media's aspect ratio. This can distort the image by making it look too tall or too wide, but it guarantees that the window area is exactly covered.
• "zoom": In zoom mode, the original aspect ratio of the media is preserved, and the image is scaled to fill either the window's full height or its full width, according to which one allows the full image to fit without any cropping. If this leaves blank areas, they're filled with black, and the image is centered. This mode avoids any geometrical distortion, but it can leave blank black areas if the image doesn't have the same aspect ratio as the window.

pagedImageIndex: This property lets you scroll through "paged" and "indexed" image types, so that you can display different images from the game's collection on command. Reading this property retrieves the index of the media item currently displayed, starting at 0 for the first item in the list. Writing this property changes the display to show the item at the given index. If the new value is past the last available item or less than zero, the system automatically "wraps" to the beginning or end of the list (respectively).

The simplest way to use this property is to increment it to scroll forward to the next image, and decrement it to scroll back to the previous item. Because the system automatically "wraps" the value into the valid range, you can simply increment and decrement the current value without bothering to check bounds.

Note that this method only works with image types. If a window can show both video and image backgrounds, changing the paged image index will always select an image, even if a video is available.

Of the built-in types, this applies to Flyers and Instruction Cards. By the conventions of the HyperPin Media Packs, Flyers are "paged", meaning a single game can have multiple flyer images associated with it, arranged into subfolders of the main Flyers media folder, with names like "Front", "Back", "Inside1", etc. The Instruction Cards are "indexed", meaning that they have numeric suffixes attached to the filenames: "Sinbad (Gottlieb 1978) 1.png", "Sinbad (Gottlieb 1978) 2.png", and so on. If you define your own custom media types, you can use paging and indexing for any type you create that has a similar need for multiple images per game.

(I know it's inconsistent and complicating to have these two different conventions, "Paged" and "Indexed", for essentially the same function. PinballY only uses them because that's how the files are arranged in the widely deployed HyperPin media packs. Since those are the most convenient source of front-end media, I wanted to make them easy to use with PinballY. I didn't want to force everyone to undertake a renaming project every time they imported a media pack.)