first pickle, then save to avoid killing config file on sigint
[enigma2.git] / 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.