2015-04-04, 02:49
It's more general. What you get is the ability to pass arbitrary parameters to your includes and then use these values anywhere within the include body. Just so you don't have to copy/paste huge chunks of XML anymore in order to change just a value or two. Includes are now roughly equivalent to "procedures" in programming languages. Here's the final syntax that has been included in Kodi.
Include definitions are still written within <includes> tag, usually in includes.xml. But they can now accept parameters:
Here, the first part is called parameter list and is specified using <param> tags. When it is present, include body that follows it should be enclosed within <definition> tag. At the moment, parameter list is optional and is mainly used for specifying default values for parameters (such as 120 and 225 above), but is otherwise not mandatory.
The above include can be called like this:
This has the exact same effect as if you've written this instead:
and called it (old-style) like this:
only without added benefits.
Any appropriate value can be passed as parameter in the new include call, including $INFO labels, $LOCALIZE, $VARs, constants, etc. Empty string (value="") can also be passed, for example to override a non-empty default value set in the include definition.
Default values are used as replacement when their parameters are not passed in the include call.
$PARAM references can be specified within both tag values and attributes inside include body, and are expanded to either actual value passed (if it was passed), default value (if set) or empty string, in that order.
Parameters without default values (such as id above) are specified for better readability and documentation purposes only, but are otherwise not necessary and can be omitted. This is really a matter of style, and some skinners might prefer writing explicit parameter lists to specify all parameters referenced in the include body. It's a good practice though, as explicit parameter lists might be better utilized in the future versions of Kodi.
If there are no <param> tags at all, <definition> can be omitted too. This leads to even shorter syntax:
Includes can call other (nested) includes and even pass them exact parameter values that they've got themselves. This is called parameter forwarding.
Here, $PARAM[color] and $PARAM[scrollbarid] will be forwarded to MyOtherControl only if parameters color and scrollbarid have actually been passed to MyControl, otherwise the default values for color and id (if set in MyOtherControl) will be used instead in the body of MyOtherControl. Composite values containing other characters (such as label2) are not considered as "true" forwarding and always override any default value set in the nested include, even when they expand to empty strings.
Include definitions are still written within <includes> tag, usually in includes.xml. But they can now accept parameters:
Code:
<include name="MyControl">
<param name="id"/>
<param name="left" default="120"/>
<param name="top">225</param>
<definition>
<control type="image" id="$PARAM[id]">
<left>$PARAM[left]</left>
<top>$PARAM[top]</top>
<width>370</width>
<height>40</height>
<texture>foo.png</texture>
</control>
<definition>
</include>Here, the first part is called parameter list and is specified using <param> tags. When it is present, include body that follows it should be enclosed within <definition> tag. At the moment, parameter list is optional and is mainly used for specifying default values for parameters (such as 120 and 225 above), but is otherwise not mandatory.
The above include can be called like this:
Code:
<include name="MyControl">
<param name="id" value="52"/>
<param name="left">300</param>
</include>This has the exact same effect as if you've written this instead:
Code:
<include name="MyControl">
<control type="image" id="52">
<left>300</left>
<top>225</top>
<width>370</width>
<height>40</height>
<texture>foo.png</texture>
</control>
</include>and called it (old-style) like this:
Code:
<include>MyControl</include>only without added benefits.
Any appropriate value can be passed as parameter in the new include call, including $INFO labels, $LOCALIZE, $VARs, constants, etc. Empty string (value="") can also be passed, for example to override a non-empty default value set in the include definition.
Default values are used as replacement when their parameters are not passed in the include call.
$PARAM references can be specified within both tag values and attributes inside include body, and are expanded to either actual value passed (if it was passed), default value (if set) or empty string, in that order.
Parameters without default values (such as id above) are specified for better readability and documentation purposes only, but are otherwise not necessary and can be omitted. This is really a matter of style, and some skinners might prefer writing explicit parameter lists to specify all parameters referenced in the include body. It's a good practice though, as explicit parameter lists might be better utilized in the future versions of Kodi.
If there are no <param> tags at all, <definition> can be omitted too. This leads to even shorter syntax:
Code:
<include name="MyControl">
<control type="image" id="$PARAM[id]">
<left>$PARAM[left]</left>
<top>$PARAM[top]</top>
<width>370</width>
<height>40</height>
<texture>foo.png</texture>
</control>
</include>Includes can call other (nested) includes and even pass them exact parameter values that they've got themselves. This is called parameter forwarding.
Code:
<include name="MyControl">
...
<include name="MyOtherControl">
<param name="label">$INFO[Player.Title]</param>
<param name="label2" value="x:$PARAM[left]; y:$PARAM[top]"/>
<param name="color" value="$PARAM[color]"/> <!-- forwarding -->
<param name="id" value="$PARAM[scrollbarid]"/> <!-- forwarding -->
</include>
...
</include>Here, $PARAM[color] and $PARAM[scrollbarid] will be forwarded to MyOtherControl only if parameters color and scrollbarid have actually been passed to MyControl, otherwise the default values for color and id (if set in MyOtherControl) will be used instead in the body of MyOtherControl. Composite values containing other characters (such as label2) are not considered as "true" forwarding and always override any default value set in the nested include, even when they expand to empty strings.
Not so important since I have the animations working but ... Request more code lines and not as clean as using dynamic positioning. However good job on this. Will see how to integrate it elsewhere in the code.
