xbmc/guilib/GUIControlGroup.dox

   1 /*!
   2
   3 \page Group_Control Group Control
   4 \brief **Used to group controls together.**
   5
   6 \tableofcontents
   7
   8 The group control is one of the most important controls. It allows you to group
   9 controls together, applying attributes to all of them at once. It also remembers
  10 the last navigated button in the group, so you can set the <b>`<onup>`</b> of a control
  11 to a group of controls to have it always go back to the one you were at before.
  12 It also allows you to position controls more accurately relative to each other,
  13 as any controls within a group take their coordinates from the group's top left
  14 corner (or from elsewhere if you use the "r" attribute). You can have as many
  15 groups as you like within the skin, and groups within groups are handled with
  16 no issues.
  17
  18
  19 --------------------------------------------------------------------------------
  20 \section Group_Control_sect1 Example
  21
  22 ~~~~~~~~~~~~~
  23 <control type="group" id="17">
  24       <description>My first group control</description>
  25       <posx>80</posx>
  26       <posy>60</posy>
  27       <width>250</width>
  28       <height>30</height>
  29       <defaultcontrol>2</defaultcontrol>
  30       <visible>true</visible>
  31       <onup>2</onup>
  32       <ondown>3</ondown>
  33       <onleft>1</onleft>
  34       <onright>1</onright>
  35       ... more controls go here ...
  36 </control>
  37 ~~~~~~~~~~~~~
  38
  39
  40 --------------------------------------------------------------------------------
  41 \section Group_Control_sect2 Available tags
  42
  43 In addition to the [Default Control Tags](http://kodi.wiki/view/Default_Control_Tags)
  44 the following tags are available. Note that each tag is **lower case** only. This is
  45 important, as `xml` tags are case-sensitive.
  46
  47 | Tag               | Description                                                   |
  48 |------------------:|:--------------------------------------------------------------|
  49 | defaultcontrol    | Specifies the default control that will be focused within the group when the group receives focus. Note that the group remembers it's previously focused item and will return to it.
  50
  51
  52 --------------------------------------------------------------------------------
  53 \section Group_Control_sect3 Notes on positioning of controls within groups
  54
  55 All controls within a group take their positions relative to the group's placement.
  56 Thus, the group always requires its <b>`<posx>`</b>, <b>`<posy>`</b>,
  57 <b>`<width>`</b>, and <b>`<height>`</b> attributes to be defined.
  58 As this can be a pain to remember, anything that you don't specify will be
  59 inherited from it's parent group (or the main window).
  60
  61 By way of example, consider the first group within a PAL full screen window
  62 (720x576), and suppose we have
  63
  64 ~~~~~~~~~~~~~
  65 <control type="group" id="15">
  66   <posx>30</posx>
  67   <posy>70</posy>
  68   <width>400</width>
  69   ... more controls go here ...
  70 </control>
  71 ~~~~~~~~~~~~~
  72
  73 so that the <b>`<height>`</b> hasn't been defined. Then Kodi will
  74 automatically set the <b>`<height>`</b> equal to 506 by inheriting this
  75 from the window's height of 576, less the <b>`<posy>`</b> amount.
  76
  77 You can align controls within a group to the right edge of the group, by
  78 using the <b>"r"</b> modifier to the <b>`<posx>`</b> and <b>`<posy>`</b> fields
  79
  80 ~~~~~~~~~~~~~
  81 <control type="group" id="20">
  82   <control type="button" id=2>
  83     <posx>180r</posx>
  84     <width>180</width>
  85   </control>
  86   <control type="button" id=3>
  87     <posx>180r</posx>
  88     <width>180</width>
  89   </control>
  90   <control type="button" id=4>
  91     <posx>180r</posx>
  92     <width>180</width>
  93   </control>
  94 </control>
  95 ~~~~~~~~~~~~~
  96
  97 All the buttons have width 180, and are aligned 180 pixels from the right edge of the group they're within.
  98
  99
 100 --------------------------------------------------------------------------------
 101 \section Group_Control_sect4 See also
 102
 103 #### Development:
 104
 105 - [Add-on development](http://kodi.wiki/view/Add-on_development)
 106 - [Skinning](http://kodi.wiki/view/Skinning)
 107
 108 */