While I am waiting on the ability to submit this patch, I figured i'd spend some time discussion how to use the function.
The new function is:
Container.SetSortMethod(methodID)
Sets the container's sorting method to the specified method. methodID is an integer value between 0 and 29 indicating what sort method should be applied to the container. There are currently 30 sort methods in XBMC but they are NOT all available at the same time. What sort method's are available will depend on what media is currently in the container. Passing a method that is not available will simply have no result. IE it won't hurt anything.
Skinners can use Container.Content(contentType) in <visible> tags to try and filter only the proper sort methods. It will however be necessary for us to build a decent table of what methods are available for what media. I'm hoping we can get a wiki page to document this, since it is rather in depth.
From my own testing when writing this function I do know that when the media is Video Library, TV Titles, then the available sort methods are IDs 1, 7, & 16. This is "Name", "Episodes", and "Year".
Here is the table that I built to get things started off, but it will have to be documented nicer at some point:
Code:
methodID method name Button Label
0 SORT_METHOD_NONE
1 SORT_METHOD_LABEL Name
2 SORT_METHOD_LABEL_IGNORE_THE Name
3 SORT_METHOD_DATE Date
4 SORT_METHOD_SIZE Size
5 SORT_METHOD_FILE File
6 SORT_METHOD_DRIVE_TYPE Type
7 SORT_METHOD_TRACKNUM Track, Episodes
8 SORT_METHOD_DURATION Time
9 SORT_METHOD_TITLE Title
10 SORT_METHOD_TITLE_IGNORE_THE Title
11 SORT_METHOD_ARTIST Artist
12 SORT_METHOD_ARTIST_IGNORE_THE Artist
13 SORT_METHOD_ALBUM Album
14 SORT_METHOD_ALBUM_IGNORE_THE Album
15 SORT_METHOD_GENRE Genre
16 SORT_METHOD_VIDEO_YEAR Year
17 SORT_METHOD_VIDEO_RATING Rating
18 SORT_METHOD_PROGRAM_COUNT Play Count, Usage
19 SORT_METHOD_PLAYLIST_ORDER Playlist
20 SORT_METHOD_EPISODE Episode
21 SORT_METHOD_VIDEO_TITLE Title, Name
22 SORT_METHOD_PRODUCTIONCODE Prod Code
23 SORT_METHOD_SONG_RATING Rating
24 SORT_METHOD_MPAA_RATING Rating
25 SORT_METHOD_VIDEO_RUNTIME Time
26 SORT_METHOD_STUDIO Studio
27 SORT_METHOD_STUDIO_IGNORE_THE Studio
28 SORT_METHOD_UNSORTED Default
29 SORT_METHOD_MAX
Note regarding "Ignore The". In skin settings the user has an option to "Ignore The" when sorting. Many of the sort methods are duplicated, one for ignoring "the", and one for not. This adds a layer of complexity to things, but in order to make it easier on the skinning, I wrote the function so that it translates internally. For example, to sort do a SORT_METHOD_LABEL you can specify either 1, or 2 as the methodID. Either ID will work because the function will simply convert it as needed based on the user's setting.
I'll see about getting a wiki page for this so we can have some proper and clean documentation.