							1999-05-31
							Emil Brink

			gentoo File Styles

1. INTRODUCTION
This file documents the file style subsystem in gentoo. A good
understanding of file styles is important in order to maximize
your comfort in gentoo.

2. NEW vs. OLD STYLE SYSTEM
If you've never used gentoo prior to version 0.11.7, you can skip
this section entierly, since it deals with changes to the style
system that occured with the mentioned release.
	As of 0.11.7, file style properties are fully dynamic.
This means that there are no "built-in" properties of any kind,
neither visual nor action. Prior versions of gentoo featured a
set of built-in properties (they were Default, View, Edit, Print
and Play).
	There was a need to support user-defined actions, but
I couldn't find a clean way of extending the old code to support
that. So I tore it all away, designed a style system with fully
dynamic properties, and implemented that instead. The style system
in gentoo 0.11.7 is the result.
	If you want a particular property to be available, just
add it at a suitable point in the style tree. It will be propagated
by inheritance to all styles below the one where you added it.
	If you want to change the value of an inherited property
at some point in the tree, just override it. The new value will
propagate downwards.
	Older versions of gentoo featured a command for each built-
in property (the FileDefault, FileView, ... commands). Since I don't
want to dynamically add commands as properties are created, these
commands have been replaced by the single FileAction command. If
called with no parameters, this command will run the Default action
property. If called with an "action=X" argument, it will run the
property called X.


3. WHAT IS A STYLE?
A style is an abstract object. Its main purpose is to serve as a
container for a set of related "properties", and to provide an
inheritance hierarchy for these properties. Styles are tightly
coupled to the concept of "types"; each type is always connected
to exactly one style.
	Styles are arranged in a tree. The tree has a single root
style (commonly called "Root", although you can rename it if you
want to) and as many child styles as you need. The tree can have
any depth; you can add child styles to child styles to build the
hierarchy up recursively.

4. WHAT IS A PROPERTY?
Properties are what make styles useful. A property is a named value
of a certain type.
	Currently, three different types of properties are supported
by gentoo: colors, icons and actions. The two former are usually
refered to as "visual" properties.
	The point of properties is to contain the information gentoo
needs to display and handle dirpane rows of various types in a use-
ful and correct way.

4.1 Property Inheritance
The properties are inherited downwards in the tree, from the first
style that define them, down to all its children. This means that
if the root style defines a property called "A", all child styles
(i.e., all other styles) will also have a property called "A" with
the value defined by the root.
	At any style, you can override the inherited value of a
property, thus causing the new value to propagate instead of the
old.
	Using inheritance saves work, and makes maintaining the
styles much easier and less error-prone. Basically, it is a good
thing. :)

4.2 Visual Properties
Visual properties control how gentoo renders the rows of a pane.
There are three visual properties in use: background and foreground
colors, and icon. The two former control the colors used for row
background and text (foreground), when the row has not been sel-
ected by the user. As soon as a row is selected, it reverts to
using GTK+'s standard selection colors. The icon property contains
the name of the icon graphics to use for the style.

4.3 Action Properties
Action properties specify commands that can operate on files of
a given type. You then use the FileAction command to envoke these
commands by property name.
	All styles should have a default action property (typically
called "Default"), inherited from the root. The "Default" action
is what is executed when you double click on a row in a pane. For
many styles, it makes sense to make the default action cause the
files contents to be viewed, by setting the property to "FileAction
action=View" and defining a suitable View action.


5. CONFIGURING STYLES
To modify the current style tree, open up gentoo's configuration
window (execute the builtin command Configure). Then click the tab
labelled "File Styles". It might be helpful to have the window open
and visible while reading this, since there will be many references
to various things in the window.
	The style config page can be divided vertically into four
areas of interest.
	At the top is the style tree itself. It shows, using a nice
tree widget, the current style tree. At the top of the tree is the
root style, and below it are all its children. The connections bet-
ween styles are shown with lines.

5.1 Name and Parent
Below the style tree are two text entry fields, labelled Name and
Parent, respectively.
	The Name entry field shows the name of the currently selected
style, and lets you type directly to rename the style.
	The Parent text field is not editable. When a style is
selected, it shows the name of the style's immediate parent. You can
click the button to the right of the field (with the magnifying glass)
to pop up a dialog that lets you select a new parent for the style.
	If the current style has any child styles of its own, the
entire branch will be moved if you change the parent.

5.2 Properties
Underneath the name & parent fields is a frame titled "Inherited
Properties". It contains a notebook with two pages: one for visual
properties, and one for the actions.

5.2.1 Visual Properties
The visual property page contains a little preview, showing you how
the colors and icon look together.
	It also holds three frames, one for each of the three
standard visual properties (background color, foreground color, and
icon).
	To set a visual property, make sure the "Override Parent's?"
check button is checked (depressed). Then click the button below the
check button, the one with the "Edit..." or "Pick..." label. This
will pop up a dialog where you can make the desired changes.
	To revert back to the parent's value for a given property,
simply uncheck the override check button.

5.2.2 Action Properties
The action property page contains a list of all action properties
the current style has. Note that not all of these are actually set
in the style itself: the list shows inherited properties as well.
	To modify an action property's value (its command), just
select it in the list and type the new value in the entry box
labelled "Command". Clicking the magnifying-glass button to the
right of the entry field pops up a dialog where you can choose
from the currently defined commands.
	Changing the command of an action property automatically
overrides the property, i.e. the new value will be propagated to
any child styles, and the inherited one will be ignored from this
style on. Note that even if you change it back to the same value
as the parent has, it will remain overridden.
	You can add a new action property by clicking on the
button labelled "Add Action...". This will pop up a dialog asking
you for the name of the action to add. I suggest using a single
word, with an uppercase initial (like "Default", "View", "Edit",
and so on). Initially, the property will not have a useful value
assigned to it. Select it in the list, and follow the instructions
given above to set the value you want.
	Removing a property you added is simple: just select it,
and then click the button labeled "Delete Action" (it's to the
right of the "Add Action..." button). This will immediately remove
the action from the current style and all its children. If the
delete-button reads "Revert to Inherited Command" rather than
"Delete Action", the selected action is an overridden inherited
one. You cannot remove inherited properties, but you can make them
assume the inherited value rather than the one set locally in the
current style, by clicking this button. If the button is ghosted
(drawn greyed out), the property is a normal inherited one, and
can be neither removed nor reverted. This is the normal state,
and probably the one you'll see the most often.


5.3 Adding and Deleting Styles
To add a new style, first select the style you wish to have as
parent for the new one. Then click the "Add" button in the bottom
of the page. This will add a new style as a child to the previously
selected one.
	To delete a style, select it and click the "Delete" button
in the bottom-right corner of the page. If the selected style has
any children, deleting it will also remove the children. This might
be very inconvenient if done to the wrong style, so there will be
a confirmation dialog if the style has children.
