Icons and Messages

In order to interact with the skin, the jukebox sends status messages to the skin and can receive control messages from icons mapped to locations on the screen.

When a message is received that matches the Action setting of an icon, that icon's OnImage is displayed, and when the negative version of the message is received, the icon reverts to its OffImage. More than one icon can have the same Action, but each icon can only have one Action. If no OnImage is defined, the OffImage will appear down and to the right as if "pressed" in like a button. If no OffImage is specified, the background image in the area specified by the icon is used.

An Action may contain any of the button definitions listed above. When a button definition is used, the icon will move to the OnImage state for a tenth of a second, and then return to the OffImage state. If the icon is marked as Clickable, it will send the button command as well as receive it.

In addition to button messages, there are several state messages that can be assigned as actions. State messages should not be marked as Clickable, as they are not commands. State messages are often used to activate "lights" on the jukebox, indicating credits being available, that a song is paused, that radio mode is turned on, etc. This is done by putting an image of a turned-on lamp for the icon's OnImage and of an unlit lamp for the OffImage.

The state messages are:


MSG_FILTERED

Activated when a filter is in place; deactivated when the filter is cleared.


MSG_POPULAR

Activated when the Most Popular list is shown; deactivated when the Song Queue display is restored.


MSG_CREDITS

Activated when one or more credits are available; deactivated when no credits are remaining. When the jukebox is set to not require credits, this message is always active.


MSG_SONGSTART

Activated when a song is playing; deactivated when the song finishes.


MSG_SONGPAUSE

Activate when the Pause feature is activated; deactivated when play is resumed.


MSG_START

Activated when the jukebox is started. Note that this message is never deactivated, so you cannot use this message to trigger shutdown events, as the shutdown happens too quickly for the jukebox to respond to.


MSG_START_SKIN

Activated when a new skin starts. This is the default action, and can be used to essentially apply "decals" to the jukebox without having to edit the skin background image. Note that this message is never deactivated, so you cannot use this message to trigger skin shutdown events, as the shutdown happens too quickly for the jukebox to respond to.


MSG_ISDOS

Activated for DOS, deactivated for Windows. Useful if you wanted to show a different decal depending on which version is running.


MSG_RADIO

Activated when RadioMode is started; deactivated when RadioMode is exited.
See also: BTN_RADIO, RadioMode.
MSG_LOOP

Activated when LoopMode is started; deactivated when LoopMode is exited.
See also: BTN_LOOP, LoopMode.
MSG_PLAYSTIMULATOR

Activated when the PlayStimulator has been enabled; deactivated when the PlayStimulator has been disabled.
See also: BTN_PLAYSTIMULATOR, PlayStimulator.
MSG_SCREENSAVER

Activated when the screen saver is activated; deactivated when the screen saver has been dismissed.


MSG_MUTE

Activated when the Mute function is used; deactivated when normal volume is restored. This message is only sent if the actual mute function is used, not if the volume is simply turned down to minimum.
See also: BTN_MUTE.
MSG_NOCREDITS

Activated when the user attempts to select a song when credits are required and no credits are available. Deactivated two seconds later.


MSG_INVALID

Activated when the user attempts to select an empty song slot. Deactivated two seconds later.


MSG_DUPSONG

Activated when a song is selected that is already in the queue if AllowDuplicatesInQueue is disabled in jukebox.ini. Deactivated two seconds later.


MSG_FREEPLAY

Activated or deactivated at jukebox startup depending on the RequireCredits setting in jukebox.ini, and activated or deactivated as appropriate if BTN_FREEPLAY is toggled.
See also: BTN_FREEPLAY.
MSG_IDLE

Activated when no songs are playing, paused, or queued. This message is sent after the post-song delay on the last song, and it is deactivated before the pre-song delay. It is not activated between queued songs, only when the last queued song has played.


MSG_QUEUE

Activated when songs are added to an empty queue; deactivated when the last song in the queue has started playing.


MSG_PRESONG

Activated when the delay period before a song starts, and deactivated when the song starts playing. If no delay is set, this message will activate at the beginning of a song and then immediately deactivate.


MSG_POSTSONG

Activated when the delay period after a song starts, and deactivated when the post-song delay is over. If no delay is set, this message will activate and then immediately deactivate.


MSG_INTERSONG

Activated when the between-song delay period starts, and deactivated when the between-song delay is over. If no delay is set, this message will not activate at all.


MSG_ADDINGCREDITS

If the skin is set to add multiple credits one at a time, this message is activated while the credits are being added and deactivated when all of the credits for that coin have been added.


MSG_ADDEDCREDIT

Activated for each credit as it is added, deactivated a moment later.


MSG_SKIPLASTOK

Activated when the Skip Last Song function is available, deactivated when the SkipLastTimeLimit timer is reached or another song is queued or the last song is actually skipped.


MSG_QUEUEFULL

Activated when the song queue is full; deactivated when the song queue is no longer full.
See also: MaxQueueSize.
MSG_SELECTING

Activated when one or more selection buttons have been pressed but not enough to make a valid selection. Deactivated when the selection is cleared or a valid selection is ready to be selected.


MSG_SELECTIONREADY

Activated when enough selection buttons have been pressed to indicate a valid selection. Deactivated when this is no longer the case.


MSG_ALLOWSELECTFULLCD

Activated at startup if the AllowSelectFullCD option is enabled. Deactivated if it is disabled.
See also: AllowSelectFullCD.
MSG_SONGSELECTED

Activated whenever a song is selected by any user action as opposed to by the RadioMode or PlayStimulator. Deactivated two seconds later.
See also: MSG_SELECTING, MSG_SELECTIONREADY.
MSG_SELECTEDALL

Activated if the user selects the full CD and all tracks are successfully queued. Deactivated two seconds later.
See also: MSG_ALLOWSELECTFULLCD, MSG_SELECTEDSOME.
MSG_SELECTEDSOME

Activated if the user selects the full CD but only some of the tracks are successfully queued due to lack of credits. Deactivated two seconds later.
See also: MSG_ALLOWSELECTFULLCD, MSG_SELECTEDALL.

Command Messages

A command message is similar to a BTN_ message; however, they are not sent in pairs, i.e. there is never a deactivation for them. Commands are meant to trigger actions in the jukebox as opposed to triggering GUI actions. These are not usually used as icon actions; they are used internally by timers. Command messages are not sent to the GUI so they should not be used by non-clickable icons, and clickable icons will not appear to "press" if mapped to a command message.


CMD_ADDCREDIT

If the skin is set to add multiple credits one at a time, this command is sent once for each credit to instruct the jukebox to increase the credit counter.


CMD_NEXTPG

Turns to the next page of songs.


CMD_PREVPG

Turns to the previous page of songs.


Back to contents