ch21_12.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<dt><i> <tt class="literal">-width =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
The width of the line (default is 1 pixel).</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">createOval</tt></b></dt>
<dd>
<a name="INDEX-3005" />Creates an oval. For example, to create
a circle bounded by the box from (50,50) to (150,150):
</p>


<blockquote><pre class="code">$canvas-&gt;createOval(50,50,150,150);</pre></blockquote>

<p>Options are:</p>

<dl>
<dt><i> <tt class="literal">-fill =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
Fills the arc with the specified color.</p>
</dd>


<dt><i> <tt class="literal">-outline =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
Specifies the color for the outline (default is
<tt class="literal">black</tt>).
</p>
</dd>


<dt><i> <tt class="literal">-stipple =&gt;</tt> <em class="replaceable"><tt>bitmap</tt></em></i></dt>
<dd>
Specifies a bitmap to fill the oval with.</p>
</dd>


<dt><i> <tt class="literal">-tags =&gt;</tt> <em class="replaceable"><tt>tagnames</tt></em></i></dt>
<dd>
Associates the oval with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
</p>
</dd>


<dt><i> <tt class="literal">-width =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
The width of the outline (default is 1 pixel).</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">createPolygon</tt></b></dt>
<dd>
<a name="INDEX-3006" />Creates a polygon. At least three sets
of coordinates are required; the first point is automatically
connected to the last point to complete the polygon.
</p>


<blockquote><pre class="code">$canvas -&gt; createPolygon(0,0,130, 20, 90, -35);</pre></blockquote>

<p>Options are:</p>

<dl>
<dt><i> <tt class="literal">-fill =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
The color to use to fill the polygon.</p>
</dd>


<dt><i> <tt class="literal">-outline =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
Specifies the color of the outline (default is
<tt class="literal">black</tt>).
</p>
</dd>


<dt><i> <tt class="literal">-smooth =&gt;</tt> <em class="replaceable"><tt>boolean</tt></em></i></dt>
<dd>
Determines whether the outline is drawn with a Bezier spine. Default
is <tt class="literal">0</tt>.
</p>
</dd>


<dt><i> <tt class="literal">-splinesteps =&gt;</tt> <em class="replaceable"><tt>n</tt></em></i></dt>
<dd>
Determines how smooth the Bezier curve is.</p>
</dd>


<dt><i> <tt class="literal">-stipple =&gt;</tt> <em class="replaceable"><tt>bitmap</tt></em></i></dt>
<dd>
Fills the polygon with the specified bitmap pattern.</p>
</dd>


<dt><i> <tt class="literal">-tags =&gt;</tt> <em class="replaceable"><tt>tagnames</tt></em></i></dt>
<dd>
Associates the polygon with the specified tag(s). Multiple tag names
can be supplied as an anonymous list.
</p>
</dd>


<dt><i> <tt class="literal">-width =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
The width of the outline (default is 1 pixel).</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">createRectangle</tt></b></dt>
<dd>
<a name="INDEX-3007" />Creates a rectangle. For example, to
create a square with one corner at (0,0) and another at (100,100):
</p>

<blockquote><pre class="code">$canvas-&gt;createRectangle(0,0,100,100);</pre></blockquote>


<p>Options are:</p>

<dl>
<dt><i> <tt class="literal">-fill =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
The color to use to fill the rectangle.</p>
</dd>


<dt><i> <tt class="literal">-outline =&gt;</tt> <em class="replaceable"><tt>color</tt></em></i></dt>
<dd>
Specifies the color of the outline (default is
<tt class="literal">black</tt>).
</p>
</dd>


<dt><i> <tt class="literal">-stipple =&gt;</tt> <em class="replaceable"><tt>bitmap</tt></em></i></dt>
<dd>
Fills the rectangle with the specified bitmap pattern.</p>
</dd>


<dt><i> <tt class="literal">-tags =&gt;</tt> <em class="replaceable"><tt>tagnames</tt></em></i></dt>
<dd>
Associates the rectangle with the specified tag(s). Multiple tag
names can be supplied as an anonymous list.
</p>
</dd>


<dt><i> <tt class="literal">-width =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
The width of the outline (default is 1 pixel).</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">createText</tt></b></dt>
<dd>
<a name="INDEX-3008" />Places text in a canvas widget. For
example, to write "Broadway"
centered at the position (130,-40):
</p>


<blockquote><pre class="code">$canvas-&gt;createText(130,-40, -text =&gt; "Broadway");</pre></blockquote>

<p>Options are:</p>

<dl>
<dt><b><tt class="literal">-anchor =&gt;</tt> <em class="replaceable">position</em></b></dt>
<dd>
Anchors the text at the specified position. Values are
<tt class="literal">center</tt> (default), <tt class="literal">n</tt>,
<tt class="literal">e</tt>, <tt class="literal">s</tt>, <tt class="literal">w</tt>,
<tt class="literal">ne</tt>, <tt class="literal">nw</tt>, <tt class="literal">se</tt>,
and <tt class="literal">sw</tt>.
</p>
</dd>


<dt><b><tt class="literal">-fill =&gt;</tt> <em class="replaceable">color</em></b></dt>
<dd>
The color to use for the text.</p>
</dd>


<dt><b><tt class="literal">-font =&gt;</tt> <em class="replaceable">fontname</em></b></dt>
<dd>
The font for the text.</p>
</dd>


<dt><b><tt class="literal">-justify =&gt;</tt> <em class="replaceable">position</em></b></dt>
<dd>
The justification of the text (either <tt class="literal">left</tt>,
<tt class="literal">right</tt>, or <tt class="literal">center</tt>). The default
is <tt class="literal">left</tt>.
</p>
</dd>


<dt><b><tt class="literal">-stipple =&gt;</tt> <em class="replaceable">bitmap</em></b></dt>
<dd>
Fills the text with the specified bitmap pattern.</p>
</dd>


<dt><b><tt class="literal">-tags =&gt;</tt> <em class="replaceable">tagnames</em></b></dt>
<dd>
Associates the text with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
</p>
</dd>


<dt><b><tt class="literal">-text =&gt;</tt> <em class="replaceable">string</em></b></dt>
<dd>
Specifies the text to display.</p>
</dd>


<dt><b><tt class="literal">-width =&gt;</tt> <em class="replaceable">amount</em></b></dt>
<dd>
The maximum length of each line of text. Default is
<tt class="literal">0</tt>, which means that lines are broken only at
explicit newline characters.
</p>
</dd>

</dl>

<p>There is a set of methods for manipulating text items within a Canvas
widget. For each of these methods, the first argument is the tag name
or tag ID, and subsequent arguments use text indexes as described for
the Text widget.
</p>

<dl>
<dt><i> <tt class="literal">dchars</tt></i></dt>
<dd>
Deletes characters from a text item, given the tag name or ID, and
indexes of the first and last characters to delete
</p>
</dd>


<dt><i> <tt class="literal">icursor</tt> </i></dt>
<dd>
Places the insert cursor at the specified index</p>
</dd>


<dt><i> <tt class="literal">index</tt></i></dt>
<dd>
Gets a numerical index from a named one</p>
</dd>


<dt><i> <tt class="literal">insert</tt></i></dt>
<dd>
Adds a string to the text item</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">createWindow</tt></b></dt>
<dd>
<a name="INDEX-3009" />Embeds another widget inside of a
canvas. The widget must have been already created as a child of the
canvas or of the canvas's parent. Options are:
</p>
<dl>

<dt><i> <tt class="literal">-anchor =&gt;</tt> <em class="replaceable"><tt>position</tt></em></i></dt>
<dd>
Anchors the widget at the specified position. Values are
<tt class="literal">center</tt> (default), <tt class="literal">n</tt>,
<tt class="literal">e</tt>, <tt class="literal">s</tt>, <tt class="literal">w</tt>,
<tt class="literal">ne</tt>, <tt class="literal">nw</tt>, <tt class="literal">se</tt>,
and <tt class="literal">sw</tt>.
</p>
</dd>


<dt><i> <tt class="literal">-height =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
Specifies the height of the widget.</p>
</dd>


<dt><i> <tt class="literal">-tags =&gt;</tt> <em class="replaceable"><tt>tagnames</tt></em></i></dt>
<dd>
Associates the widget with the specified tag(s). Multiple tag names
can be supplied as an anonymous list.
</p>
</dd>


<dt><i> <tt class="literal">-width =&gt;</tt> <em class="replaceable"><tt>amount</tt></em></i></dt>
<dd>
The width of the widget.</p>
</dd>


<dt><i> <tt class="literal">-window =&gt;</tt> <tt class="literal">$</tt><em class="replaceable"><tt>widget</tt></em></i></dt>
<dd>
Specifies the widget to embed.</p>
</dd>

</dl>
</dd>

</dl>

</div>
<a name="perlnut2-CHP-21-SECT-12.2" /><div class="sect2">
<h3 class="sect2">21.12.2. Item Tags and IDs</h3>

<p><a name="INDEX-3010" />Each item in a Canvas widget is given a
unique ID when it is created. This ID is returned from the canvas
creation command. In addition, each item can have a tag associated
with it, either when created or with the <tt class="literal">addtag</tt>
method. You can use either the ID or the tag to refer to an item in
the canvas. Unlike IDs, tags do not have to be unique, which makes it
possible to configure several items as a group.
</p>

<p>Two special tags are created automatically. The
<tt class="literal">"all"</tt> tag refers to all items in the canvas. The
<tt class="literal">"current"</tt> tag refers to the item that the cursor
is currently over, if any.
</p>

</div>
<a name="perlnut2-CHP-21-SECT-12.3" /><div class="sect2">
<h3 class="sect2">21.12.3. Canvas Methods</h3>

<p>In addition to <tt class="literal">configure</tt> and
<tt class="literal">cget</tt>, the following methods are supported by the
Canvas widget:
</p>

<dl>
<dt><b><tt class="literal">addtag</tt></b></dt>
<dd>
<a name="INDEX-3011" />Defines a tag for an already created
canvas item. For example, to assign a tag called
<tt class="literal">"everything"</tt> to all items in a canvas:
</p>


<blockquote><pre class="code">$canvas-&gt;addtag("everything", "all");</pre></blockquote>


<p>To assign the tag <tt class="literal">origin</tt> to the item closest to
the coordinates (0,0):
</p>

<blockquote><pre class="code">$canvas-&gt;addtag("origin", "closest", 0, 0);</pre></blockquote>

<p>The full list of identifiers is:</p>

<dl>
<dt><i> <tt class="literal">above</tt></i></dt>
<dd>
Assigns the tag to the item above the specified item in the display
list
</p>
</dd>


<dt><i> <tt class="literal">all</tt></i></dt>
<dd>
Assigns the tag to all items in the canvas</p>
</dd>


<dt><i> <tt class="literal">below</tt></i></dt>
<dd>