RC file documentation

[Federico Mena Quintero <federico ximian com>]

I think I found a few typos in the RC file documentation.  They are
fixed in the attached patch.  Can someone with good knowledge of the RC
system please take a look?

Also, I was looking at bug #142417, which is basically about:

- You have this in your .gtkrc:

	widget_class "*.Foo.*" style "Bar"

- You have a FooSubclass that inherits from class Foo

- Children of FooSubclass don't get style "Bar" because widget_class
doesn't pay attention to type inheritance, just exact class names.

The way I see RC files, you would use things as follows:

1. Some funny applications like 3D modellers like to use color-coded
widgets:

http://www.ixbt.com/video/profcard/05-2002/images/screenshots/design-tests.png

The way I'd write such an application with GTK+ is by creating
containers for each color group, setting the widget name of those
containers, and then creating an app-specific gtkrc file:

	vbox_1 = gtk_vbox_new (...);
	gtk_widget_set_name (vbox_1, "vbox_for_object_commands");

	button = gtk_button_new_with_label ("Cylinder");
	gtk_box_pack_start (vbox_1, button, ...);
	button = gtk_button_new_with_label ("Sphere");
	gtk_box_pack_start (vbox_1, button, ...);

	vbox_2 = gtk_vbox_new (...);
	gtk_widget_set_name (vbox_2, "vbox_for_mode_commands");

	button = gtk_button_new_with_label ("Surface editor");
	gtk_box_pack_start (vbox_2, button, ...);
	button = gtk_button_new_with_label ("Image editor");
	gtk_box_pack_start (vbox_2, button, ...);

	
	widget "*.vbox_for_object_commands.*" style "RedBackground"
	widget "*.vbox_for_mode_commands.*" style "BlueBackground"

I don't think it's very useful to use class names in widget paths, since
widget paths are precisely to use widget names.

Definition:  Widget paths are to be able to reach particular widgets,
not whole classes of widgets or generic subhierarchies.  Therefore, it
doesn't make sense to follow type inheritance for widget paths.

2. Themes define styles for whole classes of widgets.  They want to use
things like

	widget_class "*.GtkMenuItem.*" style "StyleForMenuItems"

Bug #142417 mentions the fact that this line won't work for children of
a GtkCheckMenuItem:  even though GtkCheckMenuItem inherits from
GtkMenuItem, type inheritance is not used for widget_class lines in
gtkrc.  So, themes have to put this in their rc files:

	widget_class "*.GtkMenuItem.*" style "StyleForMenuItems"
	widget_class "*.GtkCheckMenuItem.*" style "StyleForMenuItems"
	widget_class "*.GtkRadioMenuItem.*" style "StyleForMenuItems"
	widget_class "*.GtkSeparatorMenuItem.*" style "StyleForMenuItems"
	...

Definition:  Class paths are used to reach generic subhierarchies of
widgets.  If this is right, then I think the bug is valid:  widget_class
should use type inheritance to make it easier to write themes.  Perhaps
more importantly, this is also an issue for language bindings; some of
them create glue classes like GlueGtkMenuItem, and then themes don't
work for them.

3. Class matching is to reach any widget which inherits from a
particular class:

	class "GtkButton" style "StyleForButtons"

Widgets of type GtkButton or its descendants will get the
StyleForButtons.  Children of these containers will not get that style,
however.  You can use this to say "I want thick frames and buttons" by
putting this in your .gtkrc:

	style "thick" {
		xthickness = 10
		ythickness = 10
	}

	class "GtkFrame" style "thick"
	class "GtkButton" style "thick"

However, you don't want thick GtkEntries, so this works.  If you had
used this instead:

	widget_class "*.GtkFrame.*" style "thick"

it would mean "make everything inside a GtkFrame be thick", so an entry
inside a frame would also be thick, which is not what you want.


Summary:  in gtkrc files,

1. "widget" is to reach particular widgets by name, used for funny apps
2. "widget_class" is to reach all widgets in a generic subhierarchy,
used for themes
3. "class" is to reach a particular class of widgets, but not their
children.

Are all of the assumptions above correct?  If so, I could use this text
to clarify the documentation, and we would have the bug mentioned in
(2).

  Federico

Index: gtkrc.sgml
===================================================================
RCS file: /cvs/gnome/gtk+/docs/reference/gtk/tmpl/gtkrc.sgml,v
retrieving revision 1.83
diff -u -r1.83 gtkrc.sgml
--- gtkrc.sgml	6 Mar 2004 22:46:44 -0000	1.83
+++ gtkrc.sgml	13 Jul 2004 19:15:47 -0000
@@ -55,7 +55,7 @@
 widget "mywindow.*.GtkEntry" style "my-entry-class"
 </programlisting></informalexample>
 attaches the style <literal>"my-entry-class"</literal>
-to all widgets whose <firstterm>widget class</firstterm>
+to all widgets whose <firstterm>widget path</firstterm>
 matches the <firstterm>pattern</firstterm>
 <literal>"mywindow.*.GtkEntry"</literal>.
 </para>
@@ -73,11 +73,11 @@
 the widget path, the name assigned by
 gtk_widget_set_name() is used
 if present, otherwise the class name of the widget, while
-for the widget path, the class name is always used.
+for the class path, the class name is always used.
 </para>
 <para>
 So, if you have a #GtkEntry named
-<literal>"myentry"</literal>, inside of a of a window
+<literal>"myentry"</literal>, inside of a box, inside of a window
 named <literal>"mywindow"</literal>, then the
 widget path is: <literal>"mwindow.GtkHBox.myentry"</literal>
 while the class path is: <literal>"GtkWindow.GtkHBox.GtkEntry"</literal>.