Skin Timers

Table of Contents

• Description
• Examples
• Available tags
• See also
  • • • Development:

Programatic time-based resources for Skins

---

Description

Skin timers are skin resources that are dependent on time and can be fully controlled from skins either using Builtin functions or Infolabels and Boolean conditions. 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":

<timers>
    <timer>...</timer>
    <timer>...</timer>
</timers>

see the examples section and the list of available tags for concrete details.

v20 Skinning engine changes

Added skin timers

---

Examples

The following example illustrates the simplest possible skin timer. This timer is completely manual (it has to be manually started and stopped):

<timer>
    <name>mymanualtimer</name>
    <description>100% manual timer</description>
</timer>

This timer can be controlled from your skin by executing the Skin.TimerStart(mymanualtimer) builtin or Skin.TimerStop(mymanualtimer) builtin. 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 Skin.TimerIsRunning(mymanualtimer) info or depending on the elapsed time (e.g. 5 seconds) using the Integer.IsGreaterOrEqual(Skin.TimerElapsedSecs(mymanualtimer),5) info.

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:

<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 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:

<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.

<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:

<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".

<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>

---

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. (required)
description	The description of the timer, a helper string. (optional)
start	An info bool expression that the skinning engine should use to automatically start the timer (optional)
reset	An info bool expression that the skinning engine should use to automatically reset the timer (optional)
stop	An info bool expression that the skinning engine should use to automatically stop the timer (optional)
onstart	A builtin function that the skinning engine should execute when the timer is started (optional)(can be repeated). Supports an additional "condition" as element attribute.
onstop	A builtin function that the skinning engine should execute when the timer is stopped (optional)(can be repeated). Supports an additional "condition" as element attribute.

Note

If multiple onstart or onstop actions exist, their execution is triggered sequentially.

Both onstart and onstop actions support fine-grained conditional granularity by specifying a "condition" attribute (see the examples above).

---

See also

Development:

• Skinning