======Theming Photivo’s GUI======

To achieve its unique look and the ability to switch between different themes Photivo mostly relies on Qt’s styling abilities around ''QPalette'', ''QStyle'' and QSS stylesheets. On top of that ''ptTheme'' has its own stylsheet format and parser to avoid duplicated stylesheets and define colour variables in one single place instead of putting the actual colour values wherever you need them.

<note>At the moment it is not possible to add new themes without making changes to the C++ source code as well. You can alter the existing themes, but consider this to be at your own risk.</note>


====Theme Tweaking with Custom Stylesheets====

To tweak some aspects of a theme without touching the “official” theming files the best way is to use a custom QSS stylesheet. QSS is Qt’s version of the web world’s CSS stylesheets. Basically it’s CSS with several Qt specific additions.

Assuming you know a bit about CSS, a good place to start is the [[http://qt-project.org/doc/qt-4.8/stylesheet.html|Qt Stylesheet documentation]]. For writing a custom stylesheet you’ll want to keep the [[http://qt-project.org/doc/qt-4.8/stylesheet-reference.html|style sheets reference]] and [[http://qt-project.org/doc/qt-4.8/stylesheet-examples.html|examples]] handy. Also the //Photivo.qss// file in Photivo’s //Themes// subfolder is a good reference. There the major part of Photivo’s built-in themes are defined.

Things to keep in mind:
  * To load a custom theme file go to //Settings › Theming// in Photivo and load the file via the //Open// button to the left of the two theme combo boxes.
  * A custom stylesheet is an addition to the style you choose in the //Theming// section.It is intended to tweak an existing theme. Most likely you won’t be able to build a completely new theme this way.
  * The ''$Colourname$'' variables you see in //Photivo.qss// do not work in custom stylesheets. You must use the actual colour values themselves.


====Photivo Themes Explained====
A Photivo theme consists of a ''.ptheme'' file defining variables and one or more ''.qss'' files defining the actual style rules. For example the default //Dark grey// style is defined in //DarkGrey.ptheme//, //Photivo.qss//, //Photivo.windows.qss// and //Photivo.linux.qss//.

<note warning>Photivo’s theme files are not intended to be edited by users. The theme parser is not error tolerant! It will break quickly if you don’t stick to the rules.</note>

  * Except comments a .ptheme file consists of an ''@Variables'' section followed by an ''@import'' command. Both are mandatory.
  * Multiple ''@Variables'' or ''@import'' are not allowed.
  * Comments are only allowed at the start of the file before the ''@Variables'' section. Do not use comments anywhere else!
  * Comments must be the slash-star type, i.e. starting with ''/*'' and ending with ''*/''. They can span multiple lines.
  * Everything is case sensitive.
  * Theme and qss files are assumed to be UTF-8 encoded.
  * Always use the forward slash “''/''” as path delimiter.
  * ''.ptheme'' files must reside in ''<PhotivoProgramFolder>/Themes''

The ''@Variables'' section defines global color values and paths to graphical elements. Access them anywhere in the QSS as ''$VariableName$''.
  * Always define ALL the colors.
  * You MUST use ''#rrggbb'' notation compatible with ''QColor::name()''
  * For graphics, paths can be Qt resource paths or real file paths. File paths may be 
    absolute or relative to the ''.qss'' file’s location.

The ''@import'' specifies the theme’s QSS files.
  * Only give the file name without the extension, i.e. for “Photivo.qss” write “Photivo”.
  * The file name may include a path. Paths may be absolute or relative to the ''.ptheme'' file’s location.
  * The file extension for all QSS files must be ''.qss'' (lower case).
  * Avoid additional ''@import'' rules in the QSS files themselves. You cannot use the variables from the ''@Variables'' section in additionally imported files.
  * Platform specific settings are supported in additional QSS files. For example “Photivo.qss” may be accompanied by “Photivo.windows.qss”, “Photivo.linux.qss” and “Photivo.mac.qss”. If present the parser appends additional files to the end of the main style file depending on the platform Photivo was compiled for.