forked from BigNoid/script.skinshortcuts
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
365 lines (215 loc) · 17.6 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
script.skinshortcuts was written with the intention of making user customizable shortcuts on the home page easier for skinners.
What's New for Skinners (version 0.4.4 - current Repo release)
-----------------------
- Just Select method - option to show a 'None' option, which will reset all skin labels passed in. See "Advanced Usage.txt", section "Just Select Shortcuts"
- Ability to specify available thumbnails for user to choose from with new button 311. See "Advanced Usage.txt", section "Overrides.xml", part 13 and "Management Dialog.txt"
- Ability to specify conditions for widgets and thumbnails to determine if they are available for selection. See "Advanced Usage.txt", section "Overrides.xml", parts 3 and 4
- Ability to set skin boolean based on inclusion of a shortcut with a specified action. See "Advanced Usage.txt", section "Overrides.xml", part 7
- Advice change - hasSubmenu cannot be relied upon to indicate there are no visible items, there may still be invisible items.
What's New for Skinners (version 0.4.2 - previous release)
-----------------------
- Ability to skip warning when resetting all shortcuts. See "Resetting all shortcuts", below
- Ability to set default backgrounds and widgets based on defaultID. See "Advanced Usage.txt", section "Overrides.xml", parts 3 and 4
- Ability to define a default path when browsing for backgrounds. See "Advanced Usage.txt", section "Overrides.xml", part 3
- Skin properties set for each background and widget that is active. See "Advanced Usage.txt", sections "Managing Custom Backgrounds" and "Managing Widgets".
- Window property set when management dialog for submenu/additional menu is launched. See "Management Dialog.txt", part 6
- Advice change - consider providing a defaultID in your default shortcuts. See "Providing default shortcuts", below.
- Advice change - use video node links, rather than library links, in your default shortcuts. See "Providing default shortcuts" below; and "Advanced Usage.txt", section "Overrides.xml", part 1.
- Shortcuts with a <visible/> element will not only show in management dialog if this property evaluates to true. Though they won't be visible in the management dialog, they will not be removed from the menu, but will move to the end of the menu.
With Thanks - Because their names don't deserve to be at the bottom :)
-----------
Huge thanks to Ronie, whose code for listing plugins is used in this script
Equally huge thanks to Ronie and `Black, for their favourites code used in this script
More huge thanks to BigNoid, for the ability to edit shortcuts, and Jeroen, for so many suggestions each of which just made the script better.
The thanks remain absolutely huge to the translaters on Transifex for localising the script
And the biggest thanks of all to Annie and my family, for feature suggestions, testing and shouting at me when I broke things
Where To Get Help
-----------------
Though hopefully Skin Shortcuts will save you a lot of code in the long-run, it is a relatively complex script and so may take some time to get your head around.
To help, it includes several documentation files:
readme.txt - This file, containing basics of integrating the script
resources/Advanced Usage.txt - Contains details of more advanced configuration and customisation
resources/Management Dialog.txt - Contains details of how to skin the management dialog the user will interact with to manage their shortcuts
resources/labelID.txt - Contains details of the labelID system used to identify shortcuts.
It's highly recommended to take time to read through all of these documents before you begin.
If you require any assistance post on the XBMC forum and I'll do my best to assist:
http://forum.xbmc.org/showthread.php?tid=178294
Before you Begin
----------------
Before you can add the script to your skin, you have a decisions to make:
How much of the menu system should the script manage?
- Main menu and sub-menus
- Main menu and sub-menus, with additional menus unlinked to main menu
- Sub-menus only
Whichever menu system you choose, details of how to implement are below. Below that, there is information common to all methods which you should also read.
You may also choose to manage menu's yourself, and just make use of the scripts list of available shortcuts. For more details see "Just Select Shortcuts" in Advanced Usage.txt
Main menu and sub-menus
-----------------------
1. Include the necessary file, and run the script
This method runs the script when the user enters the main menu or has left the skin settings. If a change to the menu has been made, it writes out the new menu into a file that you can <include> in your skin.
*IMPORTANT*
Using this method WILL WRITE AN ADDITIONAL FILE TO YOUR SKINS DIRECTORY called script-skinshortcut-includes.xml!
First the file must be imported - in your includes.xml add the line:
<include file="script-skinshortcuts-includes.xml"/>
In home.xml, add the line:
<onload>RunScript(script.skinshortcuts,type=buildxml&mainmenuID=9000&levels=0)</onload>
And in skinsettings.xml, the line:
<onunload>RunScript(script.skinshortcuts,type=buildxml&mainmenuID=9000&levels=0)</onunload>
Replace 9000 with the ID of the list you are using for the mainmenu. If you are providing more than one sub-menu per main-menu item, increase the levels accordingly.
2. Let users manage their main menu and sub-menu shortcuts
The script can provide a list of controls for your overrides.xml to let the user manage both main menu and sub-menu.
Uses new method of filling the contents of a list in Gotham. In the list where you want these controls to appear, put the following in the <content> tag:
plugin://script.skinshortcuts?type=settings&property=$INFO[Window(10000).Property("skinshortcuts")]
Alternatively, you can create a button with the following onclick method:
RunScript(script.skinshortcuts,type=manage&group=mainmenu)
Then, within the management dialog, provide a button with the id 405 to let the user manage sub-menus. You must use this method if you want to provide more than one sub-menu.
If using the second method, you may also want to provide a reset button, with the following in the onclick method:
RunScript(script.skinshortcuts,type=resetall)
3. Display main menu and shortcuts
This details the simplest method of displaying main menu and sub-menus, using two lists. When the user focuses on an item in the main menu list, the sub-menu list will update with the shortcuts for that item.
In the list where you want the main menu to appear, put the following in the <content> tag:
<include>skinshortcuts-mainmenu</include>
In the list where you want the sub-menu to appear, put the following in the <content> tag:
<include>skinshortcuts-submenu</include>
Remember to replace 9000 with the id of the list you are using for the main menu.
To provide additional sub-menus, use the following in the <content> tag:
<include>skinshortcuts-submenu-[level]</include>
Where level indicates the additional submenu level, starting from 1.
Main menu and sub-menus, with additional menus unlinked to main menu
-----------------------
Same as the method above, except you need to include the &group= parameter to the build line, with mainmenu as the first group, and any additional groups you wish built separated by a pipe - | - symbol.
<onload>RunScript(script.skinshortcuts,type=buildxml&mainmenuID=9000&group=mainmenu|[groupname]|[groupname]|[groupname])</onload>
To the let user manage shortcuts in these additional groups
RunScript(script.skinshortcuts, type=manage&group=[groupname])
And to display them:
<include>skinshortcuts-group-[groupname]</include>
Sub-menu Only
-------------
1. Include the necessary file, and run the script
This method runs the script when the user enters the main menu or has left the skin settings. If a change to the menu has been made, it writes out the new menu into a file that you can <include> in your skin.
*IMPORTANT*
Using this method WILL WRITE AN ADDITIONAL FILE TO YOUR SKINS DIRECTORY called script-skinshortcut-includes.xml!
First the file must be imported - in your includes.xml add the line:
<include file="script-skinshortcuts-includes.xml"/>
In home.xml, add the line:
<onload>RunScript(script.skinshortcuts,type=buildxml&mainmenuID=9000&group=[groupname]|[groupname]|[groupname])</onload>
And in skinsettings.xml, the line:
<onunload>RunScript(script.skinshortcuts,type=buildxml&mainmenuID=9000&group=[groupname]|[groupname]|[groupname])</onunload>
Replace 9000 with the ID of the list you are using for the mainmenu. You should include all [groupname]'s that your skin supports, separated by a pipe. The script will then load all of the submenus, and set visibility conditions on each one.
If you are not using a main menu to choose which display group to show, you must still include a mainmenuID value, but can set this to any random value. If you want to build the mainmenu and additional standalone groups, include the group parameter with "mainmenu" as the first option.
2. Let the user manage their shortcuts
In your skinsettings.xml file, you need to create a button for each [groupname] that you want to support, with the following in the <onclick> tag
RunScript(script.skinshortcuts,type=manage&group=[groupname])
3. Display user shortcuts (single group)
In the list where you want the submenu to appear, put the following in the <content> tag:
<include>skinshortcuts-group-[groupname]</include>
4. Display user shortcuts based on another list
If your skin provides a main menu you want to display shortcuts for using the script, then you need to add an additional property to each main menu item, called submenuVisibility, containing the [groupname] of the submenu to associate with that main menu.
<property name="submenuVisibility">[groupname]</property>
Then, in the list where you want the submenu to appear, put the following in the <content> tag:
<include>skinshortcuts-submenu</include>
Resetting All Shortcuts
-----------------------
It is recommended you give users the option to reset all shortcuts to defaults within your skinsettings.xml, by including a button with the following onclick:
<onclick>RunScript(script.skinshortcuts,type=resetall)</onclick>
You can also include &warning=false if your skin provides a warning to the user before this action is carried out.
Recommended [groupname]'s
-------------------------
If providing only the sub-menu, the script uses the [groupname] property to determind which set of shortcuts to show. In order to share users customized shortcuts across different skins using this script, there are a few recommended [groupname]'s to use:
videos
movies
tvshows
livetv
radio (Helix)
music
musicvideos
pictures
weather
programs
dvd
settings
Providing default shortcuts
---------------------------
If the user has not already selected any shortcuts or if the user resets shortcuts, the script will first attempt to load defaults from a file provided by the skin before trying to load its own.
To provide this optional file, create a new sub-directory in your skin called 'shortcuts', and drop the relevant [groupname].DATA.xml file into it, or create the file manually. See "Recommended [groupname]'s" for ideas of some of the default files you may wish to provide, along with mainmenu.DATA.xml if you are using the script to manage the main menu.
The script provides defaults equivalent to Confluence's main menu and sub-menus.
The file format is simple enough:
<?xml version='1.0' encoding='UTF-8'?>
<shortcuts>
<shortcut>
<label>Label of shortcut, can be localised string</label>
<label2>Type of shortcut, can be localised string</label2>
<icon>The default icon to use for the shortcut</icon>
<thumb>The default thumbnail to use for the shortcut (optional)</thumb>
<action>The default action of the shortcut</action>
<visible>Visibility condition for the shortcut (optional)</visible>
<defaultID>The defaultID of the menu item</defaultID>
</shortcut>
</shortcuts
If you want to provide a default which links to a playlist you include with your skin, then make sure the .shortcuts file uses the special protocol (e.g. special://skin/) as the URI to it. The script will replace this with a localised version, so that the playlist link will continue to work even if the user switches to another skin supporting skin shortcuts.
Particularly when setting defaults for the main menu, you may wish to include the <defaultID> element. This will set the [groupname] of the submenu's .DATA.xml file. (e.g. defaultID of tvshows -> tvshows.DATA.xml). Please note, any defaultID must follow the standard rules - all lowercase, all english characters, no spaces.
As Skin Shortcuts will integrate with a Video Node Editor script (for skins where the script manages the full menu), it is strongly suggested that default shortcuts use video nodes rather than library shortcuts where appropriate.
For example, a link to movie titles should be:
<action>ActivateWindow(10025,videodb://movies/titles/,Return)</action>
rather than
<action>ActivateWindow(10025,MovieTitles,Return)</action>
This will ensure that any users modifying the default Movies node (for example) will access the content they expect rather than, as video library links provide, all content.
Properties returned
-------------------
Regardless of which method you use, the script will always return a list with a few standard properties:
Label Label of the item (localized where possible)
Label2 Type of shortcut
Icon Icon image
Thumbnail Thumbnail image
Property(labelID) Unlocalized string used for sub-menu and for displaying more controls depending on the main menu item
property(defaultID) Permanent form of the labelID
Property(action) The action that will be run when the shortcut is selected
Property(group) The [groupname] that this shortcut is listed from
Property(widget) If your skin uses Skin Shortcuts to manage widgets, the [widgetID] will appear here (mainmenu only)
Property(widgetName) - The display name of the widget will appear here
Property(background)If your skin uses Skin Shortcuts to manage background, the [backgroundID] will appear here (mainmenu only)
Property(backgroundName) - The display name of the widget will appear here
You can also use the script to manage any additional properties you would like. See "resources/Management Dialog.txt" and "resources/Advanced Usage.txt" - "Overrides.xml" - section 5 (Custom shortcut properties)
Note, there is an additional property - Property(hasSubmenu) - which is used by the methods used for building all menus in a single list. It should not be relied upon to determine whether there are any visible items in a submenu, as it will still return True if all items within the submenu are invisible. Suggestion is to use Container.NumItems to determine this information instead.
Display more controls depending on the mainmenu item
----------------------------------------------------
If your skin provides widgets or has custom backgrounds, you can use Skin Shortcuts to manage these. See resources/Advanced Usage.txt
Otherwise, you can set visibility of any additional controls based on the labelID of the main menu listitems property 'labelID' or 'defaultID'. For common main menu items, it will contain one of the following strings:
videos
movies
tvshows
livetv
radio (Helix)
music
musicvideos
pictures
weather
programs
dvd
settings
A full list of labelID/defaultID's can be found in the Resources folder.
Providing alternative access to settings
----------------------------------------
One of the side effects of using skinshortcuts to provide the whole main menu is that users have the ability to delete any shortcut, including those that they will later turn out to actually want. Generally, this isn't a problem as they can add them back at any time. However if they delete all links to settings, they will have no way to add it back unless your skin offers an alternative access.
Therefore, you should either include an alternative link to settings such as in the skins shutdown menu, or you can force settings to always be included in the menu - see "Advanced Usage", section "Overrides.xml" part 11
It's possible to warn the user before they remove a link to shortcuts - see "Advanced Usage", section "Overrides.xml" part 10
Skinning the management dialog
------------------------------
For details on skinning the management dialog, see resources/Management Dialog.txt.
Targeting Helix (Kodi 14)
-------------------------
There are no required changes to your implementation of Skin Shortcuts to target the upcoming release of Kodi. However, you may wish to update your PVR defaults to use the new implementation (full details on the skinning forum).
It is possible to include defaults for both Gotham and Helix in your defaults if you use the new XML format. Include a <version/> tag, with the value of either 13 or 14 for the version of Kobi for which it applies:
<version>13</version> - A default for Gotham
<version>14</version> - A default for Helix
If you have customised the order of available shortcuts in your overrides.xml, it is also possible to target both Gotham and Helix by displaying different nodes depending on the version by including the version in the node tag:
<node label="32017" condition="System.GetBool(pvrmanager.enabled)" version="13"> - A node for Gotham
<node label="32017" condition="PVR.HasTVChannels" version="14"> - A node for Helix
Advanced Usage
--------------
The script includes a number of options and features to try to make a skinners life easier, and to help customise the script for your skin.
* Manage backgrounds
* Manage widgets
* Overrides.xml
* Localisation
For details, see "resources/Advanced Usage.txt".