[svn-upgrade] Integrating new upstream version, ion3-doc (20080103)

[ion3-doc.git] / de.tex

diff --git a/de.tex b/de.tex
index 4697dc6912d1eb6ef006da7491a5bc25c507fd1e..7fd5a8b001fbfd6e9390fa52de8cfa53c71cb640 100644 (file)
--- a/de.tex
+++ b/de.tex
@@ -5,7 +5,9 @@
 This chapter first gives in section \ref{sec:engines} a general outline 
 of how drawing engines are used, of style specifications and then
 in section \ref{sec:defaultde} describes how to specify styles
 This chapter first gives in section \ref{sec:engines} a general outline 
 of how drawing engines are used, of style specifications and then
 in section \ref{sec:defaultde} describes how to specify styles

-for the default drawing engine.
+for the default drawing engine. Some additional settings and
+user attributes are explained in Sections \ref{sec:grmisc}.
+

 
 \section{Drawing engines, style specifications and sub-styles}
 \label{sec:engines}
 
 \section{Drawing engines, style specifications and sub-styles}
 \label{sec:engines}


@@ -13,7 +15,7 @@ for the default drawing engine.
 
 Ion's drawing routines are abstracted into so-called drawing engine
 modules that can, again depending on the system, be dynamically
 
 Ion's drawing routines are abstracted into so-called drawing engine
 modules that can, again depending on the system, be dynamically

-loaded as needed. The drawing engine modules provide ''brushes''
+loaded as needed. The drawing engine modules provide ``brushes''

 that objects can use to draw some high-level primitives such
 as borders and text boxes (in addition to simple text and rectangle
 drawing) on their windows and configure e.g. the shape and 
 that objects can use to draw some high-level primitives such
 as borders and text boxes (in addition to simple text and rectangle
 drawing) on their windows and configure e.g. the shape and 


@@ -28,16 +30,16 @@ are strings of the form
 element1-element2-...-elementn
 \end{verbatim}
 
 element1-element2-...-elementn
 \end{verbatim}
 

-An example of such a style specification is \code{tab-frame};
+An example of such a style specification is \codestr{tab-frame};

 see the table in subsection \ref{sec:styles} for more styles.
 
 When an object asks for a brush of certain style, the selected
 drawing engine will attempt to find the closest match to this
 specification. The styles/brushes defined by the drawing engines 
 see the table in subsection \ref{sec:styles} for more styles.
 
 When an object asks for a brush of certain style, the selected
 drawing engine will attempt to find the closest match to this
 specification. The styles/brushes defined by the drawing engines 

-may have asterisks (\verb!*!) as some of the elements indicating
+may have asterisks (\codestr{*}) as some of the elements indicating

 a match to anything. Exact matches are preferred to asterisk
 matches and longer matches to shorter. For example, let a brush
 a match to anything. Exact matches are preferred to asterisk
 matches and longer matches to shorter. For example, let a brush

-for style \code{foo-bar-baz} be queried, then the following
+for style \codestr{foo-bar-baz} be queried, then the following

 brushes are in order of preference:
 
 \begin{verbatim}
 brushes are in order of preference:
 
 \begin{verbatim}


@@ -70,19 +72,19 @@ tag and drag states.)
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}

-\code{frame} & Style for frames. 
-       Substyle attributes: \code{active}/\code{inactive} 
-       (mutually exclusive) and
-       \code{quasiactive}\nobreak/\code{not_quasiactive}. 
+\codestr{frame} & Style for frames. 
+       Substyle attributes: \codestr{active}/\codestr{inactive} 
+       (mutually exclusive), and
+       \codestr{quasiactive}.

        A frame is ``quasiactive'' when an active region
        A frame is ``quasiactive'' when an active region

-       has a backlink to it, such as a detached window. \\
-\code{frame-tiled} & A more specific style for tiled frames.
-        Substyle attributes as for \code{frame}. \\
-\code{frame-tiled-alt} & An alternative style for tiled frames.
+       has a back-link to it, such as a detached window. \\
+\codestr{frame-tiled} & A more specific style for tiled frames.
+        Substyle attributes as for \codestr{frame}. \\
+\codestr{frame-tiled-alt} & An alternative style for tiled frames.

         Often used to disable the tab-bar. \\
         Often used to disable the tab-bar. \\

-\code{frame-floating} & A more specific style for floating
+\codestr{frame-floating} & A more specific style for floating

         frames. \\
         frames. \\

-\code{frame-transient} & A more specific style for frames
+\codestr{frame-transient} & A more specific style for frames

         containing transient windows. \\
 \end{tabularx}
 
         containing transient windows. \\
 \end{tabularx}
 


@@ -90,25 +92,25 @@ tag and drag states.)
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}

-\code{tab} & Style for frames' tabs and menu entries. 
+\codestr{tab} & Style for frames' tabs and menu entries. 

        Substyle attributes:
        Substyle attributes:

-       \code{active}\nobreak/\code{inactive} and
-       \code{selected}\nobreak/\code{unselected} \\
-\code{tab-frame} & A more specific style for frames' tabs.
-        Additional substyle attributes include:
-       \code{tagged}\nobreak/\code{not_tagged},
-       \code{dragged}\nobreak/\code{not_dragged},
-       \code{activity}\nobreak/\code{no_activity} and
-       \code{quasiactive}\nobreak/\code{not_quasiactive}. \\
-\code{tab-frame-tiled}, & \\
-\code{tab-frame-tiled-alt}, & \\
-\code{tab-frame-floating}, & \\
-\code{tab-frame-transient} & More specific styles for frames in the
+       \codestr{active}/\codestr{inactive} and
+       \codestr{selected}/\codestr{unselected} \\
+\codestr{tab-frame} & A more specific style for frames' tabs.
+        Additional substyle attributes include those of
+        the \codestr{frame} style, as well as tab-specific
+       \codestr{tagged}/\codestr{not\_tagged},
+       \codestr{dragged}/\codestr{not\_dragged}, and
+       \codestr{activity}/\codestr{no\_activity}. \\
+\codestr{tab-frame-tiled}, & \\
+\codestr{tab-frame-tiled-alt}, & \\
+\codestr{tab-frame-floating}, & \\
+\codestr{tab-frame-transient} & More specific styles for frames in the

         different modes. \\
         different modes. \\

-\code{tab-menuentry} & A more specific style for entries in \type{WMenu}s. 
-        Additional substyle attributes include \code{submenu} and
-        occasionally also \code{activity} is used.\\
-\code{tab-menuentry-bigmenu} & 
+\codestr{tab-menuentry} & A more specific style for entries in \type{WMenu}s. 
+        Additional substyle attributes include \codestr{submenu} and
+        occasionally also \codestr{activity} is used.\\
+\codestr{tab-menuentry-bigmenu} & 

         An alternate style for entries in \type{WMenu}s. \\
 \end{tabularx}
 
         An alternate style for entries in \type{WMenu}s. \\
 \end{tabularx}
 


@@ -116,16 +118,21 @@ tag and drag states.)
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Style name & Description}

-\code{input} & A style for \type{WInput}s. \\
-\code{input-edln} & A more specific style for \type{WEdln}s. 
-       Substyle attributes: \code{selection} for selected text and
-       \code{cursor} for the cursor indicating current editing point. \\
-\code{input-message} & A more specific style for \type{WMessage}s. \\
-\code{input-menu} & A more specific style for \type{WMenu}s. \\
-\code{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
-\code{moveres_display} & The box displaying position/size when
+\codestr{input} & A style for \type{WInput}s. \\
+\codestr{input-edln} & A more specific style for \type{WEdln}s. 
+       Substyle attributes: \codestr{selection} for selected text and
+       \codestr{cursor} for the cursor indicating current editing point. \\
+\codestr{input-message} & A more specific style for \type{WMessage}s. \\
+\codestr{input-menu} & A more specific style for \type{WMenu}s. \\
+\codestr{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
+\codestr{moveres\_display} & The box displaying position/size when

        moving or resizing frames. \\
        moving or resizing frames. \\

-\code{dock} & The dock. \\     
+\codestr{stdisp} & Any status display. \\
+\codestr{stdisp-dock} & The dock. \\
+\codestr{stdisp-statusbar} & The statusbar. Substyles include:
+    the name of any monitor/meter (such as \codestr{date}), and 
+    the supplied hint. Typical hints are: \codestr{normal},
+    \codestr{important}, and \codestr{critical}. \\

 \end{tabularx}
 
 
 \end{tabularx}
 
 


@@ -153,13 +160,13 @@ end
 
 The \fnref{gr.select_engine} function sees if the engine
 given as argument is registered (the default drawing engine is
 
 The \fnref{gr.select_engine} function sees if the engine
 given as argument is registered (the default drawing engine is

-simply called ''de''). If the engine could not be found, it
+simply called ``de''). If the engine could not be found, it

 tries to load a module of the same name. If the engine still
 tries to load a module of the same name. If the engine still

-is not registered, \fnref{gr.select_engine} returns \code{false}
+is not registered, \fnref{gr.select_engine} returns \codestr{false}

 and in this case we also exit the style setup script.
 If the engine was found, \fnref{gr.select_engine} sees that
 further requests for brushes are forwarded to that engine
 and in this case we also exit the style setup script.
 If the engine was found, \fnref{gr.select_engine} sees that
 further requests for brushes are forwarded to that engine

-and returns \code{true}.
+and returns \codestr{true}.

 
 Before defining new styles it may be a good idea to clear old
 styles from memory so if the old configuration defines more
 
 Before defining new styles it may be a good idea to clear old
 styles from memory so if the old configuration defines more


@@ -230,16 +237,16 @@ in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \var{highlight_colour} &  
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \var{highlight_colour} &  

-       Colour for the ''highlight'' part of a border. \\
+       Colour for the ``highlight'' part of a border. \\

 \var{shadow_colour}    &  
 \var{shadow_colour}    &  

-       Colour for the ''highlight'' part of a border. \\
+       Colour for the ``shadow'' part of a border. \\

 \var{foreground_colour} &  
        Colour for the normal drawing operations, e.g. text. \\
 \var{background_colour} &  
        Window background colour (unless transparency is enabled) and
        background colour boxes. \\
 \var{padding_colour} &  
 \var{foreground_colour} &  
        Colour for the normal drawing operations, e.g. text. \\
 \var{background_colour} &  
        Window background colour (unless transparency is enabled) and
        background colour boxes. \\
 \var{padding_colour} &  

-       Colour for the ''padding'' part of a border border. Set to 
+       Colour for the ``padding'' part of a border border. Set to 

        \var{background_colour} if unset. \\
 \end{tabularx}
 
        \var{background_colour} if unset. \\
 \end{tabularx}
 


@@ -252,12 +259,12 @@ indicating a number of pixels.
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \var{border_style} & A string indicating the style of border; one of
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \var{border_style} & A string indicating the style of border; one of

-                    elevated/inlaid/ridge/groove as seen in the
-                    above sketch. \\
+                    \codestr{elevated}/\codestr{inlaid}/\codestr{ridge}/\codestr{groove}
+                    as seen in the above sketch. \\

 \var{border_sides} & A string indicating which sides of the border
 \var{border_sides} & A string indicating which sides of the border

-                     to draw: all/tb/lr for all, top and bottom, and
-                     left and right. To control between left/right
-                     and top/bottom, use the pixel options below. \\
+                     to draw: \codestr{all}/\codestr{tb}/\codestr{lr} for all, 
+                     top and bottom, and left and right. To control between
+                     left/right and top/bottom, use the pixel options below. \\

 \var{highlight_pixels} &  
        Width of the highlight part of the border in pixels. \\
 \var{shadow_pixels}    &  
 \var{highlight_pixels} &  
        Width of the highlight part of the border in pixels. \\
 \var{shadow_pixels}    &  


@@ -276,7 +283,7 @@ indicating a number of pixels.
 \var{font} & Font to be used in text-drawing operations; standard X font
             name. \\
 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
 \var{font} & Font to be used in text-drawing operations; standard X font
             name. \\
 \var{text_align} & How text is to be aligned in text boxes/tabs; one of

-                  the strings left\nobreak/right\nobreak/center. \\
+                  the strings \codestr{left}/\codestr{right}/\codestr{center}. \\

 \end{tabularx}
 
 
 \end{tabularx}
 
 


@@ -295,13 +302,13 @@ indicating a number of pixels.
 \subsubsection{Substyles}
 
 As discussed in previous sections, styles may have substyles to e.g.
 \subsubsection{Substyles}
 
 As discussed in previous sections, styles may have substyles to e.g.

-indicate different states of the object being drawn. The ''de'' engine
+indicate different states of the object being drawn. The ``de'' engine

 limits what can be configured in substyles to the set of colours in the
 first table above, but also specifically interprets for the main style
 limits what can be configured in substyles to the set of colours in the
 first table above, but also specifically interprets for the main style

-\code{tab-frame} the substyles \code{*-*-tagged} and \code{*-*-*-dragged}
+\codestr{tab-frame} the substyles \codestr{*-*-tagged} and \codestr{*-*-*-dragged}

 by, respectively, drawing a right angle shape at the top right corner 
 of a tab and by shading the tab with a stipple pattern. Also for
 by, respectively, drawing a right angle shape at the top right corner 
 of a tab and by shading the tab with a stipple pattern. Also for

-menus the substyles \code{*-*-submenu} are handled as a special case.
+menus the substyles \codestr{*-*-submenu} are handled as a special case.

 
 Substyles are defined with the function \fnref{de.substyle} within the
 table defining the main style. The parameters to this function are 
 
 Substyles are defined with the function \fnref{de.substyle} within the
 table defining the main style. The parameters to this function are 


@@ -359,18 +366,32 @@ de.defstyle("tab-frame", {
 
 
 \section{Miscellaneous settings}
 
 
 \section{Miscellaneous settings}

+\label{sec:grmisc}
+
+
+\subsection{Frame user attributes}
+
+The function \fnref{WFrame.set_grattr} may be used to give frames
+(and their tabs) arbitrary extra attributes to be passed to the
+drawing engine. Hence, by configuring such substyles in the style
+configuration files, and turning on the attribute when needed, 
+scripts may display visual cues related to the frame. There is
+also one extra attribute specially interpreted by the default
+drawing engine: the \codestr{numbered} attribute, which causes 
+numbers to be displayed on the tabs.
+
+
+\subsection{Extra fields for style \codestr{frame}}

 
 The following style fields are independent of the drawing engine used,
 but are related to objects' styles and therefore configured in the drawing
 engine configuration file.
 
 
 The following style fields are independent of the drawing engine used,
 but are related to objects' styles and therefore configured in the drawing
 engine configuration file.
 

-\subsection{Extra fields for style \code{frame}}
-

 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \code{bar} & Controls the style of the tab-bar. Possible values
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \code{bar} & Controls the style of the tab-bar. Possible values

-        are the strings \code{"none"}, \code{"inside"}, \code{"outside"}
-        and \code{"shaped"}, with the last providing the PWM-style
+        are the strings \codestr{none}, \codestr{inside}, \codestr{outside}
+        and \codestr{shaped}, with the last providing the PWM-style

         tab-bars for floating frames. \\
 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
         the shaped style, given that this number times number of tabs
         tab-bars for floating frames. \\
 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
         the shaped style, given that this number times number of tabs


@@ -380,15 +401,17 @@ engine configuration file.
        interval $(0, 1]$.
 \end{tabularx}
 
        interval $(0, 1]$.
 \end{tabularx}
 

-\subsection{Extra fields for style \code{dock}}
+
+
+\subsection{Extra fields for style \codestr{dock}}

 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \code{outline_style} & How borders are drawn:
 
 \begin{tabularx}{\linewidth}{lX}
 \tabhead{Field  & Description}
 \code{outline_style} & How borders are drawn:

-                       \code{"none"} -- no border,
-                       \code{"all"} -- border around whole dock,
-                       \code{"each"} -- border around each dockapp. \\
-\code{tile_size} & A table with entries \code{width} and \code{height},
+                       \codestr{none} -- no border,
+                       \codestr{all} -- border around whole dock,
+                       \codestr{each} -- border around each dockapp. \\
+\code{tile_size} & A table with entries \codestr{width} and \codestr{height},

        indicating the width and height of tiles in pixels.
 \end{tabularx}
 
        indicating the width and height of tiles in pixels.
 \end{tabularx}