diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/refman.tex | 140 |
1 files changed, 95 insertions, 45 deletions
diff --git a/doc/refman.tex b/doc/refman.tex index 9c5b8c3..210961b 100644 --- a/doc/refman.tex +++ b/doc/refman.tex @@ -810,7 +810,7 @@ are: \section{The root group and the item tree} An item, be it simple like a rectangle or more complex like a group, is always -created relative to a group which is known as is parent, the group's items are its +created relative to a group which is known as its parent, the group's items are its children. The items form a tree whose nodes are the group items. The top-most node is known as the root group, of id 1, which is automatically created with TkZinc. By convention, the root group is its own parent. It is not possible to change the parent @@ -1035,6 +1035,28 @@ it so it can act as the background. Of course, other creative uses can be found warned that the clipper outline will never be easthetically drawn due to round off or quantization errors, it is better to turn off borders or outlines in this case. +It is also possible to clip the root group. Depending on the value of TkZinc options +\optref{reshape} and \optref{fullreshape}, the clipping form can be used either to +clip all items in the TkZinc widget, or reshape the TkZinc widget, or to propagate +the TkZinc widget shape to the parent windows. In the latter case, this allows to build +non-rectangulaire applications. Example: + +\code{ + use Tk::Zinc;\\ + + my \$mw = MainWindow->new();\\ + my \$zinc = \$mw->Zinc(-reshape => 1, -fullreshape => 1)->pack;\\ + + \# creating a triangulaire curve\\ + my \$triangle= \$zinc->add('curve',1, [ [0,0], [100,0], [50,100] ], -closed => 1);\\ + \# using the triangulaire curve to reshape both TkZinc and Mainwindow widgets\\ + \$zinc->itemconfigure(1, -clip => \$triangle);\\ + + \$zinc->add('arc',1, [ [0,0], [100,100] ], -filled => 1, -fillcolor => 'darkblue'); + ...\\ + \&Tk::MainLoop; +} + %% %% @@ -1470,7 +1492,7 @@ reference) and all list parameters are given as array references. \$zinc->{\bf addtag}(tag, 'all', ?inGroup?, ?recursive?);} This form is no more allowed since version 3.2.6 of TkZinc. - Please use a form ``'withtag', 'all''' as documented below. + Please use a form '"withtag", "all"' as documented below. \item{\tt\large pathname {\bf addtag} tag atpriority priority ?tagOrId?\\ @@ -1943,10 +1965,15 @@ false. various {\tt args}. The items are sorted in drawing order, topmost first. For example:\\ \code{ \# to get the item under the mouse cursor:\\ \$item = \$zinc->find('withtag', 'current');\\ + \# to get the closest item of a point:\\ \$closest = \$zinc->find ('closest', \$x, \$y);\\ + \# to get direct children of an atomic group with a pathTag:\\ - @children = \$zinc->find('withtag', ''.\$atomicGroup.''); + @children = \$zinc->find('withtag', ".atomicGroup.");\\ + + \# to get all groups recursevely contained in a group\\ + @groups = \$zinc->find('withtype', 'group', ".aGroup*"); } As detailled in \cmdref{addtag} command the following searchCommands are possible: @@ -2650,8 +2677,9 @@ with the local transform. The default value is {\tt true}.} \attribute{track}{connecteditem}{item}{The item at the other end of the connection link. The default value is {\tt ""} which means that no connection link will be drawn.} -\attribute{track}{connectioncolor}{gradient}{The color of the connection link. The -default value is the current value of the widget option \optref{forecolor}.} +\attribute{track}{connectioncolor}{gradient}{The uniform (possibly transparent) +color of the connection link. The first color of a real gradient color +will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{connectionsensitive}{boolean}{Specifies if the connection link is sensitive. The actual sensitivity is the logical \ident{and} of this attribute and of the @@ -2673,7 +2701,8 @@ otherwise it will be outlined. The default value is {\tt false}.} current location to prevent the anti overlapping system from moving it. The default value is {\tt false}.} -\attribute{track}{historycolor}{gradient}{The color of the track history. The default +\attribute{track}{historycolor}{gradient}{The uniform (possibly transparent) color of the +track history. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{labelanchor}{anchor}{The anchor used in positionning the label. The @@ -2716,7 +2745,8 @@ history color. The default value is {\tt false}.} side. The default value is {\tt ""} which means that both leader anchors are at the label center.} -\attribute{track}{leadercolor}{gradient}{The color of the label leader. The default +\attribute{track}{leadercolor}{gradient}{The uniform (possibly transparent) color of the label +leader. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{leaderfirstend}{lineend}{Describes the arrow shape at the current @@ -2738,7 +2768,8 @@ value is {\tt simple}.} \attribute{track}{leaderwidth}{dimension}{The width of the label leader. The default value is {\tt 1}.} -\attribute{track}{markercolor}{gradient}{The color of the circular marker. The +\attribute{track}{markercolor}{gradient}{The uniform (possibly transparent) color of the +circular marker. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{markerfillpattern}{bitmap}{The pattern to use when filling the circular @@ -2769,8 +2800,9 @@ default value is {\tt true}.} unit / minute. The default value is {\tt "0 0"} which results in no speed vector displayed.} -\attribute{track}{speedvectorcolor}{gradient}{The color of the track's speed -vector. The default value is the current value of the widget option \optref{forecolor}.} +\attribute{track}{speedvectorcolor}{gradient}{The uniform (possibly transparent) color of +the track's speed vector. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{speedvectormark}{boolean}{If set a small point is drawn at the end of the speed vector. The point is drawn with the speed vector color. The default is {\tt @@ -2789,8 +2821,9 @@ position. The default is {\tt false}. Not yet available without openGL} \attribute{track}{symbol}{bitmap}{The symbol displayed at the current position. The default value is {\tt AtcSymbol15}.} -\attribute{track}{symbolcolor}{gradient}{The color of the symbol displayed at the -current position. The default value is the current value of the widget option +\attribute{track}{symbolcolor}{gradient}{The uniforme (possibly transparent) color of the symbol +displayed at the current position. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{track}{symbolsensitive}{boolean}{Specifies if the current position's symbol is @@ -2851,7 +2884,8 @@ composed with the local transform. The default value is {\tt true}. } \attribute{waypoint}{connecteditem}{item}{The item at the other end of the connection link. The default value is {\tt ""} which means that no connection link will be drawn.} -\attribute{waypoint}{connectioncolor}{gradient}{The color of the connection link. The +\attribute{waypoint}{connectioncolor}{gradient}{The uniform (possibly transparent) color of +the connection link. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{connectionsensitive}{boolean}{Specifies if the connection link is @@ -2898,7 +2932,8 @@ value is {\tt ""} which means that no label will be displayed.} label side. The default value is {\tt ""} which means that both leader anchors are at the label center.} -\attribute{waypoint}{leadercolor}{gradient}{The color of the label leader. The +\attribute{waypoint}{leadercolor}{gradient}{The uniform (possibly transparent) color of the +label leader. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{leaderfirstend}{lineend}{Describes the arrow shape at the current @@ -2920,7 +2955,8 @@ default value is {\tt simple}.} \attribute{waypoint}{leaderwidth}{dimension}{The width of the label leader. The default value is {\tt 1}.} -\attribute{waypoint}{markercolor}{gradient}{The color of the circular marker. The +\attribute{waypoint}{markercolor}{gradient}{The uniform (possibly transparent) color of the +circular marker. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{markerfillpattern}{bitmap}{The pattern to use when filling the @@ -2946,8 +2982,9 @@ The default value is {\tt true}.} \attribute{waypoint}{symbol}{bitmap}{The symbol displayed at the current position. The default value is {\tt AtcSymbol15}.} -\attribute{waypoint}{symbolcolor}{gradient}{The color of the symbol displayed at the -current position. The default value is the current value of the widget option +\attribute{waypoint}{symbolcolor}{gradient}{The uniform (possibly transparent) color of the +symbol displayed at the current position. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{waypoint}{symbolsensitive}{boolean}{Specifies if the current position's symbol @@ -3036,8 +3073,9 @@ the item. The default value is {\tt left}.} \attribute{text}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} -\attribute{text}{color}{gradient}{Specifies the color for drawing the text -characters, the overstrike and underline lines. The default value is the current value of +\attribute{text}{color}{gradient}{Specifies the uniform (possibly transparent) color for +drawing the text characters, the overstrike and underline lines. The first color of a +real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{text}{composealpha}{boolean}{Specifies if the alpha value inherited from @@ -3109,8 +3147,9 @@ Applicable attributes for \ident{icon} are: \attribute{icon}{anchor}{anchor}{The anchor used in positionning the item. The default value is {\tt nw}.} -\attribute{icon}{color}{gradient}{Specifies the fill color used for drawing the -bitmap. The default value is the current value of the widget option \optref{forecolor}.} +\attribute{icon}{color}{gradient}{Specifies the uniform (possibly transparent) fill color +used for drawing the bitmap. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{icon}{composealpha}{boolean}{Specifies if the alpha value inherited from the parent group should be composed with the alpha of this item. The default value is {\tt true}.} @@ -3168,8 +3207,9 @@ Reticle cannot handle events. Applicable attributes for \ident{reticle} are: -\attribute{reticle}{brightlinecolor}{gradient}{This is the color of the highlighted -circles. The default value is the current value of the widget option \optref{forecolor}.} +\attribute{reticle}{brightlinecolor}{gradient}{This is the uniform (possibly transparent) +color of highlighted circles. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{reticle}{brightlinestyle}{linestyle}{This is the line style of the highlighted circles. The default value is {\tt simple}.} @@ -3186,8 +3226,9 @@ composed with the local transform. The default value is {\tt true}.} \attribute{reticle}{firstradius}{dimension}{This is the radius of the innermost circle of the reticle. The default value is {\tt 80}.} -\attribute{reticle}{linecolor}{gradient}{This is the color of the regular (not -highlighted) circles. The default value is the current value of the widget option +\attribute{reticle}{linecolor}{gradient}{This is the uniform (possibly transparent) color of +regular (not highlighted) circles. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{reticle}{linestyle}{linestyle}{This is the line style of the regular (not @@ -3235,8 +3276,9 @@ command or more generally created and edited with a set of commands described in Applicable attributes for \ident{map} are: -\attribute{map}{color}{gradient}{Specifies the color usedd to draw or fill the -map. The texts and symbols that are part of the map are also drawn in this color. The +\attribute{map}{color}{gradient}{Specifies the uniform (possibly transparent) color used +to draw or fill the map. The texts and symbols that are part of the map are also drawn in +this color. The first color of a real gradient color will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{map}{composealpha}{boolean}{Specifies if the alpha value inherited from @@ -3313,8 +3355,9 @@ value is {\tt false}.} \attribute{rectangle}{fillpattern}{bitmap}{Specifies the pattern to use when filling the item. The default value is {\tt ""}.} -\attribute{rectangle}{linecolor}{gradient}{Specifies the color that will be used to -draw the item outline. The default value is the current value of the widget option +\attribute{rectangle}{linecolor}{gradient}{Specifies the uniform (possibly transparent) +color used to draw the item outline. The first color of a real gradient color +will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{rectangle}{linepattern}{bitmap}{Specifies the pattern to use when drawing the @@ -3383,7 +3426,7 @@ with the local transform. The default value is {\tt true}.} start angle. The angle is expressed in degrees in the trigonometric system. The default value is {\tt 360}.} -\attribute{arc}{fillcolor}{gradient}{ Specifies the color that will be used to fill +\attribute{arc}{fillcolor}{gradient}{ Specifies the color used to fill the arc if requested by the \attributeref{arc}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{backcolor}.} @@ -3401,8 +3444,9 @@ default value is {\tt ""}.} arc. This attribute is applicable only if the item is not closed and not filled. The default value is {\tt ""}.} -\attribute{arc}{linecolor}{gradient}{Specifies the color that will be used to draw -the item outline. The default value is the current value of the widget option +\attribute{arc}{linecolor}{gradient}{Specifies the uniform (possibly transparent) color +used to draw the item outline. The first color of a real gradient color +will be used. The default value is the current value of the widget option \optref{forecolor}.} \attribute{arc}{linepattern}{bitmap}{Specifies the pattern to use when drawing the @@ -3478,7 +3522,7 @@ composed with the local transform. The default value is {\tt true}.} \attribute{curve}{composescale}{boolean}{Specifies if the current scale should be composed with the local transform. The default value is {\tt true}.} -\attribute{curve}{fillcolor}{gradient}{Specifies the color that will be used to fill +\attribute{curve}{fillcolor}{gradient}{Specifies the color used to fill the curve if requested by the \attributeref{curve}{filled} attribute. The default value is a one color gradient based on the current value of the widget option \optref{backcolor}.} @@ -3506,9 +3550,9 @@ default value is {\tt round}.} This attribute is applicable only if the item is not closed, not filled and the relief of the outline is flat. The default value is {\tt ""}.} -\attribute{curve}{linecolor}{gradient}{Specifies the color that will be used to draw -the item outline. The default value is the current value of the widget option -\optref{forecolor}.} +\attribute{curve}{linecolor}{gradient}{Specifies the uniform (possibly transparent) color +used to draw the item outline. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{curve}{linepattern}{bitmap}{Specifies the pattern to use when drawing the outline. The default value is {\tt ""}.} @@ -3523,8 +3567,9 @@ scalable). The default value is {\tt 1}.} each vertex of the curve. This attribute is not applicable if the outline relief is not flat. The default value is {\tt ""} which means do not draw markers.} -\attribute{curve}{markercolor}{gradient}{Specifies the color of the markers. The -default value is the current value of the widget option \optref{forecolor}.} +\attribute{curve}{markercolor}{gradient}{Specifies the uniform (possibly transparent) color of the +markers. The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{curve}{priority}{priority}{The absolute position in the stacking order among siblings of the same parent group. The default value is {\tt 2}.} @@ -3749,7 +3794,7 @@ As an example: -color => 'white', -backcolor => 'black', -filled => 1); - # this should display ``Hello World'' in white on black in field 0 + # this should display "Hello World" in white on black in field 0 \end{verbatim} It is possible to bind callbacks to fields, with the command \cmdref{bind} and @@ -3799,11 +3844,13 @@ one pixel wide outline that is drawn around the field outside the relief. Some b edges can be omitted, this attribute describes the edges that should be displayed as part of the border. The default value is {\tt ""}.} -\attribute{field}{bordercolor}{gradient}{ The border color. The default value is the current -value of the widget option \optref{forecolor}.} +\attribute{field}{bordercolor}{gradient}{ The border uniform (possibly transparent) color. +The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} -\attribute{field}{color}{gradient}{ The text color. The default value is the current value of -the widget option \optref{forecolor}.} +\attribute{field}{color}{gradient}{ The text uniform (possibly transparent) color. +The first color of a real gradient color will be used. +The default value is the current value of the widget option \optref{forecolor}.} \attribute{field}{filled}{boolean}{ Specifies if the field background should be filled. The default value is {\tt false}.} @@ -3975,8 +4022,11 @@ the example fillrule provided with TkZinc in \conceptref{zinc-demos}{zinc-demos} \attrtype{gradient} \begin{blockindent} This is a string describing a color gradient to be used for example to fill a surface. + Gradient are also used to describe color of lines, even if in this case the lines are + limited to one color with and additionnal alpha percentage. + The string may consist in a single color name that will be used to paint a solid surface - or can be a list of gradient steps separated by \verb+|+ characters. + or a simple color with an alpha valuecan be a list of gradient steps separated by \verb+|+ characters. The general pattern is: @@ -4428,7 +4478,7 @@ or simply by using the -M option of Perl: \section{Tracing TkZinc methods call in perl/Tk} Because you some time get some errors inside \ident{TkZinc} with a cryptic message -like {\tt ``.... errors in Tk.pm line 228''} it may be usefull to know where exactly +like {\tt ".... errors in Tk.pm line 228"} it may be usefull to know where exactly in your code is this error. There is a simple and convenient mean to do this, just by using a small module called \ident{ZincTrace.pm}, released with \ident{TkZinc}. It will trace every call of a TkZinc method. It will trace on the standard output |