SqueezePlay Developers FAQ

This page needs editing. It may contain errors and/or outdated information.

ACTION event model change coming in 7.4

For 7.4, the SP input event model will be change to include a new "action" event. An action event is a means to translate different sources of the same user input (controller buttons, keyboard shortcuts, future input types) into a action which then represents what high level function is to be performed rather the what input was received. Applets can then listen for action event to perform a specific implementation for the action.

In a nutshell, for an applet developer, this means that instead of writing the following:

widget:addListener(EVENT_KEY_PRESS | EVENT_CHAR_PRESS | EVENT_SOME_FUTURE_INPUT_TYPE,
		function(...)
			if (event:getType() == EVENT_KEY_PRESS and event:getKeycode() == KEY_PLAY ) or (event:getType() == EVENT_CHAR_PRESS and string.char(event:getUnicode()) == "p") then
				doSomething()
			end
		end
	)

you would write:

widget:addActionListener("play", obj, doSomething)

where "play" is the name of an existing action. Behind the scenes, when a user hits play on the Controller or hits p on a keyboard, a "play" event will be dispatched.

Any applet that still wishes to listen for specific input events such as EVENT_KEY_* or EVEN_CHAR_* can still do so. Listeners for those events will take priority over ACTION listeners.

The backwards compatibility implication of this is: If your applet is listening for only KEY events to receive input, your applet will still work, but will only work for Controller KEY inputs, not keyboard shortcuts. If you want to support keyboard shortcuts and future input, convert to using Framework:addActionListener() or widget:addActionListener() (Prior to this change, we used code to translate keyboard shortcuts to KEY events, but that is being eliminated to support the ACTION model).

The 7.4 branch is in the process of being converted to the new model. Many, but not, all of the new action names have been defined, and can be seen in 7.4/trunk/squeezeplay/share/jive/InputToActionMap.lua This file also holds the mapping of the various inputs to their corresponding default action.

Developers will be able to add additional actions and also be able to override what inputs trigger a given action. The design and implementation for this override capability is not yet complete.

What are the keyboard shortcuts?

Mouse support is targeted for the 7.2 release, so in the meantime you'll need to use the keyboard. The keys are:

Go		   RIGHT, RETURN, mouse middle button
Back		   LEFT, ESC, (todo - mouse right button), BACKSPACE
Scroll up	   UP, mouse wheel
Scroll down	   DOWN, mouse wheel
Home              h, HOME
Up		   i
Down		   k
Left		   j
Right		   l
Play		   x p, mouse left button, (Media Key PLAY - Windows, Linux)
Play (hold)	   P    
Play next          W
Pause		   c space, (Media Key PAUSE - Windows, Linux)
Add		   a, (Keypad +)
Add  (hold)	   A
Rew		   z, <, (Media Key REW - Windows, Linux)
Rew  (hold)	   Z
Fwd		   b, >, (Media Key FWD - Windows, Linux)
Fwd  (hold)	   B
Volume up	   +, =, (Media Key VOLUP)
Volume down	   -, (Media Key VOLDOWN)
Screenshot        S
Disconnect Player D
Search            /
--Temporary/In progress:
[                  Now Playing
]                  Now Playing Playlist
,                  Shuffle Toggle
.                  Repeat Toggle
;                  Music Library
:                  Favorites
Play Favorite 0-9  0-9
<Debug Skin>       }
<Reload Skin>      R
--During text input screens (search, etc), ESC leaves the text input entirely and BACKSPACE acts as a text backspace.
--Note: To view the related source code directly see (for 7.4): http://svn.slimdevices.com/jive/7.4/trunk/squeezeplay/src/squeezeplay/share/jive/InputToActionMap.lua?view=markup

What is the difference between EVENT_KEY_PRESS and EVENT_KEY_HOLD?

SqueezePlay uses four key events, EVENT_KEY_DOWN, EVENT_KEY_PRESS, EVENT_KEY_HOLD and EVENT_KEY_UP.

EVENT_KEY_DOWN and EVENT_KEY_UP are sent when the key is physically pressed and released. These events are not used often but are useful when a key repeat is needed, for example the volume control. If the key is held down for 2 seconds then a EVENT_KEY_HOLD event is dispatch, otherwise if the key is released before the hold timeout then a EVENT_KEY_PRESS event is dispatched.