Popups

PinballY uses popup boxes to display messages and detailed information. Popup boxes are functionally similar to Windows dialog boxes, but they're visually styled to fit the arcade graphics environment, rather than appearing as separate windows. They're also operable with the basic pin cab buttons rather than requiring a mouse. Popups are mostly limited to information displays, as they don't have a full complement of input controls like Windows dialogs do. PinballY resorts to regular Windows dialogs for anything involving keyboard input or other complex input gestures.

Popup events

When a popup opens or closes, the system fires popupopen and popupclose events (respectively). See PopupEvent for details.

System popups

Here's a list of the system popup display types, with the ID strings reported in the .popupID property of the object returned from mainWindow.getUIMode() while the popup is being displayed.

Custom popups

The mainWindow.showPopup() method lets you create your own completely custom popup dialog, using the same basic display style as the system popups, but with your own custom contents.

The argument to mainWindow.showPopup() is a descriptor object specifying the layout and contents of the popup. The descriptor has the following properties:

Default sizing

If you omit the width and/or height settings in the descriptor, the system figures a default size as follows:

Calculated layout height

In some cases, you might want to adjust your popup's overall display height according to its contents, so that it's just tall enough to display the contents. You can do this as follows:

When the system has to use this "computed" method to determine the height, it calls your drawing function twice. The first time, the call is only to figure out the height, and doesn't do any actual on-screen drawing. There are two important implications of this two-pass process. First, the actual layout height isn't yet known on the first call, since the whole point of the first call is to determine that information. So if you call getSize() on the drawing context, the height returned will be invalid. Second, any drawing you do on this first pass is ignored and won't actually appear on-screen, so it's okay if the exact drawing positions of objects are wrong on this first pass. For example, if you want to align something with the bottom of the popup, you won't be able to get that position right on the first pass because the overall popup height won't be known at that point. The actual drawing occurs on the second pass, at which point the final height is known, so your vertical position calculations will be valid.

Drawing function

The draw property of the popup descriptor object passed to mainWindow.showPopup() lets you specify a Javascript function where you create your own custom internal graphics in the popup area.

The system calls this function after setting up the graphics area for the drawing. The argument to the function is a "drawing context" object, which has methods that let you draw text and graphics into the popup area.

The drawing context has the following methods:

Return value: If necessary, the function must return the desired final height in pixels of the popup. This is needed if you don't specify a height for the popup in the popup descriptor and you don't supply a background image, since in this case the system has no way to figure the required height on its own. To figure the required height, you should keep track of the positions and heights of the objects you draw, and use that to calculate the overall height needed for the contents. Return the result as the return value from the function. The system ignores the returned height if you explicitly specify a height or a background image in the popup descriptor.