Theming

Theming

General

Theming is done via QSS, a Qt CSS "derivate" (basically it is css with some extensions)
Stylesheets are explained in detail in the Qt documentation so we'll just cover the BE:Shell specifics here (mainly the used classes)

Important

You can use images but you must either supply full paths ("/home/joe/images/image.png") or place them in the theme directory ("~/.kde/share/apps/be.shell/Themes/myFancyTheme/image.png") and reference them as "${base}/image.png" in the QSS theme.
Notice that this is not a Qt QSS feature, so if you try that with a theme on "dolphin --stylesheel myFancyTheme.css" that will fail!

Basics

Elements can be addressed by class, exact class (not through inheritance) or the id.

The #id is just the BE::Plugged applet name, so if you've an applet

[clock\]
Pattern='\<html\>\<small\>'dddd dd. MMM. '\</small\>\<b\> | 'hh:mm'\</b\>\</html\>'
Type=Clock

the theme could include

#clock {
    color: #aaaaaa;
    font-weight:bold;
    font-size:9pt;
    padding-bottom:2px;
    padding-left:6px;
    padding-right:12px;
    border: none;
    border-left: 2px solid #222222;
}

Classes can be selected as exact class or as matching class

• Example
  • QAbstractButton matches everything that is Button (eg. QPushButton, QToolButton, QCheckBox)
  • .QAbstractButton (notice the dot) matches QAbstractButton only (what effectively means nothing in this case)

You can also select elements that must be inside other elements:

.BE--Run QTreeWidget QScrollBar :: handle
{
    background-color: #aaaaaa;
    border: none;
    margin-left:3px;
    border-radius: 3px;
}

This matches the handle of a scrollbar inside any Treewidget inside the runner.
The "::handle" part is explained in the Qt documentation, a detailed reference on selector is provided by w3.org

BE::Shell widgets are inside the BE namespace.
Since "::" is otherwise used by css, it's replaced by a double dash "--"
That's why you've to write "BE--Run" while you actually mean "BE::Run" (in case you ever look up the code ;-)

Classes

Notice that virtually each and every applet will reside in a panel - the panel can be transparent and strutless but it will parent.
Only a trashcan and the desktop icons are directly on the desktop.

Generic items

• BE--Panel (QFrame)
  
  Well, a panel - panels have automatic names:
  • TopPanel
  • LeftTopPanel
    
    (a panel on the top, touching the left but not the right border)
  • CentralTopPanel
  • RightTopPanel
  • BottomPanel
  • LeftBottomPanel
  • CentralBottomPanel
  • RightBottomPanel
  • LeftPanel
  • TopLeftPanel
    
    (a panel on the left, touching the top but not the bottom border)
  • CentralLeftPanel
  • BottomLeftPanel
  • RightPanel
  • TopRightPanel
  • CentralRightPanel
  • BottomRightPanel
• BE--Button (QToolButton)
  
  A generic button that can be used as random trigger applet. It's also a base for other plugs
• BE--Label (QLabel)
  
  A generic label plug printing random text from random input

Notice: Toplevel panels also support two non standard css properties

• shadow-radius
• shadow-padding ([-128,127])
• shadow-border

Which allow to control (and align) the roundness of the panel and its distance from the contents rect

shadow-radius:12; /*aligns to 12px border radius*/
shadow-padding:4; /*aligns to margin:4px - eg. to create a transparent glass border effect*/
shadow-padding:8 4 20 4; /*top right bottom left*/
shadow-border:rgba(255,255,255,128) 4; /*translucent white 4 border attached to shadow, not panelpx*/

Notice: Those properties are not accurately parsed, ie.

• they can not be commented
• the value metrics is px - no matter what you write behind

The Desktop

• BE--Desk (QWidget)
  
  The Desktop (the huge thing below the wallpaper ;-)
• BE--DeskIcon (QToolButton)
  
  An icon on the desktop (in case you show them)
• BE--Pager (QFrame)
  
  A container for several QToolButtons each representing a virtual Desktop
• BE--Trash (QLabel)
  
  A trashcan icon (can also reside on BE--Desk)

The runner

• BE--Run (QDialog)
  
  The runner

Status

• BE--Battery (QFrame)
  
  A charge indicating icon
• BE--Clock (QLabel)
  
  A digital clock (random html marked up strings)
  
  The provides access to a calender which can be accessed as
  • #Calendar
    
    and that contains a
    • .KDatePicker
• BE--Volume (QLabel)
  
  
• BE--InfoCenter (QLabel)
  
  An icon showing "(i)" and pulsating when there's a new message from the system
• BE--InfoDialog (QDialog)
  
  The dialog with the system messages you get when clicking the InfoCenter
  <!--
• BE--Job (QWidget)
  
  -->

The global menu

• BE--GMenu (QFrame)
  
  A global menu (XBar server)
• BE--HMenuBar (QMenuBar)
  
  A menu in the global menu
• BE--VMenuBar (QMenu)
  
  A vertical menubar

NOTICE That the Main menu is just a plain QMenuBar resp. QMenu
To hit all menus, you may want to select as

.BE--GMenu QMenuBar

NOTICE If the menu vanishes for tight panels, try minimizing its margins and paddings

.BE--Panel QMenuBar { padding:0px; margin:0px; }
.BE--Panel QMenuBar::item { padding: 0px; margin: 0px; padding-left: 4px; padding-right: 4px; margin-right: 4px; }

The Taskbar

• BE--Tasks (QFrame)
  
  A taskbar (nearly as useless as the systray, but both were introduced win Win95 and are prominent Desktop stuff)
• BE--Task (BE::Button)
  
  A button representing a task in the taskbar
  • #NoTask
    
    There's currently no running task for this item (effectively it's a runner that can turn an ordinary task button)
  • #OneTask
    
    This item represents only one task (like in a flat taskbar)
  • #ManyTasks
    
    This item represents several tasks (stacked taskbar)

BE--Task's also can have properties, these could be addressed like

BE--Task[windowMinimized="true"]

which matches minimized tasks

• Properties are:
  • windowMinimized
  • needsAttention
• #TaskTip
  
  The idea refers to the taskbar tooltip

Meters

• BE--Meter (QFrame)
  
  A generic meter with two indicators
• BE--CpuMeter (BE::Meter)
  
  ... specialised for CPU load
• BE--RamMeter (BE::Meter)
  
  ... specialised for memory usage
• BE--NetMeter (BE::Meter)
  
  ... specialised for network traffic
• BE--HddMeter (BE::Meter)
  
  ... specialised for I/O load

NOTICE
For some reason I unfortunately don't know atm, Meters CAN NOT BE SELECTED BY CLASS - seelct them by #id instead:

[RAM]
Mode=NonInactive
PollInterval=5000
Type=RamMeter

and in the theme

#RAM { color: white; }

The rest

• BE--SysTray (QFrame)
  
  A place where applications dump little outposts - most of them rather pointless and nasty
• BE--MediaTray (QFrame)
  
  A container for attached devices (DvD, USB stick, Camera, ...)
• BE--Device (QToolButton)
  
  Icon representation of such attached Hardware
• BE--Session (QToolButton)
  
  A button with your login (or name) and a menu to control the session (lock, logout, shutdown, stuff like that)