Description

A button in MediaPortal.

Changelog

Change	Date	Version
Fadelabel text wrapping and button control with fadelabel	2010/10/10	1.0.1 to 1.1.0
Back Button Control (history)	2010/10/05	1.1.0 to 1.2.0
Open Plugins with a Parameter	2010/10/05	1.1.0 to 1.2.0
Image Masking	2010/11/14	1.1.0 to 1.2.0
Expressions in Hyperlink, Action, OnXXX	2014/01/28	1.6.0 to 1.7.0
Image Tile Fill	2010/10/05	1.1.0 to 1.2.0
Enhance textXOff in Buttons	2011/12/17	1.2.0 to 1.3.0
Image borders	2010/10/10	1.0.1 to 1.1.0
Text Padding	2013/01/27	1.2.0 to 1.3.0
Shadow text	2010/10/10	1.0.1 to 1.1.0

Tags

GUIButtonControl (button)

Element Name	Data Type	Description
textureFocus [border, position, textureRepeat, textureRotate, texture, colorKey, corners, cornerRotate, mask, tileFill]	String	The texture to display when the button has the focus/is selected
border	String	With this feature you have the ability to add borders composed from textures that you identify. See Borders for a more detailled description.
position	BorderPosition	Specifies the position of the border relative to the image or control rectangle edges. Valid values are OutsideImage, InsideImage, CenterImage, OutsideControl, InsideControl, CenterControl. The default value is "OutsideImage". Example: <border position="CenterControl">10</border>
textureRepeat	Boolean
textureRotate	Boolean
texture	String
colorKey	Long
corners	Boolean
cornerRotate	Boolean
mask	String	Allows to specify a mask that defines the areas of the images that are drawn to screen. See Image Masks for more information on how to use image masks in MediaPortal.
tileFill	Boolean
textureNoFocus [border, position, textureRepeat, textureRotate, texture, colorKey, corners, cornerRotate, mask, tileFill]	String	The texture to display when the button does not have the focus/is not selected
border	String	With this feature you have the ability to add borders composed from textures that you identify. See Borders for a more detailled description.
position	BorderPosition	Specifies the position of the border relative to the image or control rectangle edges. Valid values are OutsideImage, InsideImage, CenterImage, OutsideControl, InsideControl, CenterControl. The default value is "OutsideImage". See Borders for a more detailled description.
textureRepeat	Boolean	Specifies whether the texture used for the border should repeat or stretch inside each of the four rectangles that compose the overall border. The default value is "no". Example: <border textureRepeat="yes">10</border>
textureRotate	Boolean
texture	String
colorKey	Long
corners	Boolean
cornerRotate	Boolean
mask	String	Allows to specify a mask that defines the areas of the images that are drawn to screen. See this section for more information on how to use image masks in MediaPortal.
tileFill	Boolean	Will tile a texture to the rectangle rather than stretch it
font	String	The font to use to display the button text.
label	String	The button text, property or a number that corresponds to an id in the strings.xml file.
textcolor	Long	The color of the text when the button has the focus/is selected
textcolorNoFocus	Long	The color of the text when the button is not selected
disabledcolor	Long	The color of the text when the button is disabled
hyperlink [history]	String	The id of the xml skin page that MP will load when the button is pushed. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
history	Boolean	Defines if the opened window will be stored in the history. See History for more information.
hyperlinkParameter	String	A String that is sent to the plugin specified in hyperlink as a parameter on startup. This feature allows plugins to be started depending on what the user or skin defines.
action	Integer	The prefefined event to execute when the button is pushed. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
script	String	Unknown
textXOff [hasMargin]	Integer	The number of pixels the text label is offset from the left edge of the button image
hasMargin	Boolean	[Since 1.3] If true, textXOff is used to provide horizontal space before and after the button label.
textYOff	Integer	The number of pixels the text label is offset from the top edge of the button image.
textpadding	Integer	[Since 1.3] provides "space" inside the label text to prevent overlap with graphics that follow on the right.
textalign	Alignment	Align the text in the button "left", "right" or "center"
textvalign	VAlignment	Vertical align of the text "top", "middle", "bottom"
application	String	The application to launch when the button is pushed. The application working directory is set to the executable directory and run hidden. MediaPortal does not wait for the application to exit.
arguments	String	The arguments passed to the application being launched
hover [border, position, textureRepeat, textureRotate, texture, colorKey, corners, cornerRotate, mask, tileFill]	String	The image to display when the button has the focus
border	String	With this feature you have the ability to add borders composed from textures that you identify. See Borders for a more detailled description.
position	BorderPosition	Specifies the position of the border relative to the image or control rectangle edges. Valid values are OutsideImage, InsideImage, CenterImage, OutsideControl, InsideControl, CenterControl. The default value is "OutsideImage". See Borders for a more detailled description.
textureRepeat	Boolean	Specifies whether the texture used for the border should repeat or stretch inside each of the four rectangles that compose the overall border. The default value is "no". Example: <border textureRepeat="yes">10</border>
textureRotate	Boolean	Specifies whether or not the texture used for the border should be rotated for each of the border rectangles. If the texture should rotate then the texture will be rotated 90 deg for the right border rectangle, 180 deg for the bottom, and 270 deg for the left. The default value is "no". Example: <border textureRotate="yes">10</border>
texture	String	Specifies the tetxure filename for the border rectangles. A single file is used for all four of the border rectangles. Based on the value of textureRepeat, the entire texture extent is either stretched (scaled up/down) to fill the border rectangles or is scaled (up/down) to fit inside the border rectangle at its native aspect ratio and repeatedly drawn until the border rectangle is filled. The default value is "image_border.png". This texture file must exist in the skin media directory otherwise no border will be drawn. Example: <border texture="my_border.png">10</border>
colorKey	Long	Specfies the color key for the border texture. The default value is 0xFFFFFFFF. Example: <border colorKey="0x66FFFFFF">10</border>
corners	Boolean	Specifies that the border should be rendered with corners. When the border should be rendered with corners the image control selects a texture file based on the name of the border,texture attribute. The selected file must end with "_corner" (excluding the extension); e.g., "image_border_corner.png". The default value is "no". Example: <border corners="yes">10</border>
cornerRotate	Boolean	Specifies whether or not the texture used for the border corner should be rotated for each of the four border corner rectangles. A single texture file is used for all four of the border corner rectangles. If the texture should rotate then the texture will be rotated 90 deg for the upper right border rectangle, 180 deg for the bottom right, and 270 deg for the bottom left. The default value is "no". Example: <border cornerRotate="yes">10</border>
mask	String	Allows to specify a mask that defines the areas of the images that are drawn to screen. See this section for more information on how to use image masks in MediaPortal.
tileFill	Boolean	Will tile a texture to the rectangle rather than stretch it
hoverX	Integer	The X position on the window to display the hover image
hoverY	Integer	The Y position on the window to display the hover image
hoverWidth	Integer	The width of the hover image
hoverHeight	Integer	The height of the hover image
shadowAngle	Integer
shadowDistance	Integer
shadowColor	Long
scrollStartDelaySec	Integer	sets the delay before scrolling starts, and enables scrolling of label text when it is too long for the texture
scrollWrapString	String	character to identify the end of the label text as it scrolls
onclick	String	[Since 1.3] Executes a MediaPortal skin function when the button is clicked. See Skin Settings for more information.

Inherited by GUIControl

See GUIControl for the full documentation of this control.

Element Name	Data Type	Description
id	Integer	The id of the control. The id will couple the skin file to the code, so if we later on want to check that a user pressed a button, the id will be required and must be unique. For controls that will never be referenced in the code it is safe to set it to "1"
description	String	An optional description of the control for your reference
type	String	The type of the control, for instance "button", "label", "textbox" and all other controls.
posX	Integer	The X-position on the window for this control
posY	Integer	The Y-position on the window for this control
width	Integer	The width of this control
height	Integer	The height of this control
onleft	Integer	The control id to move the focus to when the user moves left. If not specified (or zero) MediaPortal will find the closest control in that direction to move to. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
onright	Integer	The control id to move the focus to when the user moves right. If not specified (or zero) MediaPortal will find the closest control in that direction to move to. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
onup	Integer	The control id to move the focus to when the user moves up. If not specified (or zero) MediaPortal will find the closest control in that direction to move to. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
ondown	Integer	The control id to move the focus to when the user moves down. If not specified (or zero) MediaPortal will find the closest control in that direction to move to. As of v1.7.0 Skin Settings and Skin Expressions are also supported.
colordiffuse	Long	Allows you to mix a color & a graphics texture. E.g. If you have a graphics texture like a blue button you can mix it with a yellow color diffuse and the end result will be green. Defaults to 0xFFFFFFFF
dimColor	Integer	Color for a control when it is not focussed. Defaults to half transparent (0x60ffffff)
onfocus	String	[Since 1.3] Executes a MediaPortal skin function when the control gains focus. See Skin Settings for more information.

Properties exposed

GUIButtonControl

Property Name	Data Type	Description
#highlightedbutton	String	Sets the value to the label text when the button is highlighted

XML examples

The label tag can contain any of the following:

A string (e.g. "Hello World")
A number (e.g. 6) which is then converted to a string from the strings.xml file
A property (e.g. #date) which is then converted to either a string or number to be converted

A button can have 1 or more subitems, each subitem has its own text to render on the button. When the user presses the button, the next item will be selected and shown on the button label. For example:

<control>
    <description>View-As button</description>
    <type>button</type>
    <id>2</id>
    <posX>300</posX>
    <posY>200</posY>
    <width>190</width>
    <height>32</height>
    <textureFocus mask="video_poster_mask.png">menu_list_focus.png</textureFocus>
    <textureNoFocus mask="video_poster_mask.png">menu_list_nofocus.png</textureNoFocus>
    <label>100</label>
    <font>font13</font>
    <textcolor>ffffffff</textcolor>
    <disabledcolor>60ffffff</disabledcolor>
    <colordiffuse>ffffffff</colordiffuse>
    <textXOff>10</textXOff>
    <textYOff>5</textYOff>
    <action>10</action>
    <hyperlink>603</hyperlink>
    <onup>17</onup>
    <ondown>3</ondown>
    <onleft>2</onleft>
    <onright>50</onright>
    <subitems>
        <subitem>101</subitem>
        <subitem>100</subitem>
        <subitem>417</subitem>
    </subitems>
</control>

Open a new window and don't store the current window in the history:

<control>
    <description>Radiobutton</description>
    <type>button</type>
    <id>105</id>
    <posX>214</posX>
    <posY>422</posY>
    <width>50</width>
    <height>45</height>
    <hyperlink history="no">30</hyperlink>
    <textureFocus>Radiobutton_focus.png</textureFocus>
    <textureNoFocus>Radiobutton_nofocus.png</textureNoFocus>
    <onright>106</onright>
    <onup>50</onup>
    <onup>10</onup>
    <ondown>99</ondown>
</control>

Position text using textXOff while preserving the width of the label text by setting the textXOff property hasMargin to "no";

<textXOff hasMargin="no">20</textXOff>

Seitenhierarchie