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.

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 Qt Stylesheet documentation. For writing a custom stylesheet you’ll want to keep the style sheets reference and 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.

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.

• 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.