As noted earlier, in most cases you will want to derive from KThemeStyle when making new themed widget styles. Nonetheless, KThemeStyle derives this class so it's important to be familiar with it's methods. The class is fully documented, but some parts deserve a little extra attention:
The WidgetType enum
This enum lists all the widgets available to the theme plugin, with many having their own normal and down state entries. Most KThemeBase routines take this enum as a parameter and do the proper thing based on that widget's configuration. To handle widgets with multiple states you do something like:
someMethod(sunken ? PushButtonDown : PushButton);
These are the most frequent methods you will use to get per-widget configuration. They are pretty self-explanatory, but make sure you are familiar with them.
This routine takes a default colorgroup reference and a widget type and will return either the colorgroup specified by the theme if one is set or a pointer to the colors you supplied otherwise. Colorgroups are only allocated if the user specifies their own colors, so this avoids having to check if they are allocated or not. Since almost all style routines supply a default colorgroup as a parameter you can usually just use that when calling this method.
This method is very important. It will return a pixmap for the given size while transparently accessing the user's pixmap scaling and gradient settings. Thus you will use this to get both pixmaps and gradients. It also transparently utilizes the cache, so you don't have to worry about that either. It is important to note that the pixmap returned may be smaller than the requested size if it's configured to be Tiled, so use drawTiledPixmap when drawing. Also, this should only be used for resizable widgets. Fixed sized ones should use uncached().
You will usually use borderWidth() to get the size of the borders, draw them, then call isPixmap() and either QPainter::drawTiledPixmap() what this returns if true or QPainter::fillRect() the default fill if false.
This returns a uncached pixmap. This is mostly for fixed-sized widgets, where the uncached pixmap will be the original one. For resizable widgets it will be the last modification made so is not as useful. Use scale() in that case.
Now here is the full API documentation for KThemeBase:
|
|
This is a base class for KDE themed styles. It implements a cache, configuration file parsing, pixmap scaling, gradients, and a lot of inline methods for accessing user specified parameters.
Note that this class *does not* actually implement any themes. It just provides the groundwork for doing so. The only reason to use this class directly is if you plan to reimplement all of the widgets. Otherwise, refer to KThemeStyle for a fully themed style you can derive from.
KThemeBase (const QString &configFile) |
Constructs a new KThemeBase object.
enum ScaleHint {FullScale, HorizontalScale, VerticalScale, TileScale} |
Describes if a pixmap should be scaled fully, horizontally, vertically, or not at all and tiled.
enum ArrowStyle {MotifArrow, LargeArrow, SmallArrow} |
The default arrow types.
enum ShadeStyle {Motif, Windows, Next} |
The default frame shading styles.
enum SButton {SBBottomLeft, SBBottomRight, SBOpposite} |
The default scrollbar button layout. BottomLeft is like what Next uses, BottomRight is like Platinum, and Opposite it like Windows and Motif.
enum Gradient {GrNone, GrHorizontal, GrVertical, GrDiagonal, GrPyramid, GrRectangle, GrElliptic, GrReverseBevel} |
The gradient types. Horizontal is left to right, Vertical is top to bottom, and diagonal is upper-left to bottom-right.
enum WidgetType {PushButton=0, ComboBox, HScrollBarSlider, VScrollBarSlider, Bevel, ToolButton, ScrollButton, HScrollDeco, VScrollDeco, ComboDeco, MenuItem, InactiveTab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, PushButtonDown, ComboBoxDown, HScrollBarSliderDown, VScrollBarSliderDown, BevelDown, ToolButtonDown, ScrollButtonDown, HScrollDecoDown, VScrollDecoDown, ComboDecoDown, MenuItemDown, ActiveTab, SunkenArrowUp, SunkenArrowDown, SunkenArrowLeft, SunkenArrowRight, HScrollGroove, VScrollGroove, Slider, SliderGroove, IndicatorOn, IndicatorOff, ExIndicatorOn, ExIndicatorOff, HBarHandle, VBarHandle, ToolBar, Splitter, CheckMark, MenuBar, DisArrowUp, DisArrowDown, DisArrowLeft, DisArrowRight, ProgressBar, ProgressBg, MenuBarItem, Background} |
This provides a list of widget types that KThemeBase recognizes.
ScaleHint scaleHint (WidgetType widget) |
The scaling type specified by the KConfig file.
Parameters:
widget | A Widgets enum value. |
Returns: A ScaleHint enum value.
Gradient gradientHint (WidgetType widget) |
The gradient type specified by the KConfig file.
Parameters:
widget | A Widgets enum value. |
Returns: A Gradient enum value.
const QColorGroup* colorGroup (const QColorGroup &defaultGroup, WidgetType widget) |
The color group specified for a given widget. If a color group is set in the theme configuration that is used, otherwise defaultColor is returned.
Parameters:
defaultColor | The colorGroup to set if one is available. |
widget | The widget whose color group to retrieve. |
bool isPixmap (WidgetType widget) |
True if the widget has a pixmap or gradient specified.
bool isColor (WidgetType widget) |
True if the widget has a color group specified.
bool is3DFocus () |
True if the user specified a 3D focus rectangle
int focusOffset () |
If the user specified a 3D focus rectangle, they may also specify an offset from the default rectangle to use when drawing it. This returns the specified offset.
int borderWidth (WidgetType widget) |
The border width of the specified widget.
int pixBorderWidth (WidgetType widget) |
Pixmap border width of the specified widget.
KThemePixmap* borderPixmap (WidgetType widget) |
Returns the border pixmap if enabled for the specified widget. This will contain the originial pixmap, plus the edges separated in KThemePixmap::border() if valid. If invalid it will return NULL.
int highlightWidth (WidgetType widget) |
The highlight width of the specified widget.
int decoWidth (WidgetType widget) |
The border plus highlight width of the widget.
int getSBExtent () |
The extent (width for vertical, height for horizontal) requested for the scrollbars.
SButton scrollBarLayout () |
The scrollbar button layout.
ArrowStyle arrowType () |
The arrow type.
ShadeStyle shade () |
The shading type.
int frameWidth () |
The frame width.
int splitWidth () |
The splitter width.
int bevelContrast (WidgetType widget) |
The contrast for some bevel effects such as reverse gradient.
int buttonXShift () |
The button text X shift.
int buttonYShift () |
The button text Y shift.
int sliderButtonLength () |
Returns either the slider length of the slider pixmap if available, otherwise the length specified in the config file.
bool roundButton () |
True if rounded buttons are requested.
bool roundComboBox () |
True if rounded comboboxes are requested.
bool roundSlider () |
True if rounded slider grooves are requested.
bool activeTabLine () |
True if a line should be drawn on the bottom of active tabs.
bool inactiveTabLine () |
True if a line should be drawn on the bottom of inactive tabs.
KThemePixmap* uncached (WidgetType widget) |
Returns the current uncached pixmap for the given widget. This will usually be either the last scaled or gradient pixmap if those have been specified in the config file, the original pixmap if not, or NULL if no pixmap has been specified.
KThemePixmap * scalePixmap (int w, int h, WidgetType widget) |
Returns the pixmap for the given widget at the specified width and height. This will return NULL if no pixmap or gradient is specified. It may also return a different sized pixmap if the scaling is set to Tiled. When using this method, you should call it using the needed width and height then use QPainter::drawTiledPixmap to paint it. Doing this, if the pixmap is scaled it will be the proper size, otherwise it will be tiled.
Parameters:
w | Requested width. |
h | Requested height. |
widget | Widget type. |
Returns: The pixmap or NULL if one is not specified.
void applyConfigFile (const QString &file) |
This method reads a configuration file and applies it to the user's kstylerc file. It does not signal applications to reload via the KDEChangeGeneral atom, if you want to do this you must do so yourself. See kcmdisplay's general.cpp for an example.
Parameters:
file | The configuration file to apply. |
QImage* image (WidgetType widget) |
Returns a QImage for the given widget if the widget is scaled, NULL otherwise. QImages of the original pixmap are stored for scaled widgets in order to facilitate fast and accurate smooth-scaling. This also saves us a conversion from a pixmap to an image then back again.
QColor* gradientHigh (WidgetType widget) |
Returns the gradient high color if one is specified, NULL otherwise.
QColor* gradientLow (WidgetType widget) |
Returns the gradient low color if one is specified, NULL otherwise.
void readConfig (Qt::GUIStyle colorStyle = Qt::WindowsStyle) |
Reads in all the configuration file entries supported.
Parameters:
colorStyle | The style for the color groups. In KDE, colors were calculated a little differently for Motif vs Windows styles. This is obsolete. |
QColorGroup* makeColorGroup (QColor &fg, QColor &bg, Qt::GUIStyle style = Qt::WindowsStyle) |
Makes a full color group based on the given foreground and background colors. This is the same code used by KDE (kapp.cpp) in previous versions.
KThemePixmap* loadPixmap (QString &name) |
Attempts to load a pixmap from the default KThemeBase locations.
QImage* loadImage (QString &name) |
Attempts to load a image from the default KThemeBase locations.