doc/SOURCES

   1 Skins are now converted to use a "source"/"covert"/"render"-mechanism.
   2
   3 A "source" is a data-source. For example, the infobar has a source called
   4 "CurrentService", which is the currently displayed service, i.e. the channel
   5 the user is watching at the moment.
   6
   7 Now, a "current service" has a lot of properties, like
   8  - Service Name
   9  - service number
  10  - flags like "are subservices available?"
  11  - playback position, length, ...
  12
  13 Say you want to display the "service name" on screen. Only "renderers" can
  14 paint on the screen. The most basic renderer is the "Label"-Renderer, which
  15 can display a text. The "service name" is a text, so we use the
  16 "Label"-renderer. We also know that "CurrentService" is our source.
  17
  18 But the renderer can only display texts, not "services". It needs something
  19 to turn a "service" into a "text", i.e. something which extracts the service
  20 name out of a service.
  21
  22 That's where "converters" come into action. If we want to extract the
  23 servicename from a service, we need the "ServiceName"-converter. The
  24 "ServiceName"-converter can not only extract the service *name*, but also
  25 the provider name (another property of a service), so we have to specify
  26 what we want.
  27
  28 So our skin data could look like:
  29
  30 <widget source="CurrentService" render="Label" position="69,25"
  31                 size="427,26" font="Regular;22" backgroundColor="#101258" >
  32         <convert type="ServiceName">Name</convert>
  33 </widget>
  34
  35 The "call chain" consists of
  36
  37 "CurrentService" -> "ServiceName(NAME)" -> "Label"
  38
  39
  40 The are the following source types:
  41
  42 Clock - the current time
  43 EventInfo - the current now&next events
  44 MenuList - a menu
  45 CurrentService - the currently playing service
  46 FrontendStatus - frontend status, like BER, Signal Strength etc.
  47 Boolean - a usually fixed boolean value, for example "is record possible?"
  48
  49 Actually used sources are defined in a "Screen". That is, a Screen offers
  50 sources, which you can use inside your skin.
  51
  52 The "Infobar", for example, offers the following sources:
  53
  54 Event_Now
  55 Event_Next
  56 CurrentService
  57 RecordingPossible
  58 TimeshiftPossible
  59 ExtensionsAvailable
  60 Clock
  61
  62 Then there are the following "Converters":
  63
  64 ClockToText - turns a 'Clock' source into a text
  65   Parameters:
  66     "WithSeconds": "hh:mm:ss"
  67     "InMinutes"  : "mm min"
  68     "Date"       : "Wednesday, 07 June, 2006"
  69     "Default"    : "hh:mm"
  70 EventName - extracts the event name
  71   Parameters:
  72     "Description": Extracts the description of the event
  73     "ExtendedDescription": Extracts the extended description of the event
  74     "Name": extracts the name of the event
  75 EventTime - extracts the event time
  76   Parameters:
  77     "EndTime": extracts the end time of the event
  78     "Remaining": extracts the remaining time of the event
  79     "StartTime": extracts the start time of the event
  80     "Duration": extracts the duration of the event
  81     "Progress": extracts the progress of the event
  82 RemainingToText - turns a "remaining"-time into text ("xxx m", or "+xx m")
  83   It automatically uses the event length when the remaining time is invalid
  84 StringList - turns a menulist into a list usable for a "Listbox"-renderer
  85 FrontendInfo - extracts specific information out of a frontend
  86   Parameters:
  87     BER
  88     SNR
  89     AGC
  90     LOCK
  91
  92   You can either use a "Progress" or "Label" renderer, or, with Lock or
  93   BER, you can use a ConditionalShowHide to show a "warning symbol" when
  94   BER is >0.
  95
  96 ServiceInfo - extracts info out of a service
  97   Parameters:
  98     HasTeletext
  99     IsMultichannel
 100     IsCrypted
 101     IsWidescreen
 102     SubservicesAvailable
 103 ConditionalShowHide - conditionally show/hide a widgets based on the
 104                       source's boolean output
 105   Optional parameter: "Invert" - inverts the sense, i.e. show when boolean
 106                       value is false
 107 ServicePosition - extracts the current service play position out of a
 108                   service
 109   Parameters:
 110     "Length"
 111     "Position"
 112     "Remaining"
 113     "Gauge"
 114 ServiceName
 115   Parameters:
 116     "Name"
 117     "Provider"
 118
 119 Then there are the following renderers:
 120 Label
 121 Progress
 122 Listbox
 123 Pixmap
 124 PositionGauge
 125 FixedLabel
 126
 127 You can also put multiple converters in a row. Each one will pick up the
 128 output of the last coverter.
 129
 130 Of course you can only connect items which are compatible. Right now you
 131 have to look at the examples :)
 132
 133 Some more examples:
 134
 135 "SUBSERVICES AVAILABLE DISPLAY"
 136 ===============================
 137
 138                         <widget source="CurrentService" render="Pixmap" pixmap="button_green.png" position="320,132" size="27,12" >
 139                                 <convert type="ServiceInfo">SubservicesAvailable</convert>
 140                                 <convert type="ConditionalShowHide" />
 141                         </widget>
 142
 143 will display a pixmap whenever the "CurrentService" has
 144 "SubservicesAvailable".
 145
 146 "CURRENT SERVICE POSITION IN A POSITION GAUGE"
 147 ==============================================
 148
 149                         <widget source="CurrentService" render="PositionGauge" position="247,60" size="225,20" zPosition="2" pointer="position_pointer.png:3,5" >
 150                                 <convert type="ServicePosition">Gauge</convert>
 151                         </widget>
 152
 153 The "ServicePosition" is extracted from the CurrentService, and the
 154 PositionGauge picks that information up and displays it on screen.
 155
 156 "START TIME OF CURRENT EVENT"
 157 =============================
 158
 159                         <widget source="Event_Now" render="Label" position="210,68" size="60,22" font="Regular;20" backgroundColor="dark">
 160                                 <convert type="EventTime">StartTime</convert>
 161                                 <convert type="ClockToText">Default</convert>
 162                         </widget>
 163 The StartTime is extracted from the Event_Now (current event), and converted
 164 into text with the standard (hh:mm) style, then displayed with the
 165 "Label"-renderer.