gtkrc.sgml 25 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
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
<!-- ##### SECTION Title ##### -->
Resource Files

<!-- ##### SECTION Short_Description ##### -->
Routines for handling resource files

<!-- ##### SECTION Long_Description ##### -->
<para>
GTK+ provides resource file mechanism for configuring
various aspects of the operation of a GTK+ program
at runtime.
</para>

<refsect2><title>Default files</title>
<para>
An application can cause GTK+ to parse a specific RC
file by calling gtk_rc_parse(). In addition to this,
certain files will be read at the end of gtk_init().
Unless modified, the files looked for will be <filename>.gtkrc</filename>
in the users home directory, and 
<filename>$localstatedir/gtk/gtkrc</filename> 
(<literal>$localstatedir</literal> defaults to 
<filename>/usr/local/etc</filename>).
</para>
<para>
The set of these <firstterm>default</firstterm> files
can be retrieved with gtk_rc_get_default_files()
and modified with gtk_rc_add_default_file() and
gtk_rc_set_default_files().
</para>
<para>
For each default file, in addition to the file itself,
GTK+ will look for a locale-specific file that will
be parsed in addition to the main file. For instance,
if <literal>LANG</literal> is set to <literal>ja_JP.ujis</literal>,
when loading the default file <filename>~/.gtkrc</filename>
then GTK+ looks for <filename>~/.gtkrc.ja_JP.ujis</filename>,
<filename>~/.gtkrc.ja_JP</filename>, and
<filename>~/.gtkrc.ja</filename>, and parses the
first one it finds.
</para>
</refsect2>

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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
<refsect2><title>Pathnames and patterns</title>
<para>
A resource file defines a number of styles and key bindings and
attaches them to particular widgets. The attachment is done
by the <literal>widget</literal>, <literal>widget_class</literal>,
and <literal>class</literal> declarations. As an example
of such a statement:
<programlisting>
widget "mywindow.*.GtkEntry" style "my-entry-class"
</programlisting>
attaches the style <literal>"my-entry-class"</literal>
to all widgets whose <firstterm>widget class</firstterm>
matches the <firstterm>pattern</firstterm>
<literal>"mywindow.*.GtkEntry"</literal>.
</para>
<para>
The patterns here are given in the standard shell glob
syntax. The <literal>"?"</literal> wildcard matches
any character, while <literal>"*"</literal> matches
zero or more of any character. The three types of
matching are against the widget path, the
<firstterm>class path</firstterm> and the class
heirarchy. Both the widget and the class paths consists of a
<literal>"."</literal> separated list of all the
parents of the widget and the widget itself from
outermost to innermost. The difference is that in
the widget path, the name assigned by
<function>gtk_widget_set_name()</function> is used
if present, otherwise the class name of the widget, while
for the widget path, the class name is always used.
</para>
<para>
So, if you have a <classname>GtkEntry</classname> named
<literal>"myentry"</literal>, inside of a of a window
named <literal>"mywindow"</literal>, then the
widget path is:
<programlisting>
"mwindow.GtkHBox.myentry"
</programlisting>
while the class path is:
<programlisting>
"GtkWindow.GtkHBox.GtkEntry"
</programlisting>
</para>
<para>
Matching against class is a little different. The pattern
match is done against all class names in the widgets
class heirarchy (not the layout heirarchy) in sequence, so the
pattern:
<programlisting>
class "GtkButton" style "my-style"
</programlisting>
will match not just <classname>GtkButton</classname> widgets,
but also <classname>GtkToggleButton</classname> and
<classname>GtkCheckButton</classname> widgets, since
those classes derive from <classname>GtkButton</classname>.
</para>
</refsect2>

Owen Taylor's avatar
Owen Taylor committed
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<refsect2><title>Toplevel declarations</title>
<para>
An RC file is a text file which is composed of a sequence
of declarations. '#' characters delimit comments and
the portion of a line after a '#' is ignored when parsing
an RC file.
</para>

<para>
The possible toplevel declarations are:

<variablelist>
  <varlistentry>
    <term><literal>binding <replaceable>name</replaceable>
     { ... }</literal></term>
    <listitem>
      <para>Declare a binding set</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>class <replaceable>pattern</replaceable> 
          [ style | binding [ : <replaceable>priority</replaceable> ]]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <para>Specify a style or binding set for a particular
     branch of the inheritance heirarchy.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>include <replaceable>filename</replaceable></literal></term>
    <listitem>
      <para>Parse another file at this point</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>module_path <replaceable>path></replaceable></literal></term>
    <listitem>
      <para>Sets a path (a list of directories separated
      by colons) that will be searched for theme engines referenced in
      RC files.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>pixmap_path <replaceable>path></replaceable></literal></term>
    <listitem>
      <para>Sets a path (a list of directories separated
      by colons) that will be searched for pixmaps referenced in
      RC files.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>style <replaceable>name</replaceable> [ =
    <replaceable>parent</replaceable> ] { ... }</literal></term>
    <listitem>
      <para>Declare a style</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>widget <replaceable>pattern</replaceable> 
          [ style | binding [ : <replaceable>priority</replaceable> ]]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <para>Specify a style or binding set for a particular
166
     group of widgets by matching on the widget pathname.</para>
Owen Taylor's avatar
Owen Taylor committed
167
168
169
170
171
172
173
174
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>widget_class <replaceable>pattern</replaceable> 
          [ style | binding [ : <replaceable>priority</replaceable> ]]
          <replaceable>name</replaceable></literal></term>
    <listitem>
     <para>Specify a style or binding set for a particular
175
     group of widgets by matching on the class pathname.</para>
Owen Taylor's avatar
Owen Taylor committed
176
177
178
179
    </listitem>
  </varlistentry>
</variablelist>
</para>
Owen Taylor's avatar
Owen Taylor committed
180
</refsect2>
Owen Taylor's avatar
Owen Taylor committed
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267

<refsect2><title>Styles</title>
<para>
A RC style is specified by a <literal>style</literal> 
declaration in a RC file, and then bound to widgets
with a <literal>widget</literal>, <literal>widget_class</literal>,
or <literal>class</literal> declaration. All styles
applying to a particular widget are composited together
with <literal>widget</literal> declarations overriding
<literal>widget_class</literal> declarations which, in
turn, override <literal>widget</literal> declarations.
Within each type of declaration, later declarations override
earlier ones.
</para>

<para>
Within a <literal>style</literal> declaration, the possible
elements are:

<variablelist>
  <varlistentry>
    <term><literal>bg[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Set color used for the background of most widgets.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>fg[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Set color used for the foreground of most widgets.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>base[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Set color used for the background of widgets displaying
         editable text. This color is used for the background
         of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>text[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Set color used for foreground of widgets using
         <literal>base</literal> for the background color.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>bg_text[<replaceable>state</replaceable>] =
      <replaceable>color</replaceable></literal></term>
     <listitem>
       <para>
         Set a background pixmap to be used in place of
         the <literal>bg</literal> color (or for #GtkText,
         in place of the <literal>base</literal> color.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>font = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Set the font for a widget.
       </para>
     </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>fontset = <replaceable>font</replaceable></literal></term>
     <listitem>
       <para>
         Set the fontset for a widget. Overrides any
         <literal>font</literal> declarations.
       </para>
     </listitem>
  </varlistentry>
Havoc Pennington's avatar
Havoc Pennington committed
268
  <varlistentry>
269
    <term><literal>stock[<replaceable>"stock-id"</replaceable>] = { <replaceable>icon source specifications</replaceable> }</literal></term>
Havoc Pennington's avatar
Havoc Pennington committed
270
271
272
273
274
275
     <listitem>
       <para>
        Defines the icon for a stock item.
       </para>
     </listitem>
  </varlistentry>
Owen Taylor's avatar
Owen Taylor committed
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
</variablelist>
</para>
<para>
The colors and background pixmaps are specified as a function of the
state of the widget. The states are:

<variablelist>
  <varlistentry>
    <term><literal>NORMAL</literal></term>
    <listitem>
      <para>
        A color used for a widget in its normal state
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>ACTIVE</literal></term>
    <listitem>
      <para>
        A variant of the <literal>NORMAL</literal> color used when the
        widget is in the %GTK_STATE_ACTIVE state, and also for
        the trough of a ScrollBar, tabs of a NoteBook
        other than the current tab and similar areas.
        Frequently, this should be a darker variant
        of the <literal>NORMAL</literal> color.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>PRELIGHT</literal></term>
    <listitem>
      <para>
        A color used for widgets in the %GTK_STATE_PRELIGHT state. This
        state is the used for Buttons and MenuItems
        that have the mouse cursor over them, and for 
        their children.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>SELECTED</literal></term>
    <listitem>
      <para>
        A color used to highlight data selected by the user.
        for instance, the selected ListItems in a List widget, and the
        selection in an Editable widget.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>INSENSITIVE</literal></term>
    <listitem>
      <para>
        A color used for the background of widgets that have
330
        been set insensitive with gtk_widget_set_sensitive()
Owen Taylor's avatar
Owen Taylor committed
331
332
333
334
335
336
337
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para>
338
339
340
Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
<literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
Owen Taylor's avatar
Owen Taylor committed
341
342
343
344
345
<literal>g</literal>, and <literal>b</literal> are
hex digits, or they can be specified as a triplet of floats
<literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
<replaceable>b</replaceable>}</literal>.
</para>
Havoc Pennington's avatar
Havoc Pennington committed
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409

<para>
In a <literal>stock</literal> definition, icon sources are specified as a
4-tuple of image filename, text direction, widget state, and size, in that
order.  Each icon source specifies an image filename to use with a given
direction, state, and size. The <literal>*</literal> character can be used as a
wildcard, and if direction/state/size are omitted they default to
<literal>*</literal>. So for example, the following specifies different icons to
use for left-to-right and right-to-left languages:
<programlisting>
stock["my-stock-item"] = 
{
  { "itemltr.png", LTR, *, * },
  { "itemrtl.png", RTL, *, * }
}
</programlisting>
This could be abbreviated as follows:
<programlisting>
stock["my-stock-item"] = 
{
  { "itemltr.png", LTR },
  { "itemrtl.png", RTL }
}
</programlisting>
</para>

<para>
You can specify custom icons for specific sizes, as follows:
<programlisting>
stock["my-stock-item"] = 
{
  { "itemmenusize.png", *, *, "gtk-menu" },
  { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting>
The sizes that come with GTK+ itself are <literal>"gtk-menu"</literal>,
<literal>"gtk-small-toolbar"</literal>, <literal>"gtk-large-toolbar"</literal>,
<literal>"gtk-button"</literal>, <literal>"gtk-dialog"</literal>. Applications
can define other sizes.
</para>

<para>
It's also possible to use custom icons for a given state, for example:
You can specify custom icons for specific sizes, as follows:
<programlisting>
stock["my-stock-item"] = 
{
  { "itemprelight.png", *, PRELIGHT },
  { "iteminsensitive.png", *, INSENSITIVE }, 
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}
</programlisting>
</para>

<para>
When selecting an icon source to use, GTK+ will consider text direction most
important, state second, and size third. It will select the best match based on
those criteria. If an attribute matches exactly (e.g. you specified
<literal>PRELIGHT</literal> or specified the size), GTK+ won't modify the image;
if the attribute matches with a wildcard, GTK+ will scale or modify the image to
match the state and size the user requested.
</para>

Owen Taylor's avatar
Owen Taylor committed
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
</refsect2>

<refsect2><title>Key bindings</title>
<para>
Key bindings allow the user to specify actions to be 
taken on particular key presses. The form of a binding
set declaration is:
</para>

<programlisting>
binding <replaceable>name</replaceable> {
  bind <replaceable>key</replaceable> { 
    <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
    ...
  }
  ...
}
</programlisting>

<para>
<replaceable>key</replaceable> is a string consisting of a 
series of modifiers followed by the name of a key. The
modifiers can be:
<simplelist>
<member><literal>&lt;alt&gt;</literal></member>
<member><literal>&lt;control&gt;</literal></member>
<member><literal>&lt;mod1&gt;</literal></member>
<member><literal>&lt;mod2&gt;</literal></member>
<member><literal>&lt;mod3&gt;</literal></member>
<member><literal>&lt;mod4&gt;</literal></member>
<member><literal>&lt;mod5&gt;</literal></member>
<member><literal>&lt;release&gt;</literal></member>
<member><literal>&lt;shft&gt;</literal></member>
<member><literal>&lt;shift&gt;</literal></member>
</simplelist>
<literal>&lt;shft&gt;</literal> is an alias for 
<literal>&lt;shift&gt;</literal> and 
<literal>&lt;alt&gt;</literal> is an alias for
<literal>&lt;mod1&gt;</literal>.
</para>

<para>
The action that is bound to the key is a sequence
of signal names (strings) followed by parameters for 
each signal. The signals must be action signals.
(See gtk_signal_new()). Each parameter can be
a float, integer, string, or unquoted string
representing an enumeration value. The types of
the parameters specified must match the types of the 
parameters of the signal.
</para>

<para>
Binding sets are connected to widgets in the
same manner as styles, with one addition. 
A priority can be specified for each pattern,
and within each type of pattern, binding sets
override other binding sets first by priority,
and only then by order of specification. (Later
overrides earlier). The priorities that can
be specified are (highest to lowest):
<simplelist>
<member><literal>HIGHEST</literal></member>
<member><literal>RC</literal></member>
<member><literal>APPLICATION</literal></member>
<member><literal>GTK</literal></member>
<member><literal>LOWEST</literal></member>
</simplelist>
<literal>RC</literal> is the default for bindings
read from an RC file, <literal>APPLICATION</literal>
should be used for bindings an application sets
up, and <literal>GTK</literal> is used for bindings
that GTK+ creates internally.
</para>
</refsect2>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT GtkRcStyle ##### -->
<para>
The #GtkRcStyle structure is used to represent a set
of information about the appearance of a widget.
This can later be composited together with other
#GtkRcStyle structures to form a #GtkStyle.
</para>

@name: 
@bg_pixmap_name: 
501
@font_desc: 
Owen Taylor's avatar
Owen Taylor committed
502
503
504
505
506
@color_flags: 
@fg: 
@bg: 
@text: 
@base: 
507
508
509
510
511
512
513
514
@xthickness: 
@ythickness: 

<!-- ##### STRUCT GtkRcStyleClass ##### -->
<para>

</para>

Owen Taylor's avatar
Owen Taylor committed
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589

<!-- ##### ENUM GtkRcFlags ##### -->
<para>
The #GtkRcFlags enumeration is used as a bitmask
to specify which fields of a #GtkRcStyle have been
set for each state.
</para>
<variablelist>
 <varlistentry><term> %GTK_RC_FG </term>
 <listitem>
   <para>
   If present, the foreground color has been set for this state.
   </para>
 </listitem>
 </varlistentry>
 <varlistentry><term> %GTK_RC_BG </term>
 <listitem>
   <para>
   If present, the background color has been set for this state.
   </para>
 </listitem>
 </varlistentry>
 <varlistentry><term> %GTK_RC_TEXT </term>
 <listitem>
   <para>
   If present, the text color has been set for this state.
   </para>
 </listitem>
 </varlistentry>
 <varlistentry><term> %GTK_RC_BASE </term>
 <listitem>
   <para>
   If present, the base color has been set for this state.
   </para>
 </listitem>
 </varlistentry>
</variablelist>

@GTK_RC_FG: 
@GTK_RC_BG: 
@GTK_RC_TEXT: 
@GTK_RC_BASE: 

<!-- ##### USER_FUNCTION GtkImageLoader ##### -->
<para>
A GtkImageLoader is used to load a filename found in
a RC file.
</para>

@window: the window for creating image
@colormap: the colormap for this image
@mask: a pointer to the location to store the mask
@transparent_color: the transparent color for the image
@filename: filename to load
@Returns: a #GtkPixmap representing @filename


<!-- ##### ENUM GtkRcTokenType ##### -->
<para>
The #GtkRcTokenType enumeration represents the tokens
in the RC file. It is exposed so that theme engines
can reuse these tokens when parsing the theme-engine
specific portions of a RC file.
</para>

@GTK_RC_TOKEN_INVALID: 
@GTK_RC_TOKEN_INCLUDE: 
@GTK_RC_TOKEN_NORMAL: 
@GTK_RC_TOKEN_ACTIVE: 
@GTK_RC_TOKEN_PRELIGHT: 
@GTK_RC_TOKEN_SELECTED: 
@GTK_RC_TOKEN_INSENSITIVE: 
@GTK_RC_TOKEN_FG: 
@GTK_RC_TOKEN_BG: 
@GTK_RC_TOKEN_TEXT: 
590
591
592
@GTK_RC_TOKEN_BASE: 
@GTK_RC_TOKEN_XTHICKNESS: 
@GTK_RC_TOKEN_YTHICKNESS: 
Owen Taylor's avatar
Owen Taylor committed
593
594
@GTK_RC_TOKEN_FONT: 
@GTK_RC_TOKEN_FONTSET: 
595
@GTK_RC_TOKEN_FONT_NAME: 
Owen Taylor's avatar
Owen Taylor committed
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
@GTK_RC_TOKEN_BG_PIXMAP: 
@GTK_RC_TOKEN_PIXMAP_PATH: 
@GTK_RC_TOKEN_STYLE: 
@GTK_RC_TOKEN_BINDING: 
@GTK_RC_TOKEN_BIND: 
@GTK_RC_TOKEN_WIDGET: 
@GTK_RC_TOKEN_WIDGET_CLASS: 
@GTK_RC_TOKEN_CLASS: 
@GTK_RC_TOKEN_LOWEST: 
@GTK_RC_TOKEN_GTK: 
@GTK_RC_TOKEN_APPLICATION: 
@GTK_RC_TOKEN_RC: 
@GTK_RC_TOKEN_HIGHEST: 
@GTK_RC_TOKEN_ENGINE: 
@GTK_RC_TOKEN_MODULE_PATH: 
611
612
@GTK_RC_TOKEN_IM_MODULE_PATH: 
@GTK_RC_TOKEN_IM_MODULE_FILE: 
Havoc Pennington's avatar
Havoc Pennington committed
613
614
615
@GTK_RC_TOKEN_STOCK: 
@GTK_RC_TOKEN_LTR: 
@GTK_RC_TOKEN_RTL: 
Owen Taylor's avatar
Owen Taylor committed
616
617
@GTK_RC_TOKEN_LAST: 

618
619
620
621
622
623
624
625
<!-- ##### FUNCTION gtk_rc_scanner_new ##### -->
<para>

</para>

@Returns: 


Owen Taylor's avatar
Owen Taylor committed
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
<!-- ##### FUNCTION gtk_rc_get_style ##### -->
<para>
Finds all matching RC styles for a given widget,
composites them together, and then creates a 
#GtkStyle representing the composite appearance.
(GTK+ actually keeps a cache of previously 
created styles, so a new style may not be
created.)
</para>

@widget: a #GtkWidget
@Returns: the resulting style. The caller should
reference the result, since GTK+ will retain the
initial reference count itself for the cache
of created styles.


<!-- ##### FUNCTION gtk_rc_add_widget_name_style ##### -->
<para>
Add a RcStyle that will be looked up by a match against
the widget's pathname. This is equivalent to a:
<programlisting>
widget PATTERN style STYLE
</programlisting>
statement in a RC file.
</para>

@rc_style: the #GtkRcStyle to use for widgets matching @pattern
@pattern: the pattern


<!-- ##### FUNCTION gtk_rc_add_widget_class_style ##### -->
<para>
Add a RcStyle that will be looked up by a match against
the widget's class pathname. This is equivalent to a:

<programlisting>
widget_class PATTERN style STYLE
</programlisting>
statement in a RC file.
</para>

@rc_style: the #GtkRcStyle to use for widgets matching @pattern
@pattern: the pattern


<!-- ##### FUNCTION gtk_rc_add_class_style ##### -->
<para>
Add a RcStyle that will be looked up by a matching against
the class heirarchy of the widget. This is equivalent to a:
<programlisting>
class PATTERN style STYLE
</programlisting>
statement in a RC file.
</para>

@rc_style: the #GtkRcStyle to use for widgets deriving from @pattern
@pattern: the pattern


<!-- ##### FUNCTION gtk_rc_parse ##### -->
<para>
Parse a given resource file.
</para>

@filename: the filename of a file to parse.


<!-- ##### FUNCTION gtk_rc_parse_string ##### -->
<para>
Parse resource information directly from a string.
</para>

@rc_string: a string to parse.


<!-- ##### FUNCTION gtk_rc_reparse_all ##### -->
<para>
If the modification time on any previously read file
has changed, discard all style information
and then reread all previously read RC files.
</para>

@Returns: %TRUE if the files were reread.


<!-- ##### FUNCTION gtk_rc_add_default_file ##### -->
<para>
Adds a file to the list of files to be parsed at the
end of gtk_init().
</para>

@filename: the pathname to the file.


<!-- ##### FUNCTION gtk_rc_get_default_files ##### -->
<para>
Retrieves the current list of RC files that will be parsed
at the end of gtk_init()
</para>

@Returns: A NULL terminated array of filenames. This memory
is owned by GTK+ and must not be freed by the application.
If you want to store this information, you should make a 
copy.


<!-- ##### FUNCTION gtk_rc_set_default_files ##### -->
<para>
Sets the list of files that GTK+ will read at the
end of gtk_init()
</para>

@filenames: A %NULL terminated list of filenames.


<!-- ##### FUNCTION gtk_rc_parse_color ##### -->
<para>
Parses a color in the format expected in a RC file.
</para>

@scanner: a #GtkScanner
@color: a pointer to a #GtkColor structure in which to store the result
@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
that was expected but not found.


<!-- ##### FUNCTION gtk_rc_parse_state ##### -->
<para>
Parses a #GtkStateType variable from the format expected
in a RC file.
</para>

@scanner: a #GtkScanner (must be initialized for parsing an RC file)
@state: A pointer to a #GtkStateType variable in which to
store the result.
@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
that was expected but not found.


<!-- ##### FUNCTION gtk_rc_parse_priority ##### -->
<para>
Parses a #GtkPathPriorityType variable from the format expected
in a RC file.
</para>

@scanner: a #GtkScanner (must be initialized for parsing an RC file)
@priority: A pointer to #GtkPathPriorityType variable in which
to store the result.
@Returns: %G_TOKEN_NONE if parsing suceeded, otherwise the token
that was expected but not found.


<!-- ##### FUNCTION gtk_rc_find_module_in_path ##### -->
<para>
Looks up a file in the current module path.
</para>

@module_file: The name of the module to search for.
@Returns: The filename, if found. (Must be freed with g_free()),
otherwise %NULL.


<!-- ##### FUNCTION gtk_rc_find_pixmap_in_path ##### -->
<para>
Looks up a file in the current pixmap path. If the file is
not found, it outputs a warning message using g_warning()
and returns %NULL.
</para>

@scanner: a #GtkScanner. Used for printing out warning messages
if the file is not found.
@pixmap_file: The name of the file to search for.
@Returns: The filename, if found. (Must be freed with g_free()),
otherwise %NULL.


<!-- ##### FUNCTION gtk_rc_get_module_dir ##### -->
<para>
Returns the directory in which GTK+ will look for
theme engines.
</para>

@Returns: The directory. (Must be freed with g_free())


812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
<!-- ##### FUNCTION gtk_rc_get_im_module_path ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_rc_get_im_module_file ##### -->
<para>

</para>

@Returns: 


Owen Taylor's avatar
Owen Taylor committed
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
<!-- ##### FUNCTION gtk_rc_get_theme_dir ##### -->
<para>
Returns the standard directory in which themes should
be installed. (GTK+ does not actually use this directory
itself.)
</para>

@Returns: The directory. (Must be freed with g_free())


<!-- ##### FUNCTION gtk_rc_set_image_loader ##### -->
<para>
Sets the function that GTK+ will use to load images 
</para>

@loader: the #GtkImageLoader to use


<!-- ##### FUNCTION gtk_rc_load_image ##### -->
<para>
Internal function. Loads an image using the current
image loader.
</para>

@colormap: the colormap to use for the image
@transparent_color: the transparent color for the image
@filename: the filename of the image file
@Returns: a #GtkPixmap representing @filename


<!-- ##### FUNCTION gtk_rc_style_new ##### -->
<para>
Create a new #GtkRcStyle with no fields set and
a reference count of 1.
</para>

@Returns: the newly create #GtkRcStyle


867
868
869
870
871
872
873
874
875
<!-- ##### FUNCTION gtk_rc_style_copy ##### -->
<para>

</para>

@orig: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
<!-- ##### FUNCTION gtk_rc_style_ref ##### -->
<para>
Increment the reference count of a #GtkRcStyle.
</para>

@rc_style: a #GtkRcStyle


<!-- ##### FUNCTION gtk_rc_style_unref ##### -->
<para>
Decrement the reference count of a #GtkRcStyle and
free if the result is 0.
</para>

@rc_style: a #GtkRcStyle