Guest User


a guest
Mar 26th, 2012
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. Guide to writing Rockbox Skins
  2. ------------------------------
  4. 1 Introduction
  5. ----------------
  6. Rockbox has an ever-evolving themeing engine which allows you to
  7. theme most of the major screens. Blaa blaa
  9. 1 The basics
  10. --------------
  12. Rockbox skins are simple text files a different extension depending
  13. on which type of skin the file should be loaded to (i.e *.wps* for the
  14. WPS, *.sbs* for the main menus and browsers, etc).
  16. For the sake of simplicity all explanations assume we are talking about
  17. the WPS, but just about all tags work equally well in any screen (with
  18. some obvious exceptions.)
  20. 1.1 Tags
  21. ----------
  23. The entire system is built around the idea of *tags*. Tags in skins
  24. are a % followed by one or more letters (case sensitive) which are used
  25. as placeholders for actual data (usually text being displayed).
  27. For example::
  28. %ia - %it
  29. Will display the current track's artist (%ia) a - and the current tracks
  30. title (%it).
  32. Tags can also have parameters (%xd(foo, 1) ) which are simply comma
  33. seperated (with spaces between items being optional, however *strongly*
  34. recommended for readability.)
  36. Finally, some characters are special (i.e %) so they need to be 'escaped'
  37. to display. %% will display % on the screen.
  39. Any other text which the parser doesn't recognise as tags will siply be
  40. displayed on the screen as static text.
  42. 1.2 Lines
  43. -----------
  45. Each line in the skin file is equivilant to a line on the display.
  46. A *very* limited set of tags will break this behaviour by forcing the
  47. next line to show up on the current line, but this can be mostly ignored.
  49. Lines can also swap between various sets of tags (or text) using *sublines*.
  51. Sublines are simply sets of tags seperated by a semi-colon (;).
  52. Each subline will be displayed for 2 seconds unless the *timeout* tag
  53. is used to change that value. (%t(timeout)).
  55. Lines by default are static. If the line doesn't fit in the display
  56. it will not scroll unless the %s tag is used to tell it to scroll.
  58. 1.2.1 Text alignment
  59. --------------------
  61. Text is always drawn from the left of the display however tags are provided
  62. to position the text on the left, middle or right of the display.
  64. %al
  66. 1.3 Conditionals
  67. ------------------
  69. Most tags can have more than one value. %ia (current track artist)
  70. comes from the file which may not have that value set. When that happens
  71. %ia will show nothing, so you could end up with a line like::
  72. 01 - - Some song!
  73. To only display a tag if the tag has a value we use conditionals.
  74. Conditionals are in the form::
  75. %?xx<values>
  76. where xx is the tag name and values is a pipe (|) seperated list of
  77. lines (possibly including sublines) to display depending on the value
  78. of the tag. For text tags the "value" is either "has text" or "no text/blank".
  79. Examples::
  80. %?ia<%ia>
  81. Will only display the track artist if it is avialable.
  83. %?ia<%ia|No artist>
  84. Will display "No artist" if it isnt available.
  86. %?mm<Off|All|One|Shuffle|A-B>
  87. Will show the text representation for each of the repeat modes.
  89. This syntax can be difficult to read when the number of options is
  90. more than a few so the *%if()* tag is an alternative::
  91. %?if(%mm, >=, 1)<Repeat enabled>
  92. will display "Repeat enabled" if any repeat mode is enabled.
  94. Conditionals can of course be nested::
  95. %?ia<%?it<%ia - %it|%ia>|%fm;%fb>
  96. Will display "Artist - Title" of both are present, or just Artist if
  97. artist is present but title isnt. If neither are present the line will
  98. alternate between the filename and the files bitrate.
  100. 2.0 Viewports
  101. -------------
  103. Normally the skin will cover the entire display and each line in the
  104. file represents the equivilant line in the display. Using viewports
  105. allows you to position the text lines anywhere on the screen.
  107. By default every skin has an initial viewport which covers the full
  108. screen and uses the font specified in the settings. This viewport will
  109. not draw anything if any other viewports are specified.
  111. 2.1 Declaring Viewports
  112. -----------------------
  114. ::
  115. %V(x, y, width, height, font id)
  117. Where:
  118. *x* is the x pixel of the rectangle to draw in.
  119. *y* is the y pixel of the rectangle to draw in.
  120. *width* is the width of the rectangle.
  121. *height* is the height of the rectangle.
  122. *font id* is the font number to use for the viepworts text (1 means UI font).
  124. For example::
  125. %V(0, 100, 50, 50, 1)
  126. will create a viewport with the top left corner at (0,100) and bottom
  127. right corner at (50, 150).
  129. Once a viewport is declared all lines following it (untill the next viewport)
  130. will be drawn in this rectangle.
  132. 2.2 Conditional Viewports
  133. -------------------------
  135. You may want to display
RAW Paste Data Copied