source: trunk/third/gtk/docs/html/gtk_tut-21.html @ 14482

Revision 14482, 10.2 KB checked in by ghudson, 25 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r14481, which included commits to RCS files with non-trunk default branches.
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<HTML>
3<HEAD>
4 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
5 <TITLE>GTK v1.2 Tutorial: GTK's rc Files </TITLE>
6 <LINK HREF="gtk_tut-22.html" REL=next>
7 <LINK HREF="gtk_tut-20.html" REL=previous>
8 <LINK HREF="gtk_tut.html#toc21" REL=contents>
9</HEAD>
10<BODY BGCOLOR="#FFFFFF">
11<A HREF="gtk_tut-22.html">Next</A>
12<A HREF="gtk_tut-20.html">Previous</A>
13<A HREF="gtk_tut.html#toc21">Contents</A>
14<HR NOSHADE>
15<H2><A NAME="sec_gtkrc_files"></A> <A NAME="s21">21. GTK's rc Files </A></H2>
16
17<P>GTK has its own way of dealing with application defaults, by using rc
18files. These can be used to set the colors of just about any widget, and
19can also be used to tile pixmaps onto the background of some widgets. 
20<P>
21<H2><A NAME="ss21.1">21.1 Functions For rc Files </A>
22</H2>
23
24<P>When your application starts, you should include a call to:
25<P>
26<BLOCKQUOTE><CODE>
27<PRE>
28void gtk_rc_parse( char *filename );
29</PRE>
30</CODE></BLOCKQUOTE>
31<P>Passing in the filename of your rc file. This will cause GTK to parse
32this file, and use the style settings for the widget types defined
33there.
34<P>If you wish to have a special set of widgets that can take on a
35different style from others, or any other logical division of widgets,
36use a call to:
37<P>
38<BLOCKQUOTE><CODE>
39<PRE>
40void gtk_widget_set_name( GtkWidget *widget,
41                          gchar     *name );
42</PRE>
43</CODE></BLOCKQUOTE>
44<P>Passing your newly created widget as the first argument, and the name
45you wish to give it as the second. This will allow you to change the
46attributes of this widget by name through the rc file.
47<P>If we use a call something like this:
48<P>
49<BLOCKQUOTE><CODE>
50<PRE>
51button = gtk_button_new_with_label ("Special Button");
52gtk_widget_set_name (button, "special button");
53</PRE>
54</CODE></BLOCKQUOTE>
55<P>Then this button is given the name "special button" and may be addressed by
56name in the rc file as "special button.GtkButton".  [&lt;--- Verify ME!]
57<P>The example rc file below, sets the properties of the main window, and lets
58all children of that main window inherit the style described by the "main
59button" style.  The code used in the application is:
60<P>
61<BLOCKQUOTE><CODE>
62<PRE>
63window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
64gtk_widget_set_name (window, "main window");
65</PRE>
66</CODE></BLOCKQUOTE>
67<P>And then the style is defined in the rc file using:
68<P>
69<BLOCKQUOTE><CODE>
70<PRE>
71widget "main window.*GtkButton*" style "main_button"
72</PRE>
73</CODE></BLOCKQUOTE>
74<P>Which sets all the Button widgets in the "main window" to the
75"main_buttons" style as defined in the rc file.
76<P>As you can see, this is a fairly powerful and flexible system.  Use your
77imagination as to how best to take advantage of this.
78<P>
79<H2><A NAME="ss21.2">21.2 GTK's rc File Format</A>
80</H2>
81
82<P>The format of the GTK file is illustrated in the example below. This is
83the testgtkrc file from the GTK distribution, but I've added a
84few comments and things. You may wish to include this explanation in
85your application to allow the user to fine tune his application.
86<P>There are several directives to change the attributes of a widget.
87<P>
88<UL>
89<LI>fg - Sets the foreground color of a widget.</LI>
90<LI>bg - Sets the background color of a widget.</LI>
91<LI>bg_pixmap - Sets the background of a widget to a tiled pixmap.</LI>
92<LI>font - Sets the font to be used with the given widget.</LI>
93</UL>
94<P>In addition to this, there are several states a widget can be in, and you
95can set different colors, pixmaps and fonts for each state. These states are:
96<P>
97<UL>
98<LI>NORMAL - The normal state of a widget, without the mouse over top of
99it, and not being pressed, etc.</LI>
100<LI>PRELIGHT - When the mouse is over top of the widget, colors defined
101using this state will be in effect.</LI>
102<LI>ACTIVE - When the widget is pressed or clicked it will be active, and
103the attributes assigned by this tag will be in effect.</LI>
104<LI>INSENSITIVE - When a widget is set insensitive, and cannot be
105activated, it will take these attributes.</LI>
106<LI>SELECTED - When an object is selected, it takes these attributes.</LI>
107</UL>
108<P>When using the "fg" and "bg" keywords to set the colors of widgets, the
109format is:
110<P>
111<BLOCKQUOTE><CODE>
112<PRE>
113fg[&lt;STATE>] = { Red, Green, Blue }
114</PRE>
115</CODE></BLOCKQUOTE>
116<P>Where STATE is one of the above states (PRELIGHT, ACTIVE, etc), and the Red,
117Green and Blue are values in the range of 0 - 1.0,  { 1.0, 1.0, 1.0 } being
118white. They must be in float form, or they will register as 0, so a straight
119"1" will not work, it must be "1.0".  A straight "0" is fine because it
120doesn't matter if it's not recognized.  Unrecognized values are set to 0.
121<P>bg_pixmap is very similar to the above, except the colors are replaced by a
122filename.
123<P>pixmap_path is a list of paths separated by ":"'s.  These paths will be
124searched for any pixmap you specify.
125<P>The font directive is simply:
126<BLOCKQUOTE><CODE>
127<PRE>
128font = "&lt;font name>"
129</PRE>
130</CODE></BLOCKQUOTE>
131<P>The only hard part is figuring out the font string. Using xfontsel or
132a similar utility should help.
133<P>The "widget_class" sets the style of a class of widgets. These classes are
134listed in the widget overview on the class hierarchy.
135<P>The "widget" directive sets a specifically named set of widgets to a
136given style, overriding any style set for the given widget class.
137These widgets are registered inside the application using the
138gtk_widget_set_name() call. This allows you to specify the attributes of a
139widget on a per widget basis, rather than setting the attributes of an
140entire widget class. I urge you to document any of these special widgets so
141users may customize them.
142<P>When the keyword <CODE>parent</CODE> is used as an attribute, the widget will take on
143the attributes of its parent in the application.
144<P>When defining a style, you may assign the attributes of a previously defined
145style to this new one.
146<P>
147<BLOCKQUOTE><CODE>
148<PRE>
149style "main_button" = "button"
150{
151  font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
152  bg[PRELIGHT] = { 0.75, 0, 0 }
153}
154</PRE>
155</CODE></BLOCKQUOTE>
156<P>This example takes the "button" style, and creates a new "main_button" style
157simply by changing the font and prelight background color of the "button"
158style.
159<P>Of course, many of these attributes don't apply to all widgets. It's a
160simple matter of common sense really. Anything that could apply, should.
161<P>
162<H2><A NAME="ss21.3">21.3 Example rc file</A>
163</H2>
164
165<P>
166<P>
167<BLOCKQUOTE><CODE>
168<PRE>
169# pixmap_path "&lt;dir 1>:&lt;dir 2>:&lt;dir 3>:..."
170#
171pixmap_path "/usr/include/X11R6/pixmaps:/home/imain/pixmaps"
172#
173# style &lt;name> [= &lt;name>]
174# {
175#   &lt;option>
176# }
177#
178# widget &lt;widget_set> style &lt;style_name>
179# widget_class &lt;widget_class_set> style &lt;style_name>
180
181
182# Here is a list of all the possible states.  Note that some do not apply to
183# certain widgets.
184#
185# NORMAL - The normal state of a widget, without the mouse over top of
186# it, and not being pressed, etc.
187#
188# PRELIGHT - When the mouse is over top of the widget, colors defined
189# using this state will be in effect.
190#
191# ACTIVE - When the widget is pressed or clicked it will be active, and
192# the attributes assigned by this tag will be in effect.
193#
194# INSENSITIVE - When a widget is set insensitive, and cannot be
195# activated, it will take these attributes.
196#
197# SELECTED - When an object is selected, it takes these attributes.
198#
199# Given these states, we can set the attributes of the widgets in each of
200# these states using the following directives.
201#
202# fg - Sets the foreground color of a widget.
203# fg - Sets the background color of a widget.
204# bg_pixmap - Sets the background of a widget to a tiled pixmap.
205# font - Sets the font to be used with the given widget.
206#
207
208# This sets a style called "button".  The name is not really important, as
209# it is assigned to the actual widgets at the bottom of the file.
210
211style "window"
212{
213  #This sets the padding around the window to the pixmap specified.
214  #bg_pixmap[&lt;STATE>] = "&lt;pixmap filename>"
215  bg_pixmap[NORMAL] = "warning.xpm"
216}
217
218style "scale"
219{
220  #Sets the foreground color (font color) to red when in the "NORMAL"
221  #state.
222 
223  fg[NORMAL] = { 1.0, 0, 0 }
224 
225  #Sets the background pixmap of this widget to that of its parent.
226  bg_pixmap[NORMAL] = "&lt;parent>"
227}
228
229style "button"
230{
231  # This shows all the possible states for a button.  The only one that
232  # doesn't apply is the SELECTED state.
233 
234  fg[PRELIGHT] = { 0, 1.0, 1.0 }
235  bg[PRELIGHT] = { 0, 0, 1.0 }
236  bg[ACTIVE] = { 1.0, 0, 0 }
237  fg[ACTIVE] = { 0, 1.0, 0 }
238  bg[NORMAL] = { 1.0, 1.0, 0 }
239  fg[NORMAL] = { .99, 0, .99 }
240  bg[INSENSITIVE] = { 1.0, 1.0, 1.0 }
241  fg[INSENSITIVE] = { 1.0, 0, 1.0 }
242}
243
244# In this example, we inherit the attributes of the "button" style and then
245# override the font and background color when prelit to create a new
246# "main_button" style.
247
248style "main_button" = "button"
249{
250  font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
251  bg[PRELIGHT] = { 0.75, 0, 0 }
252}
253
254style "toggle_button" = "button"
255{
256  fg[NORMAL] = { 1.0, 0, 0 }
257  fg[ACTIVE] = { 1.0, 0, 0 }
258 
259  # This sets the background pixmap of the toggle_button to that of its
260  # parent widget (as defined in the application).
261  bg_pixmap[NORMAL] = "&lt;parent>"
262}
263
264style "text"
265{
266  bg_pixmap[NORMAL] = "marble.xpm"
267  fg[NORMAL] = { 1.0, 1.0, 1.0 }
268}
269
270style "ruler"
271{
272  font = "-adobe-helvetica-medium-r-normal--*-80-*-*-*-*-*-*"
273}
274
275# pixmap_path "~/.pixmaps"
276
277# These set the widget types to use the styles defined above.
278# The widget types are listed in the class hierarchy, but could probably be
279# just listed in this document for the users reference.
280
281widget_class "GtkWindow" style "window"
282widget_class "GtkDialog" style "window"
283widget_class "GtkFileSelection" style "window"
284widget_class "*Gtk*Scale" style "scale"
285widget_class "*GtkCheckButton*" style "toggle_button"
286widget_class "*GtkRadioButton*" style "toggle_button"
287widget_class "*GtkButton*" style "button"
288widget_class "*Ruler" style "ruler"
289widget_class "*GtkText" style "text"
290
291# This sets all the buttons that are children of the "main window" to
292# the main_button style.  These must be documented to be taken advantage of.
293widget "main window.*GtkButton*" style "main_button"
294</PRE>
295</CODE></BLOCKQUOTE>
296<P>
297<HR NOSHADE>
298<A HREF="gtk_tut-22.html">Next</A>
299<A HREF="gtk_tut-20.html">Previous</A>
300<A HREF="gtk_tut.html#toc21">Contents</A>
301</BODY>
302</HTML>
Note: See TracBrowser for help on using the repository browser.