MediaSyncEvent

This Event subclass represents media synchronization events, which occur when a window loads new media due to a new game selection, after returning from a launched game session, or for any other reason. Media synchronization events let you intervene in the media loading process (for example, you could change the image that a window loads, or prevent loading a particular video), and also can be used to coordinate your own custom displays in a window (using Drawing Layers, for example) with background media changes.

The basic media sync event type comes in the following subtypes:

• mediasyncbegin: Fires when something happens that requires the window to check to see if new media should be loaded. This is the first step in the media sync process, so at this point the system hasn't decided whether or not new media will actually be required, and hasn't searched for the appropriate media files yet. This event can be canceled (using preventDefault()), which tells the window to skip the rest of the process, keeping the current background media unchanged.
• mediasyncload: Fires after a mediasyncbegin event if the window determines that new media should be loaded. At this point, the window has resolved the media files, so the filenames are included in the event properties. You can intervene by changing the filenames in the event object, or by canceling the event entirely (using preventDefault()), which prevents any new media loading.

  Immediately after your event handler returns, assuming you don't cancel the event, the system will attempt to load the media file. Assuming this is successful, the on-screen transition effect (cross-fading from the old background media to the new background) will start almost immediately. A mediasyncend event will follow when the transition effect completes, or if an error occurs trying to load the media file.

• mediasyncend: Fires when the sync process has finished, which is either just after the media file has been successfully loaded and the cross-fade transition effect has finished, or after the media load attempt failed or was canceled. The disposition property of the event object indicates which of these outcomes occurred.

A mediasyncbegin event is always fired at the start of the process, and a mediasyncend always fires at the end of the process, no matter what the outcome. You can count on these events being paired, so you can use the "done" phase to unwind any global state that you set up in the "begin" or "load" phase.

Media sync events are fired on the window object representing the window that's loading a new background. When a new game is selected, the system visits each window in sequence and loads its media, so the media sync events will occur in that same sequence.

Properties

This event type has all of the standard event properties and methods (see the Event class), plus the following:

• game: A GameInfo object representing the current game, which determines which media files will be loaded. If no game is selected, this is null. This is provided in all phases of the event.
• disposition: For mediasyncend only, this is a string indicating the outcome of the media sync attempt:
  • "success": the new media file was loaded successfully
  • "error": an error occurred loading the new media file
  • "skip": the system decided that it wasn't necessary after all to load new media: no game was selected, or the correct media file was already being displayed, or Javascript canceled the process
• video: A string giving the name of the video file that the system has chosen to use as the new background, or null if no video file for the game could be resolved. This is only provided for the mediasyncload event. You can change this value to override the system's choice of file with your own.
• image: A string giving the name of the image file that the system has chosen, or null if no image file for the game could be resolved. This is only provided for the mediasyncload event. You can change this value to override the system's choice of file with your own.
• defaultVideo: A string with the name of default video file to use as the background, as a fallback to the video and image files. This is only provided for the mediasyncload event. You can change this value to override the system's choice of file with your own.
• defaultImage: A string with the name of default image file to use as the background, as a fallback to the video and image files. This is only provided for the mediasyncload event. You can change this value to override the system's choice of file with your own.

All of the file properties (image, video, defaultImage, defaultVideo) contain complete Windows filenames, with drive letter, folder path, and extension. If you change any of these, you must also use the same absolute path format, since PinballY will simply pass these strings to Windows directly to attempt to open the named files. You can set any of these to null to remove it from consideration.

The reason that multiple file properties are present is that the system treats these four as a series of back-up options if any of them can't be found or if any errors occur trying to load them. The system visits the files in the following order, stopping at the first one that successfully loads:

• video
• image
• defaultVideo
• defaultImage

If video is missing (meaning that the system couldn't find any video files in the Media folder for the game), or if an error occurs when PinballY attempts to load the video file (e.g., the file doesn't contain valid video data, or can't be opened for some reason), the system moves on to image as the next best candidate. If no image file was found for the game, or an error occurs loading the file, PinballY next tries defaultVideo, and finally defaultImage.

Note that video playback can be disabled by the user as an option setting. When videos are disabled, the video and defaultVideo properties won't be present, since the system doesn't consider those as candidates for the background media.