Doucmentation des path tags

1 files changed, 139 insertions, 52 deletions

diff --git a/doc/refman.tex b/doc/refman.tex
index 3ab13c7..44b87e8 100644
--- a/doc/refman.tex
+++ b/doc/refman.tex
@@ -55,7 +55,7 @@
 
 
 \usepackage{html}
-\usepackage{a4wide}
+\usepackage[widemargins]{a4}
 \usepackage{makeidx}
 
 
@@ -137,7 +137,7 @@
   \index{#2}
   \latexhtml{\ifpdf\hyperlink{attrtype.#3}{\ident{#3}}\hyperdef{attribute}{#1#2}{}\fi}{%
     \hyperref[no]{\tt \bf #3}{\ident{#3}}{attrtype:#3}}
-  \begin{quotation}\vspace{-\baselineskip}#4\end{quotation}
+  \begin{quotation}\vspace{-\baselineskip}#4\vspace{-0.8\baselineskip}\end{quotation}
   }
 
 % first argument : item type or 'option'
@@ -244,7 +244,7 @@ In order to use the openGL features, you need the support of the GLX extension o
 your X11 server. Of course, performances will be dependant of your graphic card.  At
 the time of writing, NVidia drivers for XFree86 R4.1 are doing a nice job. A laptop
 with a GeForce GO graphic card works nice for non trivial applications.  We also
-succeded in using Zinc with openGL on the Exceed X11 server (running on windows and
+succeeded in using Zinc with openGL on the Exceed X11 server (running on windows and
 developped by Hummingbird) with the 3D extension.
 
 As an exemple of Zinc capabilities when combined with openGL, we implemented
@@ -479,7 +479,6 @@ The Zinc command creates a new Zinc widget, the general form is
 
 {\tt\large \$version = \$mainwindow->zinc();}
 {\tt\large \$Tk::Zinc::VERSION;}
-
 \end{quotation}
 
 These two expressions can be used to get the version of Zinc. The string returned by the second expression also details the graphic head available. For example : ``zinc-version-3205d X11 GL''.
@@ -1016,62 +1015,150 @@ quantization errors, it is better to turn off borders or outlines in this case.
 \concept{tagOrId}
 
 \section{Item ids}
-Each item is associated with a unique numerical id which is returned by the \cmdref{add}
-or \cmdref{clone} commands. All commands on items accept those ids as (often first)
-parameter in order to uniquely identify on which item they should operate. When an id has
-been allocated to an item, it is never collected even after the item has been destroyed,
-in a Zinc session two items cannot have the same id. This property can be quite useful
-when used in conjonction with tags, which are described below.
+Each item is associated with a unique numerical id which is returned by the
+\cmdref{add} or \cmdref{clone} commands. All commands on items accept those
+ids as (often first) parameter in order to uniquely identify on which item
+they should operate. When an id has been allocated to an item, it is never
+collected even after the item has been destroyed, in a Zinc session two
+items cannot have the same id. This property can be quite useful when used
+in conjonction with tags, which are described below.
 
 \section{Tags}
-Apart from an id, an item can be associated with as many symbolic names as it may be
-needed by an application. Those names are called tags and can be any string which does not
-form a valid id (an integer). Tags exists, and may be used in commands, even if no item
-are associated with them. In contrast an item id doesn't exist if its item is no longer
-around and thus it is illegal to use it. Tags can be used to group items to do some
-action, or to mark an item that has a special function. Many other tasks can be solved
-with tags once one gets used to them.
-
-Two special tags are implicitly managed by Zinc. The tag \ident{all} is associated with
-all items in Zinc. The tag \ident{current} is always associated with the topmost item
-that lies under the mouse pointer. If no such item exists, no item has this tag.
-
-In commands, tags can be used almost anywhere an item id would be legal.  In the command
-descriptions, the expression \ident{tagOrId} means that it is legal to provide either a
-tag or an item id. This means that virtually all actions can be either performed on a
-specific item by using its id or on a whole set of items by using a tag.  In order for
-this collective behavior to be useful, if a command or an attribute does not apply to an
-item named by the tag, it is simply ignored, no error will be reported (This may yet not
-be the case with all commands, please report infringements).
-
-Everywhere a \ident{tagOrId} can be specified as a target for some action, it is possible to
-give a logical expression of tags and ids. The available boolean operators include
-logical and \verb+&&+, logical or \verb+||+, logical xor \verb+^+, logical not \verb+!+
-and subexpression grouping \verb+()+. Here is an example of a \cmdref{bbox} command
-called on a set of items defined by a logical expression. Note that tags and ids
-can be mixed.
+Apart from an id, an item can be associated with as many symbolic names as
+it may be needed by an application. Those names are called tags and can be
+any string which does not form a valid id (an integer). However the
+following characters may not be used to form a tag: \verb+. * ! ( ) & | :+.
+Tags exists, and may be used in commands, even if no item are associated
+with them. In contrast an item id doesn't exist if its item is no longer
+around and thus it is illegal to use it. Tags can be used to group items to
+do some action, or to mark an item that has a special function. Many other
+tasks can be solved with tags once one gets used to them.
+
+Two special tags are implicitly managed by Zinc. The tag \ident{all} is
+associated with all items in Zinc. The tag \ident{current} is always
+associated with the topmost item that lies under the mouse pointer. If no
+such item exists, no item has this tag.
+
+In commands, tags can be used almost anywhere an item id would be legal.
+In the command descriptions, the expression \ident{tagOrId} means that it
+is legal to provide either a tag or an item id. This means that virtually
+all actions can be either performed on a specific item by using its id or
+on a whole set of items by using a tag.  In order for this collective
+behavior to be useful, if a command or an attribute does not apply to an
+item named by the tag, it is simply ignored, no error will be reported
+(This may yet not be the case with all commands, please report
+infringements).
+
+Everywhere a \ident{tagOrId} can be specified as a target for some action,
+it is possible to give a logical expression of tags and ids. The available
+boolean operators include logical and \verb+&&+, logical or \verb+||+,
+logical xor \verb+^+, logical not \verb+!+ and subexpression grouping
+\verb+()+. Here is an example of a \cmdref{bbox} command called on a set of
+items defined by a logical expression. Note that tags and ids can be mixed.
 
 \begin{verbatim}
 ($xo, $yo, $xc, $yc) = $zinc->bbox("(red && black)||(pink && !$thisitem)");
 \end{verbatim}
 
-Many methods only operate on a single item at a time;  if \ident{tagOrId} is specified
-in a way that names multiple items, then the normal behavior for these methods is to
-use the first of these items in the display list (most visible) that is suitable for
-the method.  Exceptions are noted in the method descriptions below.
+Many methods only operate on a single item at a time; if \ident{tagOrId} is
+specified in a way that names multiple items, then the normal behavior for
+these methods is to use the first of these items in the display list (most
+visible) that is suitable for the method.  Exceptions are noted in the
+method descriptions below.
+
+Tags can be associated with items by giving a tag list to the \ident{-tags}
+attribute or by using the more powerful \cmdref{addtag} command. A tag can
+be removed by the \cmdref{dtag} command, by setting the \ident{-tags}
+attribute to the empty list, all tags are remove from an item at once
+(except the implicit ones). Tags can be read with the \cmdref{gettags} or
+by querying the \ident{-tags} attribute. The items named by a tag are
+returned in a list by the \cmdref{find} command which as exactly the same
+capabilities as \cmdref{addtag}.
+
+\section{Pathtags}
+A special form of tag called a pathtag can be used as a tagOrId argument in all
+commands except \cmdref{bind}. This special tag describes an item or a group of
+items in the absolute item hierarchy. The pathtag consists in a path down the
+group hierarchy followed by the effective tag, in the usual sense.
+
+ The path is an ordered list of tags set up on groups that drives the search
+ from the top group down the group hierarchy. The path starts with either a dot
+ or a star, and the tags in the path are separated by dots or stars. The dot
+ means that the next tag selects a group item that is a direct child of the
+ current group, starting with the top group. The star selects a group item that
+ is a possibly indirect child of the current group, the candidate is found
+ in display list order. The first tag in the path, the one just after the first
+ dot or star, can be a group id, this is useful in order to the search in a
+ specific sub-hierarchy.
+
+ The last tag of a pathtag, the one not followed by a dot or star is the
+ effective tag searched for. It can be omitted, in this case the search
+ proceed with the tag all. The dot or star just before the effective tag,
+ even if the tag is implied, controls how the tag is searched. If a dot is
+ present, the search is limited to the current group level. If a star is
+ present, the search proceed from the current group level down the whole
+ group subtree.
+
+Here are some commonly used pathtags idioms:
+
+\begin{itemize}
+\item{\bf .group1Tag.group2Tag.aTag} Selects all direct children with the tag aTag in
+the group obtained by following the path .group1Tag.group2Tag from the top group.
+The search proceed from the top group to the first direct child group in display
+list order with tag group1Tag. Then it searches for the first direct child group
+with tag group2Tag. Finally in this group, the search ends by finding all direct
+children items (including groups) with tag aTag. If a tag is not found the whole
+search is aborted and no item is selected.
+\item{\bf .group1Tag.group2Tag*aTag} Selects all children with the tag aTag in
+the group obtained by following the path .group1Tag.group2Tag from the top group.
+\item{\bf .group1Tag*group2Tag.aTag} Selects all direct children with the tag aTag in
+the group obtained by following the path .group1Tag*group2Tag from the top group.
+The search proceed from the top group to the first direct child group in display
+list order with tag group1Tag. Then it searches in display list order down the
+hierearchy for the first group with tag group2Tag . Finally in this group, the
+search ends by finding all direct children items (including groups) with tag aTag.
+ If a tag is not found the whole search is aborted and no item is selected.
+\item{\bf .group1Tag*group2Tag*aTag} Selects all items with the tag aTag in the hierarchy
+of the group obtained by following the path .group1Tag*group2Tag from the top
+group. The search proceed from the top group to the first direct child group in
+display list order with tag group1Tag. Then it searches in display list order down
+the hierearchy for the first group with tag group2Tag . Finally in this group, the
+search ends by finding all direct children items (including groups) with tag aTag.
+ If a tag is not found the whole search is aborted and no item is selected.
+\item{\bf .group1Tag.group2Tag.} Selects all direct children of the group obtained
+ by following the path .group1Tag.group2Tag from the top group. If a tag is not
+ found the whole search is aborted and no item is selected.
+\item{\bf .group1Tag.group2Tag*} Selects all items in the hierarchy of the group obtained
+ by following the path .group1Tag.group2Tag from the top group. If a tag is not
+ found the whole search is aborted and no item is selected.
+\item{\bf .groupId.aTag} Selects all direct children with tag aTag of the group with
+ id groupId.
+ If groupId is not found or is not a group id, the search is aborted and no item
+ is selected. This form together with the next is specially useful with cloned
+ items hierarchies where only the topmost group item is known after cloning. Using
+pathtags it is now possible to make use of designs using components with named
+sub-components. It is possible to clone a component and afterward to change the
+behavior of named sub-components with pathtags of the form
+componentId.subComponentName or perhaps better componentId*subComponentName. Some
+care is in order to avoid sub-component name clash, remember that the search for
+tags proceed in display list order, not in hierarchy order. In other more
+technical words the search walks the item tree depth first not breadth first.
+\item{\bf .groupId*aTag} Selects all items with tag aTag in the hierarchy of the
+ group with id groupId. If groupId is not found or is not a group id, the search
+ is aborted and no item is selected.
+\item{\bf .} Selects all direct children of the top group
+\item{\bf *} Selects all items in the hierarchy (not counting the top group
+ itself).
+\item{\bf .aTag} Selects all direct children of the top group with the tag aTag.
+\item{\bf *aTag} Selects all items in the whole hierarchy (starting a the top group)
+  with the tag aTag. It is the same as using the simple tag aTag.
+\end{itemize}
 
-Tags can be associated with items by giving a tag list to the \ident{-tags} attribute or
-by using the more powerful \cmdref{addtag} command. A tag can be removed by the
-\cmdref{dtag} command, by setting the \ident{-tags} attribute to the empty list, all tags
-are remove from an item at once (except the implicit ones). Tags can be read with the
-\cmdref{gettags} or by querying the \ident{-tags} attribute. The items named by a tag are
-returned in a list by the \cmdref{find} command which as exactly the same capabilities as
-\cmdref{addtag}.
 
 \section{Tags and bindings}
-Tags are also very useful to associate scripts with events. The \cmdref{bind} command
-is used to specify a script to be invoqued when an event sequence is associated with
-a tag.
+Tags are also very useful to associate scripts with events. The \cmdref{bind}
+command is used to specify a script to be invoqued when an event sequence is
+associated with a tag.
 
 The event dispatch mecanism in Zinc collects which tags are related to a given event and
 then use the bindings established by \cmdref{bind} to activate the related scripts. Event
@@ -1331,7 +1418,7 @@ reference) and all list parameters are given as array references.
     Selects all the items at the given priority. The tagOrId optional
     parameter can be specified to restrict the search. It specifies a
     group to start with instead of the top group and it can be used to
-    control if the search should be recursive or not (see path tags for
+    control if the search should be recursive or not (see pathtags for
     more on this subject).
 
   \item{\tt\large
@@ -1413,7 +1500,7 @@ reference) and all list parameters are given as array references.
     Selects all the items of type {\tt type}.  The tagOrId optional
     parameter can be specified to restrict the search. It specifies a
     group to start with instead of the top group and it can be used to
-    control if the search should be recursive or not (see path tags for
+    control if the search should be recursive or not (see pathtags for
     more on this subject).
   \end{itemize}
 \end{blockindent}