gtk3/docs/reference/gtk/html/gtk-migrating-GtkStyleContext-css.html
2017-12-21 20:47:04 -05:00

436 lines
22 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Using the CSS file format: GTK+ 3 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
<link rel="up" href="gtk-migrating-GtkStyleContext.html" title="Theming changes">
<link rel="prev" href="gtk-migrating-GtkStyleContext-parser-extensions.html" title="Extending the CSS parser">
<link rel="next" href="gtk-migrating-GtkStyleContext-checklist.html" title="A checklist for widgets">
<meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="gtk-migrating-GtkStyleContext.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="gtk-migrating-GtkStyleContext-parser-extensions.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gtk-migrating-GtkStyleContext-checklist.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gtk-migrating-GtkStyleContext-css"></a>Using the CSS file format</h2></div></div></div>
<p>
The syntax of RC and CSS files formats is obviously different.
The CSS-like syntax will hopefully be much more familiar to many
people, lowering the barrier for custom theming.
</p>
<p>
Instead of going through the syntax differences one-by-one, we
will present a more or less comprehensive example and discuss
how it can be translated into CSS:
</p>
<div class="example">
<a name="id-1.6.4.6.4"></a><p class="title"><b>Example 44. Sample RC code</b></p>
<div class="example-contents">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76</pre></td>
<td class="listing_code"><pre class="programlisting">style <span class="string">&quot;default&quot;</span> <span class="gtkdoc opt">{</span>
xthickness <span class="gtkdoc opt">=</span> <span class="number">1</span>
ythickness <span class="gtkdoc opt">=</span> <span class="number">1</span>
<span class="gtkdoc kwc">GtkButton</span><span class="gtkdoc opt">::</span>child<span class="gtkdoc opt">-</span>displacement<span class="gtkdoc opt">-</span>x <span class="gtkdoc opt">=</span> <span class="number">1</span>
<span class="gtkdoc kwc">GtkButton</span><span class="gtkdoc opt">::</span>child<span class="gtkdoc opt">-</span>displacement<span class="gtkdoc opt">-</span>y <span class="gtkdoc opt">=</span> <span class="number">1</span>
<span class="gtkdoc kwc">GtkCheckButton</span><span class="gtkdoc opt">::</span>indicator<span class="gtkdoc opt">-</span>size <span class="gtkdoc opt">=</span> <span class="number">14</span>
bg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;bg_color
bg<span class="gtkdoc opt">[</span>PRELIGHT<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">1.02</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
bg<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> &#64;selected_bg_color
bg<span class="gtkdoc opt">[</span>INSENSITIVE<span class="gtkdoc opt">] =</span> &#64;bg_color
bg<span class="gtkdoc opt">[</span>ACTIVE<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.9</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
fg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;fg_color
fg<span class="gtkdoc opt">[</span>PRELIGHT<span class="gtkdoc opt">] =</span> &#64;fg_color
fg<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> &#64;selected_fg_color
fg<span class="gtkdoc opt">[</span>INSENSITIVE<span class="gtkdoc opt">] =</span> <span class="function">darker</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">)</span>
fg<span class="gtkdoc opt">[</span>ACTIVE<span class="gtkdoc opt">] =</span> &#64;fg_color
text<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;text_color
text<span class="gtkdoc opt">[</span>PRELIGHT<span class="gtkdoc opt">] =</span> &#64;text_color
text<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> &#64;selected_fg_color
text<span class="gtkdoc opt">[</span>INSENSITIVE<span class="gtkdoc opt">] =</span> <span class="function">darker</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">)</span>
text<span class="gtkdoc opt">[</span>ACTIVE<span class="gtkdoc opt">] =</span> &#64;selected_fg_color
base<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;base_color
base<span class="gtkdoc opt">[</span>PRELIGHT<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.95</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
base<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> &#64;selected_bg_color
base<span class="gtkdoc opt">[</span>INSENSITIVE<span class="gtkdoc opt">] =</span> &#64;bg_color
base<span class="gtkdoc opt">[</span>ACTIVE<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.9</span><span class="gtkdoc opt">,</span> &#64;selected_bg_color<span class="gtkdoc opt">)</span>
engine <span class="string">&quot;clearlooks&quot;</span> <span class="gtkdoc opt">{</span>
colorize_scrollbar <span class="gtkdoc opt">=</span> TRUE
style <span class="gtkdoc opt">=</span> CLASSIC
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">}</span>
style <span class="string">&quot;tooltips&quot;</span> <span class="gtkdoc opt">{</span>
xthickness <span class="gtkdoc opt">=</span> <span class="number">4</span>
ythickness <span class="gtkdoc opt">=</span> <span class="number">4</span>
bg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;tooltip_bg_color
fg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> &#64;tooltip_fg_color
<span class="gtkdoc opt">}</span>
style <span class="string">&quot;button&quot;</span> <span class="gtkdoc opt">{</span>
xthickness <span class="gtkdoc opt">=</span> <span class="number">3</span>
ythickness <span class="gtkdoc opt">=</span> <span class="number">3</span>
bg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">1.04</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
bg<span class="gtkdoc opt">[</span>PRELIGHT<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">1.06</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
bg<span class="gtkdoc opt">[</span>ACTIVE<span class="gtkdoc opt">] =</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.85</span><span class="gtkdoc opt">,</span> &#64;bg_color<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">}</span>
style <span class="string">&quot;entry&quot;</span> <span class="gtkdoc opt">{</span>
xthickness <span class="gtkdoc opt">=</span> <span class="number">3</span>
ythickness <span class="gtkdoc opt">=</span> <span class="number">3</span>
bg<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> <span class="function">mix</span> <span class="gtkdoc opt">(</span><span class="number">0.4</span><span class="gtkdoc opt">,</span> &#64;selected_bg_color<span class="gtkdoc opt">,</span> &#64;base_color<span class="gtkdoc opt">)</span>
fg<span class="gtkdoc opt">[</span>SELECTED<span class="gtkdoc opt">] =</span> &#64;text_color
engine <span class="string">&quot;clearlooks&quot;</span> <span class="gtkdoc opt">{</span>
focus_color <span class="gtkdoc opt">=</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.65</span><span class="gtkdoc opt">,</span> &#64;selected_bg_color<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">}</span>
style <span class="string">&quot;other&quot;</span> <span class="gtkdoc opt">{</span>
bg<span class="gtkdoc opt">[</span>NORMAL<span class="gtkdoc opt">] =</span> <span class="gtkdoc ppc">#fff;</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc kwc">class</span> <span class="string">&quot;GtkWidget&quot;</span> style <span class="string">&quot;default&quot;</span>
<span class="gtkdoc kwc">class</span> <span class="string">&quot;GtkEntry&quot;</span> style <span class="string">&quot;entry&quot;</span>
widget_class <span class="string">&quot;*&lt;GtkButton&gt;&quot;</span> style <span class="string">&quot;button&quot;</span>
widget <span class="string">&quot;gtk-tooltip*&quot;</span> style <span class="string">&quot;tooltips&quot;</span>
widget_class <span class="string">&quot;window-name.*.GtkButton&quot;</span> style <span class="string">&quot;other&quot;</span></pre></td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="example-break"><p>
would roughly translate to this CSS:
</p>
<div class="example">
<a name="id-1.6.4.6.6"></a><p class="title"><b>Example 45. CSS translation</b></p>
<div class="example-contents">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="gtkdoc opt">* {</span>
padding<span class="gtkdoc opt">:</span> <span class="number">1</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">-</span>GtkButton<span class="gtkdoc opt">-</span>child<span class="gtkdoc opt">-</span>displacement<span class="gtkdoc opt">-</span>x<span class="gtkdoc opt">:</span> <span class="number">1</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">-</span>GtkButton<span class="gtkdoc opt">-</span>child<span class="gtkdoc opt">-</span>displacement<span class="gtkdoc opt">-</span>y<span class="gtkdoc opt">:</span> <span class="number">1</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">-</span>GtkCheckButton<span class="gtkdoc opt">-</span>indicator<span class="gtkdoc opt">-</span>size<span class="gtkdoc opt">:</span> <span class="number">14</span><span class="gtkdoc opt">;</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> &#64;bg_color<span class="gtkdoc opt">;</span>
color<span class="gtkdoc opt">:</span> &#64;fg_color<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">-</span>Clearlooks<span class="gtkdoc opt">-</span>colorize<span class="gtkdoc opt">-</span>scrollbar<span class="gtkdoc opt">:</span> <span class="keyword">true</span><span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">-</span>Clearlooks<span class="gtkdoc opt">-</span>style<span class="gtkdoc opt">:</span> classic<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">*:</span>hover <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">1.02</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">*:</span>selected <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> &#64;selected_bg_color<span class="gtkdoc opt">;</span>
color<span class="gtkdoc opt">:</span> &#64;selected_fg_color<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">*:</span>insensitive <span class="gtkdoc opt">{</span>
color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">0.7</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">*:</span>active <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">0.9</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>tooltip <span class="gtkdoc opt">{</span>
padding<span class="gtkdoc opt">:</span> <span class="number">4</span><span class="gtkdoc opt">;</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> &#64;tooltip_bg_color<span class="gtkdoc opt">;</span>
color<span class="gtkdoc opt">:</span> &#64;tooltip_fg_color<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>button <span class="gtkdoc opt">{</span>
padding<span class="gtkdoc opt">:</span> <span class="number">3</span><span class="gtkdoc opt">;</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">1.04</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>button<span class="gtkdoc opt">:</span>hover <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">1.06</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>button<span class="gtkdoc opt">:</span>active <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span>&#64;bg_color<span class="gtkdoc opt">,</span> <span class="number">0.85</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>entry <span class="gtkdoc opt">{</span>
padding<span class="gtkdoc opt">:</span> <span class="number">3</span><span class="gtkdoc opt">;</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> &#64;base_color<span class="gtkdoc opt">;</span>
color<span class="gtkdoc opt">:</span> &#64;text_color<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span>
<span class="gtkdoc opt">.</span>entry<span class="gtkdoc opt">:</span>selected <span class="gtkdoc opt">{</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">mix</span> <span class="gtkdoc opt">(</span>&#64;selected_bg_color<span class="gtkdoc opt">,</span> &#64;base_color<span class="gtkdoc opt">,</span> <span class="number">0.4</span><span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">-</span>Clearlooks<span class="gtkdoc opt">-</span>focus<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="function">shade</span> <span class="gtkdoc opt">(</span><span class="number">0.65</span><span class="gtkdoc opt">,</span> &#64;selected_bg_color<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">}</span>
<span class="comment">/* The latter selector is an specification of the first,</span>
<span class="comment"> since any widget may use the same classes or names */</span>
<span class="gtkdoc ppc">#window-name .button,</span>
GtkWindow<span class="gtkdoc ppc">#window-name GtkButton.button {</span>
background<span class="gtkdoc opt">-</span>color<span class="gtkdoc opt">:</span> <span class="gtkdoc ppc">#fff;</span>
<span class="gtkdoc opt">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="example-break"><p>
One notable difference is the reduction from fg/bg/text/base colors
to only foreground/background, in exchange the widget is able to render
its various elements with different CSS classes, which can be themed
independently.
</p>
<p>
In the same vein, the light, dark and mid color variants that
were available in GtkStyle should be replaced by a combination of
symbolic colors and custom CSS, where necessary. text_aa should
really not be used anywhere, anyway, and the white and black colors
that were available in GtkStyle can just be replaced by literal
GdkRGBA structs.
</p>
<p>
Access to colors has also changed a bit. With <a class="link" href="GtkStyle.html" title="GtkStyle"><span class="type">GtkStyle</span></a>, the common
way to access colors is:
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5</pre></td>
<td class="listing_code"><pre class="programlisting">GdkColor <span class="gtkdoc opt">*</span>color1<span class="gtkdoc opt">;</span>
GdkColor color2<span class="gtkdoc opt">;</span>
color1 <span class="gtkdoc opt">= &amp;</span>style<span class="gtkdoc opt">-&gt;</span>bg<span class="gtkdoc opt">[</span>GTK_STATE_PRELIGHT<span class="gtkdoc opt">];</span>
<span class="function"><a href="GtkStyle.html#gtk-style-lookup-color">gtk_style_lookup_color</a></span> <span class="gtkdoc opt">(</span>style<span class="gtkdoc opt">,</span> <span class="string">&quot;focus_color&quot;</span><span class="gtkdoc opt">, &amp;</span>color2<span class="gtkdoc opt">);</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
With <a class="link" href="GtkStyleContext.html" title="GtkStyleContext"><span class="type">GtkStyleContext</span></a>, you generally use <a href="../gdk4/gdk4-RGBA-Colors.html#GdkRGBA"><span class="type">GdkRGBA</span></a> instead of <span class="type">GdkColor</span>
and the code looks like this:
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11</pre></td>
<td class="listing_code"><pre class="programlisting">GdkRGBA <span class="gtkdoc opt">*</span>color1<span class="gtkdoc opt">;</span>
GdkRGBA color2<span class="gtkdoc opt">;</span>
<span class="function"><a href="GtkStyleContext.html#gtk-style-context-get">gtk_style_context_get</a></span> <span class="gtkdoc opt">(</span>context<span class="gtkdoc opt">,</span> GTK_STATE_FLAG_PRELIGHT<span class="gtkdoc opt">,</span>
<span class="string">&quot;background-color&quot;</span><span class="gtkdoc opt">, &amp;</span>color1<span class="gtkdoc opt">,</span>
NULL<span class="gtkdoc opt">);</span>
<span class="function"><a href="GtkStyleContext.html#gtk-style-context-lookup-color">gtk_style_context_lookup_color</a></span> <span class="gtkdoc opt">(</span>context<span class="gtkdoc opt">,</span> <span class="string">&quot;focus_color&quot;</span><span class="gtkdoc opt">, &amp;</span>color2<span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">...</span>
<span class="function"><a href="../gdk4/gdk4-RGBA-Colors.html#gdk-rgba-free">gdk_rgba_free</a></span> <span class="gtkdoc opt">(</span>color1<span class="gtkdoc opt">);</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
Note that the memory handling here is different: <a class="link" href="GtkStyleContext.html#gtk-style-context-get" title="gtk_style_context_get ()"><code class="function">gtk_style_context_get()</code></a>
expects the address of a GdkRGBA* and returns a newly allocated struct,
<a class="link" href="GtkStyleContext.html#gtk-style-context-lookup-color" title="gtk_style_context_lookup_color ()"><code class="function">gtk_style_context_lookup_color()</code></a> expects the address of an existing
struct, and fills it.
</p>
<p>
It is worth mentioning that the new file format does not support
stock icon mappings as the RC format did.
</p>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>