Warning, /plasma/oxygen-gtk/README is written in an unsupported language. File is not indexed.

0001 Oxygen-Gtk is a port of the default KDE widget theme (Oxygen), to gtk.
0002 
0003 It's primary goal is to ensure visual consistency between gtk and qt-based applications running under kde. A secondary objective is to also have a stand-alone nice looking gtk theme that would behave well on other Desktop Environments.
0004 
0005 Unlike other attempts made to port the kde oxygen theme to gtk, this attempt does not depend on Qt (via some Qt to Gtk conversion engine), nor does render the widget appearance via hard coded pixmaps, which otherwise breaks everytime some setting is changed in kde.
0006 
0007 Contents:
0008 ---------
0009 
0010 I. Introduction
0011 
0012 II. Install
0013 
0014 III. Hacks
0015 III.1 ARGB support
0016 III.2 DBus support
0017 III.3 Window grabbing
0018 III.4 Window background
0019 III.5 GtkTreeView
0020 III.6 GtkScrolledWindow
0021 III.7 Button order in dialogs
0022 III.8 Mouse-over support
0023 III.9 Tab close buttons
0024 III.10 Combobox list resize
0025 III.11 Inner shadows
0026 
0027 IV. Technical details
0028 IV.1 Directories
0029 IV.2 Some details on some files in src
0030 IV.3 Some details on some files in animations
0031 
0032 V. Example configuration (aka: how to select the oxygen-gtk style)
0033 
0034 VI. How to determine oxygen-gtk version
0035 
0036 I. introduction
0037 ---------------
0038 
0039 Oxygen-Gtk is a port of the default KDE widget theme (Oxygen) to GTK.
0040 
0041 Its primary goal is to ensure visual consistency between gtk-based and qt-based applications running under KDE. A secondary objective is to also have a stand-alone nice looking gtk theme that would behave well on other Desktop Environments.
0042 
0043 Unlike other attempts made to port the KDE oxygen theme to gtk, this attempt does not depend on Qt (via some Qt to Gtk conversion engine), nor does render the widget appearance via hard coded pixmaps, which otherwise breaks everytime some setting is changed in KDE.
0044 
0045 II. install
0046 -----------
0047 see the INSTALL file in top-level directory
0048 
0049 III. Hacks
0050 ----------
0051 This section describes some of the hacks we used in oxygen-gtk to make the style match its Qt/Kde counterpart better.
0052 These details are given here because:
0053 
0054 - they might cause crashes or rendering glitches for some apps (at least until we fix it, once aware of it)
0055 - they might cause some widgets to behave differently from what application designers might have expected 
0056 
0057 III.1 ARGB support
0058 ------------------
0059 
0060 Oxygen-gtk renders menus tooltips, drowdown lists, using ARGB (semi-transparent) colormaps. This is needed to have nice non-pixelated rounded corners, as in Oxygen-Qt, and semi-transparent background for tooltips, when compositing is enabled.
0061 
0062 Since release 1.0.2, only the colormap for the windows corresponding widgets mentionned above are modified. The colormap for all other windows (notably main windows and dialogs), are unchanged. Unlike with previous relieses of Oxygen-gtk, this now works for 99% of the applications (with firefox and company being the only exception we are aware of). 
0063 
0064 In case this still causes issues (typically: crashes, or menus not being rendered properly) for applications that we have not tested, we provide a way to black-list applications (so that ARGB support is not enabled). 
0065 
0066 The full list of black-listed applications is in rc/argb-apps.conf, and is usually installed at:
0067 
0068   /usr/share/themes/oxygen-gtk/gtk-2.0/argb-apps.conf
0069 
0070 There is also a per-user config file usually in 
0071 
0072   $HOME/.config/oxygen-gtk/argb-apps.conf
0073 
0074 This file will be parsed AFTER the system-wide one, thus allowing the user to override SOME or ALL of the rules set in the system-wide file. I.e., using "disable:all" as a first statement in the per-user config file will make system-wide one inactive.
0075 
0076 It can be edited by the user to add (or remove) new applications in case we overlooked some. 
0077 The syntax used to add/remove an application in the black-list is described in the argb-apps.conf file.
0078 When there is a need to add new applications, user should also post it in this bug: https://bugs.kde.org/show_bug.cgi?id=260640 so that it also gets added in the distributed code.
0079 
0080 There are some environment variables to help debug ARGB hack:
0081 
0082   OXYGEN_DISABLE_ARGB_HACK - set it to 1 to check if app will crash without the hack. Oxygen-GTK will print app name to report.
0083   OXYGEN_ARGB_DEBUG - set it to 1 to print all debug information concerning ARGB hack (mainly to debug blacklist logic).
0084   OXYGEN_DISABLE_INNER_SHADOWS_HACK - set it to 1 to disable inner shadows hack, which might make some widgets render in a wrong way or not render at all
0085 
0086 III.2 DBus support
0087 ------------------
0088 Provided that dbus-glib-1 is found on the system, oxygen-gtk is compiled with DBus support. This allows gtk applications to be updated automatically when kde (or oxygen) configuration is changed. This covers:
0089 - changing the color scheme
0090 - changing icon theme and sizes
0091 - changing oxygen style options, like the number and position of scrollbar arrows
0092 - ...
0093 
0094 The style still compiles (and runs) when dbus support is not found, but the feature above is missing, naturally.
0095 
0096 So far we have encountered no issue with this feature.
0097 
0098 III.3 Window grabbing
0099 ---------------------
0100 
0101 Oxygen-gtk supports the oxygen-qt feature that one can grab a window from any empty area and move it around as one usually does from the window decoration. The detection of 'empty' areas is quite tedious, but works well for all the applications we have tested so far. It is based mostly on main windows (or dialogs) recieving mouse button press/release events, assuming that no other child widget had any use of such events and thus allowing oxygen-gtk to use such events for moving the window.
0102 
0103 It might unfortunately happen that some widgets (so far unknown to us) make use of a mouse button press/release events and still pass them to their parent window, in which case the window-grab feature will conflict with the widget's usage of the event.
0104 
0105 If this happens, user should 
0106 - disable window-grab (using the oxygen-qt's configuration tool; called 'oxygen-settings'), to be able to still use the faulty application
0107 - file a bug report and wait for the bug to be fixed.
0108 
0109 III.4 Window background
0110 -----------------------
0111 
0112 Oxygen uses gradients for windows and menus background (there is a linear vertical gradient, and a radial gradient at the center of the window's top part) that match the window decoration's background. Some widgets however, paint their own flat background, without any possibility for the style to overwrite these, which results in plain flat squares being painted in the middle of the otherwise well-matched background. 
0113 
0114 Unfortunately in most cases, there is not much we can do about it. This is most likely either a missing feature on the gtk style (letting the style render the widget's background), or an ill-design of the widget itself.
0115 
0116 III.5 GtkTreeView
0117 -----------------
0118 
0119 Tree-lines are rendered by default on all tree-views (unless it is disabled in oxygen-qt's configuration tool).
0120 However, in order to have 'solid' grey lines instead of dotted black lines (provided by Gtk, with no way for the style to change it), we completely rewrote the tree-line drawing code (and disabled Gtk's equivalent code). This also allowed us to change the placement of the tree expander and the lines, so that they match Qt. 
0121 So far we have encountered no issue with this feature.
0122 
0123 III.6 GtkScrolledWindow
0124 -----------------------
0125 
0126 For scrolled windows that contain a GtkTreeView, we force the frame to be sunken. This is consistent with Qt, and allows us to properly render mouse-over and focus effects on such lists. There might be some specific widget's layouts however for which this results in rendering glitches (for instance, two sunken frames one embedded in the other). If you observe such things, please report and we'll fix. 
0127 
0128 III.7 Button order in dialogs
0129 -----------------------------
0130 
0131 We changed the button order in dialogs so that it matches the Qt convention. Notably, "accept" buttons are usually located 'left-of' "cancel" buttons. This choice was driven to improve consistency accross applications, although it might disorient Gnome users.
0132 
0133 III.8 Mouse-over support
0134 ------------------------
0135 
0136 We added mouse-over support (that is: highlight when mouse pointer enters the widget) for a number of widgets for which gtk did not support it. This is notably the case for: GtkTreeView, GtkEntry, GtkNoteBook. This is achieved by watching enter/leave and mouse-move events for such widgets and some of their children. To our knowledge there is no remaining issue with this feature.
0137 
0138 III.9 Tab close buttons
0139 -----------------------
0140 
0141 GTK notebook doesn't provide a standard way for apps to put close buttons on tabs. Because of this, close buttons in different apps are implemented differently. Oxygen-gtk hides such buttons' icons/text, and draws Qt close button images instead. But there's no way of detecting if the button is really _close_ one. So, current implementation may break apps which have some additional buttons in the tabs. If you find such apps with multiple buttons on single tab (which all look like close buttons) when using oxygen-gtk, file a bug report.
0142 
0143 III.10 Combobox list resize
0144 ---------------------------
0145 
0146 We haven't figured out any way to draw combobox button glow outside of the button widget, so the button is drawn reduced by glow dimensions. This leads to combobox list not match button in size (it's 6px wider than the button). To make popped-up combobox look nicer, we resize it on each popup.
0147 This may result in flicker, so if it's undesirable, this hack can be disabled this in CMakeLists.txt: set ENABLE_COMBOBOX_LIST_RESIZE to 0 instead of default 1.
0148 
0149 III.11 Inner shadows
0150 --------------------
0151 
0152 To implement inner shadows so that they get inside their child windows, we make children windows composited (gdk_window_set_composited()).
0153 This may lead to inexpected effects such as not rendered (or rendered as garbage) children of GtkScrolledWindow and GtkViewport.
0154 Currently no such problems are known.
0155 To disable this hack, set ENABLE_INNER_SHADOWS_HACK to 0 in CMakeLists.txt.
0156 
0157 Note: this feature requires gtk version 2.24.2 or later.
0158 
0159 
0160 IV. Technical details
0161 ---------------------
0162 
0163 Oxygen-Gtk is written in c++ (but makes only 'c' style calls to Gtk methods).
0164 This section provides some details about the files and classes structure of oxygen-gtk.
0165 
0166 IV.1. Directories:
0167 ------------------
0168 
0169 rc/ contains 'default' configuration files
0170 src/ contains all the source code.
0171 src/animations/ contains code needed for hover/focus effects, and will contain code for smooth animations. 
0172 It connects to various widgets signals and events to setup and trigger widget updates when appropriate conditions are fullfilled.
0173 
0174 IV.2. Some details on some files in src/
0175 ----------------------------------------
0176 
0177 oxygenrcstyle:
0178 oxygenstylewrapper: 
0179 are the core gtk style files. Oxygenstylewrapper wraps all gtk painting calls to oxygenstyle singleton painting class.
0180 
0181 oxygenstyle:
0182 does all the painting, as called by oxygenstylewrapper
0183 
0184 oxygenstylehelper: 
0185 contains some lower level painting classes, that depend on cairo context, and not on gtk windows/widgets any more. It is also responsible for generating the tilesets.
0186 
0187 oxygentileset:
0188 stores 3x3 pixmap array to handle scalable widgets, similar to what KDE/plasma does (as well as oxygen-qt)
0189 These tilesets are cached using home-made stl-based cache containers can be cached.
0190 
0191 oxygenwindowmanager: handles window grabbing
0192 
0193 oxygenrgba:
0194 stores rgba color representation and has some conversion utility functions, mostly imported from KDE/Qt.
0195 
0196 oxygencolorutils:
0197 all color handling, used to shade, mix, blend, etc. It is based on code in oxygen-qt and kde/kdelibs/kdeui kcolorutils and kcolorscheme.
0198 
0199 oxygenpalette: 
0200 internal storage of colors. It extends the colors used by gdk and passed via gtkstyle
0201 
0202 oxygenqtsettings:
0203 does all the handling of Qt/Kde options, and conversion to gtk options where needed
0204 
0205 oxygengtkicons:
0206 is responsible for mapping/replacing gtk icons by oxygen icons. This is largely inspired from QtCurve-gtk
0207 
0208 utility files/classes:
0209 oxygengeometry.h: some low-level geometry classes
0210 oxygencairocontext: a self-freed wrapper around cairo_context_t;
0211 oxygencairopattern: a self-freed wrapper around cairo_pattern_t;
0212 oxygencache: some stl based implementation of a fifo cache and a mru cache;
0213 oxygencairoutils: some cairo/gdk-cairo utilities 
0214 oxygengtkdetail: wrapper around the 'detail' strings passed to painting routines
0215 oxygengtkutils: some widget/window ancestry tree navigation utility functions.
0216 oxygenflags: generic utility class to handle enumeration based bit patterns, inspired from the QFlag Qt class.
0217 oxygentaboptions: stores options relevant for tab rendering in notebooks.
0218 oxygenstyleoptions: stores generic options for widget rendering, based on their state, shadow, etc.
0219 
0220 IV.3. some details on some files in animations/
0221 -----------------------------------------------
0222 
0223 All types of animations (mostly mouse-over effects for the moment) have two classes:
0224 - a Data class, that stores widget specific information on a per widget basis
0225 - an Engine class, that collects all Data objects and map them to their matching GtkWidget. When a GtkWidget is destroyed, the corresponding entry in the map is removed. 
0226 
0227 All engines are stored inside the oxygenanimations class, and owned by it.
0228 All engines must derive from Oxygen::BaseEngine, to be stored inside Animations.
0229 For convenience and to minimize redundant code, an Oxygen::GenericEngine class is used as a base class for most engines.
0230 
0231 For a "Data" object to be used in an engine, it must contain a "::connect(GtkWidget*)" and a "::disconnect(GtkWidget*)" class. 
0232 These two methods are responsible for the initialization and clean-up of the Data object.
0233 
0234 utility files/classes:
0235 oxygendatamap: 
0236 keeps track of association between widgets and data objects. It also keeps track of the last accessed widget, in case it is re-used immediately; for optimization.
0237 
0238 oxygentimer:
0239 a convenience class to handle delayed actions.
0240 
0241 oxygensignal: 
0242 a convenience class to handle signal/callback connections and disconnections.
0243 
0244 V. Example configuration (aka: how to select the oxygen-gtk style)
0245 ------------------------------------------------------------------
0246 Below is a 'sample' .gtkrc-2.0 file used to select oxygen-gtk for a style. 
0247 For kde users this should be copied to $HOME/.gtkrc-2.0-kde
0248 For others, in $HOME/.gtkrc-2.0 (or make a soft-link to the file above).
0249 It is provided here without any warranty, and users should backup their old config file before modifying.
0250 It is unclear whether this file will work for all configurations, all desktop environments and all systems (your distribution and DM would know better). On the other hand it has worked (by experience) in many cases.
0251 
0252 ----- begin of file ------
0253 include "/usr/share/themes/oxygen-gtk/gtk-2.0/gtkrc"
0254 
0255 style "user-font"
0256 {
0257         font_name="Sans Serif"
0258 }
0259 widget_class "*" style "user-font"
0260 
0261 gtk-theme-name="oxygen-gtk"
0262 gtk-font-name="Sans Serif 8"
0263 ----- end of file -----
0264 
0265 VI. How to determine oxygen-gtk version
0266 ---------------------------------------
0267 If you have installed oxygen-gtk from source, then deleted the sources, you can still determine oxygen-gtk version when needed using either of these commands:
0268 oxygen-gtk-demo --version
0269 oxygen-gtk-deco --version