Adding upstream version 2:20.4+dfsg.upstream/2%20.4+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 164 insertions, 0 deletions

diff --git a/xbmc/addons/gui/skin/SkinTimers.dox b/xbmc/addons/gui/skin/SkinTimers.dox
new file mode 100644
index 0000000..0d6f171
--- /dev/null
+++ b/xbmc/addons/gui/skin/SkinTimers.dox
@@ -0,0 +1,164 @@
+/*!
+
+\page Skin_Timers Skin Timers
+\brief **Programatic time-based resources for Skins**
+
+\tableofcontents
+
+--------------------------------------------------------------------------------
+\section Skin_Timers_sect1 Description
+
+Skin timers are skin resources that are dependent on time and can be fully controlled from skins either using
+\link page_List_of_built_in_functions **Builtin functions**\endlink or
+\link modules__infolabels_boolean_conditions **Infolabels and Boolean conditions**\endlink. One can see them
+as stopwatches that can be activated and deactivated automatically depending on the value of info expressions or simply activated/deactivated
+manually from builtins.
+The framework was created to allow skins to control the visibility of windows (and controls) depending on
+the elapsed time of timers the skin defines. Skin timers allow multiple use cases in skins, previously only available via the execution
+of python scripts:
+- Closing a specific window after x seconds have elapsed
+- Controlling the visibility of a group (or triggering an animation) depending on the elapsed time of a given timer
+- Defining a buffer time window that is kept activated for a short period of time (e.g. keep controls visible for x seconds after a player seek)
+- Executing timed actions (on timer stop or timer start)
+- etc
+
+Skin timers are defined in the `Timers.xml` file within the xml directory of the skin. The file has the following "schema":
+
+~~~~~~~~~~~~~{.xml}
+<timers>
+    <timer>...</timer>
+    <timer>...</timer>
+</timers>
+~~~~~~~~~~~~~
+
+see \link Skin_Timers_sect2 the examples section\endlink and \link Skin_Timers_sect3 the list of available tags\endlink for concrete details.
+
+\skinning_v20 Added skin timers
+
+--------------------------------------------------------------------------------
+\section Skin_Timers_sect2 Examples
+
+The following example illustrates the simplest possible skin timer. This timer is completely manual (it has to be manually started and stopped):
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>mymanualtimer</name>
+    <description>100% manual timer</description>
+</timer>
+~~~~~~~~~~~~~
+
+This timer can be controlled from your skin by executing the \link Builtin_SkinStartTimer `Skin.TimerStart(mymanualtimer)` builtin\endlink or
+\link Builtin_SkinStopTimer `Skin.TimerStop(mymanualtimer)` builtin\endlink. You can define the visibility of skin elements based on the internal
+properties of the timer, such as the fact that the timer is active/running using \link Skin_TimerIsRunning `Skin.TimerIsRunning(mymanualtimer)` info\endlink
+or depending on the elapsed time (e.g. 5 seconds) using the \link Skin_TimerElapsedSecs Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(mymanualtimer),5) info\endlink.
+
+The following timer is a variation of the previous timer but with the added ability of being automatically stopped by the skinning engine after a maximum of elapsed
+5 seconds without having to issue the `Skin.TimerStop(mymanualtimer)` builtin:
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>mymanualautocloseabletimer</name>
+    <description>100% manual autocloseable timer</description>
+    <stop>Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(mymanualautocloseabletimer),5)</stop>
+</timer>
+~~~~~~~~~~~~~
+
+This type of timer is particularly useful if you want to automatically close a specific window (or triggering a close animation) after x time has elapsed,
+while guaranteeing the timer is also stopped. See the example below:
+
+~~~~~~~~~~~~~{.xml}
+<?xml version="1.0" encoding="utf-8"?>
+<window type="dialog" id="1109">
+	<onload>Skin.TimerStart(mymanualautocloseabletimer)</onload>
+    ...
+	<controls>
+		<control type="group">
+			<animation effect="slide" start="0,0" end="0,-80" time="300" condition="Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(mymanualautocloseabletimer),5)">Conditional</animation>
+			...
+        </control>
+    </controls>
+</window>
+~~~~~~~~~~~~~
+
+The following timer presents a notification (for 1 sec) whenever the timer is activated or deactivated:
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>manualtimerwithactions</name>
+    <description>100% manual timer with actions</description>
+    <onstart>Notification(skintimer, My timer was started, 1000)</onstart>
+    <onstop>Notification(skintimer, My timer was stopped, 1000)</onstop>
+</timer>
+~~~~~~~~~~~~~
+
+The following timer is an example of a completely automatic timer. The timer is automatically activated or deactivated based on the value
+of boolean info expressions. In this particular example, the timer is automatically started whenever the Player is playing a file (if not already running). It is stopped if
+there is no file being played (and of course if previously running). Since the timer can be activated/deactivated multiple times, `reset="true"` ensures the timer is
+always reset to 0 on each start operation. Whenever the timer is started or stopped, notifications are issued.
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>myautomatictimer</name>
+    <description>Player state checker</description>
+    <start reset="true">Player.Playing</start>
+    <stop>!Player.Playing</stop>
+    <onstart>Notification(skintimer, Player has started playing a file, 1000)</onstart>
+    <onstop>Notification(skintimer, Player is no longer playing a file, 1000)</onstop>
+</timer>
+~~~~~~~~~~~~~
+
+In certain situations you might want to reset your timer without having to stop and start. For instance, if you want to stop the timer after 5 seconds
+but have the timer resetting to 0 seconds if the user provides some input to Kodi. For such cases the `<reset/>` condition can be used:
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>windowtimer</name>
+    <description>Reset on idle</description>
+    <start reset="true">Window.IsActive(mywindow)</start>
+    <reset>Window.IsActive(mywindow) + !System.IdleTime(1) + Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(windowtimer), 1)</reset>
+    <stop>!Window.IsActive(mywindow) + Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(windowtimer), 5)</stop>
+    <onstop>Dialog.Close(mywindow)</onstop>
+</timer>
+~~~~~~~~~~~~~
+
+Finer conditional granularity can also be applied to the `onstop` or `onstart` actions. This allows the skinner to create generic timers which respect a 
+limited set of conditions but trigger different actions depending on a condition applied only to the action.
+The following timer plays the trailer of a given item when the user is in the videos window, the item has a trailer, the player is not playing and the
+global idle time is greater than 3 seconds.
+As you can see, the first action (notification) is triggered for any item. The actual playback, on the other hand, will only play if the focused
+item has the label "MyAwesomeMovie".
+
+~~~~~~~~~~~~~{.xml}
+<timer>
+    <name>trailer_autoplay_idle_timer</name>
+    <start reset="true">System.IdleTime(3) + Window.IsVisible(videos) + !Player.HasMedia + !String.IsEmpty(ListItem.Trailer)</start>
+    <onstart>Notification(skintimer try play, $INFO[ListItem.Trailer], 1000)</onstart>
+    <onstart condition="String.IsEqual(ListItem.Label,MyAwesomeMovie)">PlayMedia($INFO[ListItem.Trailer],1,noresume)</onstart>
+</timer>
+~~~~~~~~~~~~~
+
+--------------------------------------------------------------------------------
+\section Skin_Timers_sect3 Available tags
+
+Skin timers have the following available tags:
+
+| Tag           | Description                                                   |
+|--------------:|:--------------------------------------------------------------|
+| name          | The unique name of the timer. The name is used as the id of the timer, hence needs to be unique. <b>(required)</b>
+| description   | The description of the timer, a helper string. <b>(optional)</b>
+| start         | An info bool expression that the skinning engine should use to automatically start the timer <b>(optional)</b>
+| reset         | An info bool expression that the skinning engine should use to automatically reset the timer <b>(optional)</b>
+| stop          | An info bool expression that the skinning engine should use to automatically stop the timer <b>(optional)</b>
+| onstart       | A builtin function that the skinning engine should execute when the timer is started <b>(optional)</b><b>(can be repeated)</b>. Supports an additional `"condition"` as element attribute.
+| onstop        | A builtin function that the skinning engine should execute when the timer is stopped <b>(optional)</b><b>(can be repeated)</b>. Supports an additional `"condition"` as element attribute.
+
+@note If multiple onstart or onstop actions exist, their execution is triggered sequentially.
+@note Both onstart and onstop actions support fine-grained conditional granularity by specifying a "condition" attribute (see the examples above).
+
+--------------------------------------------------------------------------------
+\section Skin_Timers_sect4 See also
+#### Development:
+
+- [Skinning](http://kodi.wiki/view/Skinning)
+
+*/