docs/linux_gtk_theme_integration.md

   1 # Linux GTK Theme Integration
   2
   3 The GTK+ port of Chromium has a mode where we try to match the user's GTK theme
   4 (which can be enabled under Wrench -> Options -> Personal Stuff -> Set to GTK+
   5 theme). The heuristics often don't pick good colors due to a lack of information
   6 in the GTK themes.
   7
   8 Starting in Chrome 9, we're providing a new way for theme authors to control our
   9 GTK+ theming mode. I am not sure of the earliest build these showed up in, but I
  10 know 9.0.597 works.
  11
  12 ## Describing the previous heuristics
  13
  14 The frame heuristics were simple. Query the `bg[SELECTED]` and `bg[INSENSITIVE]`
  15 colors on the `MetaFrames` class and darken them slightly. This usually worked
  16 OK until the rise of themes that try to make a unified titlebar/menubar look. At
  17 roughly that time, it seems that people stopped specifying color information for
  18 the `MetaFrames` class and this has lead to the very orange chrome frame on
  19 Maverick.
  20
  21 `MetaFrames` is (was?) a class that was used to communicate frame color data to
  22 the window manager around the Hardy days. (It's still defined in most of
  23 [XFCE's themes](http://packages.ubuntu.com/maverick/gtk2-engines-xfce)). In
  24 chrome's implementation, `MetaFrames` derives from `GtkWindow`.
  25
  26 If you are happy with the defaults that chrome has picked, no action is
  27 necessary on the part of the theme author.
  28
  29 ## Introducing `ChromeGtkFrame`
  30
  31 For cases where you want control of the colors chrome uses, Chrome gives you a
  32 number of style properties for injecting colors and other information about how
  33 to draw the frame. For example, here's the proposed modifications to Ubuntu's
  34 Ambiance:
  35
  36 ```
  37 style "chrome-gtk-frame"
  38 {
  39     ChromeGtkFrame::frame-color = @fg_color
  40     ChromeGtkFrame::inactive-frame-color = lighter(@fg_color)
  41
  42     ChromeGtkFrame::frame-gradient-size = 16
  43     ChromeGtkFrame::frame-gradient-color = "#5c5b56"
  44
  45     ChromeGtkFrame::scrollbar-trough-color = @bg_color
  46     ChromeGtkFrame::scrollbar-slider-prelight-color = "#F8F6F2"
  47     ChromeGtkFrame::scrollbar-slider-normal-color = "#E7E0D3"
  48 }
  49
  50 class "ChromeGtkFrame" style "chrome-gtk-frame"
  51 ```
  52
  53 ### Frame color properties
  54
  55 These are the frame's main solid color.
  56
  57 | **Property** | **Type** | **Description** | **If unspecified** |
  58 |:-------------|:---------|:----------------|:-------------------|
  59 | `frame-color` | `GdkColor` | The main color of active chrome windows. | Darkens `MetaFrame::bg[SELECTED]` |
  60 | `inactive-frame-color` | `GdkColor` | The main color of inactive chrome windows. | Darkens `MetaFrame::bg[INSENSITIVE]` |
  61 | `incognito-frame-color` | `GdkColor` | The main color of active incognito windows. | Tints `frame-color` by the default incognito tint |
  62 | `incognito-inactive-frame-color` | `GdkColor` | The main color of inactive incognito windows. | Tints `inactive-frame-color` by the default incognito tint |
  63
  64 ### Frame gradient properties
  65
  66 Chrome's frame (along with many normal window manager themes) have a slight
  67 gradient at the top, before filling the rest of the frame background image with
  68 a solid color. For example, the top `frame-gradient-size` pixels would be a
  69 gradient starting from `frame-gradient-color` at the top to `frame-color` at the
  70 bottom, with the rest of the frame being filled with `frame-color`.
  71
  72 | **Property** | **Type** | **Description** | **If unspecified** |
  73 |:-------------|:---------|:----------------|:-------------------|
  74 | `frame-gradient-size` | Integers 0 through 128 | How large the gradient should be. Set to zero to disable drawing a gradient | Defaults to 16 pixels tall |
  75 | `frame-gradient-color` | `GdkColor` | Top color of the gradient | Lightens `frame-color` |
  76 | `inactive-frame-gradient-color` | `GdkColor` | Top color of the inactive gradient | Lightents `inactive-frame-color` |
  77 | `incognito-frame-gradient-color` | `GdkColor` | Top color of the incognito gradient | Lightens `incognito-frame-color` |
  78 | `incognito-inactive-frame-gradient-color` | `GdkColor` | Top color of the incognito inactive gradient. | Lightens `incognito-inactive-frame-color` |
  79
  80 ### Scrollbar control
  81
  82 Because widget rendering is done in a separate, sandboxed process that doesn't
  83 have access to the X server or the filesystem, there's no current way to do
  84 GTK+ widget rendering. We instead pass WebKit a few colors and let it draw a
  85 default scrollbar. We have a very
  86 [complex fallback](http://git.chromium.org/gitweb/?p=chromium.git;a=blob;f=chrome/browser/gtk/gtk_theme_provider.cc;h=a57ab6b182b915192c84177f1a574914c44e2e71;hb=3f873177e192f5c6b66ae591b8b7205d8a707918#l424)
  87 where we render the widget and then average colors if this information isn't
  88 provided.
  89
  90 | **Property** | **Type** | **Description** |
  91 |:-------------|:---------|:----------------|
  92 | `scrollbar-slider-prelight-color` | `GdkColor` | Color of the slider on mouse hover. |
  93 | `scrollbar-slider-normal-color` | `GdkColor` | Color of the slider otherwise |
  94 | `scrollbar-trough-color` | `GdkColor` | Color of the scrollbar trough |
  95
  96 ## Anticipated Q&A
  97
  98 ### Will you patch themes upstream?
  99
 100 I am at the very least hoping we can get Radiance and Ambiance patches since we
 101 make very poor frame decisions on those themes, and hopefully a few others.
 102
 103 ### How about control over the min/max/close buttons?
 104
 105 I actually tried this locally. There's a sort of uncanny valley effect going on;
 106 as the frame looks more native, it's more obvious that it isn't behaving like a
 107 native frame. (Also my implementation added a startup time hit.)
 108
 109 ### Why use style properties instead of (i.e.) bg[STATE]?
 110
 111 There's no way to distinguish between colors set on different classes. Using
 112 style properties allows us to be backwards compatible and maintain the
 113 heuristics since not everyone is going to modify their themes for chromium (and
 114 the heuristics do a reasonable job).
 115
 116 ### Why now?
 117
 118 *   I (erg@) was putting off major changes to the window frame stuff in
 119     anticipation of finally being able to use GTK+'s theme rendering for the
 120     window border with client side decorations, but client side decorations
 121     either isn't happening or isn't happening anytime soon, so there's no
 122     justification for pushing this task off into the future.
 123 *   Chrome looks pretty bad under Ambiance on Maverick.
 124
 125 ### Details about `MetaFrames` and `ChromeGtkFrame` relationship and history?
 126
 127 `MetaFrames` is a class that was used in metacity to communicate color
 128 information to the window manager. During the Hardy Heron days, we slurped up
 129 the data and used it as a key part of our heuristics. At least on my Lucid Lynx
 130 machine, none of the GNOME GTK+ themes have `MetaFrames` styling. (As mentioned
 131 above, several of the XFCE themes do, though.)
 132
 133 Internally to chrome, our `ChromeGtkFrame` class inherits from `MetaFrames`
 134 (again, which inherits from `GtkWindow`) so any old themes that style the
 135 `MetaFrames` class are backwards compatible.