spinbox.html

来自「perl教程」· HTML 代码 · 共 1,002 行 · 第 1/3 页

</p>
<hr />
<h1><a name="validation">VALIDATION</a></h1>
<p>Validation works by setting the <strong>validateCommand</strong>
option to a callback which will be evaluated according to the <strong>validate</strong>
option as follows:</p>
<dl>
<dt><strong><a name="item_none"><strong>none</strong></a></strong>

<dd>
<p>Default.  This means no validation will occur.</p>
</dd>
</li>
<dt><strong><a name="item_focus"><strong>focus</strong></a></strong>

<dd>
<p><strong>validateCommand</strong> will be called when the Spinbox receives or
loses focus.</p>
</dd>
</li>
<dt><strong><a name="item_focusin"><strong>focusin</strong></a></strong>

<dd>
<p><strong>validateCommand</strong> will be called when the Spinbox receives focus.</p>
</dd>
</li>
<dt><strong><a name="item_focusout"><strong>focusout</strong></a></strong>

<dd>
<p><strong>validateCommand</strong> will be called when the Spinbox loses focus.</p>
</dd>
</li>
<dt><strong><a name="item_key"><strong>key</strong></a></strong>

<dd>
<p><strong>validateCommand</strong> will be called when the Spinbox is edited.</p>
</dd>
</li>
<dt><strong><a name="item_all"><strong>all</strong></a></strong>

<dd>
<p><strong>validateCommand</strong> will be called for all above conditions.</p>
</dd>
<dd>
<p>The <strong>validateCommand</strong> and <strong>invalidCommand</strong> callbacks are invoked
with at least 5 positional arguments, which are <em>appended</em> to any already
existing callback arguments:</p>
</dd>
<ul>
<li><strong><a name="item_1">1</a></strong>

<p>The proposed value of the entry.  If you are configuring the
entry widget to have a new textVariable, this will be the value of that
textVariable.</p>
</li>
<li><strong><a name="item_2">2</a></strong>

<p>The characters to be added (or deleted). This will be <a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a>
if validation is due to focus, explcit call to validate or if change
is due to <code>-textvariable</code> changing.</p>
</li>
<li><strong><a name="item_3">3</a></strong>

<p>The current value of entry i.e. before the proposed change.</p>
</li>
<li><strong><a name="item_4">4</a></strong>

<p>The index of character string to be added/deleted, if any. Otherwise -1.</p>
</li>
<li><strong><a name="item_5">5</a></strong>

<p>Type of action. 1 == INSERT, 0 == DELETE,
-1 if it's a forced validation or textVariable validation.</p>
</li>
</ul>
<p>In general, the <strong>textVariable</strong> and <strong>validateCommand</strong> can be
dangerous to mix.  Any problems have been overcome so that using the
<strong>validateCommand</strong> will not interfere with the traditional behavior of
the Spinbox widget.  Using the <strong>textVariable</strong> for read-only purposes will
never cause problems.  The danger comes when you try set the
<strong>textVariable</strong> to something that the <strong>validateCommand</strong> would not
accept, which causes <strong>validate</strong> to become <em>none</em> (the
<strong>invalidCommand</strong> will not be triggered).  The same happens
when an error occurs evaluating the <strong>validateCommand</strong>.</p>
<p>Primarily, an error will occur when the <strong>validateCommand</strong> or
<strong>invalidCommand</strong> encounters an error in its script while evaluating or
<strong>validateCommand</strong> does not return a valid boolean value.  The
<strong>validate</strong> option will also set itself to <strong>none</strong> when you edit the
Spinbox widget from within either the <strong>validateCommand</strong> or the
<strong>invalidCommand</strong>.  Such editions will override the one that was being
validated.  If you wish to edit the value of the widget
during validation and still have the <strong>validate</strong> option set, you should
include the command</p>
<pre>
 <span class="keyword">my</span> <span class="variable">$val</span> <span class="operator">=</span> <span class="variable">$spinbox</span><span class="operator">-&gt;</span><span class="variable">cget</span><span class="operator">(-</span><span class="variable">validate</span><span class="operator">);</span>
 <span class="variable">$spinbox</span><span class="operator">-&gt;</span><span class="variable">configure</span><span class="operator">(</span><span class="string">-validate</span> <span class="operator">=&gt;</span> <span class="variable">$val</span><span class="operator">);</span>
</pre>
<p>in the <strong>validateCommand</strong> or <strong>invalidCommand</strong> (whichever one you
were editing the Spinbox widget from).  It is also recommended to not set an
associated <strong>textVariable</strong> during validation, as that can cause the
Spinbox widget to become out of sync with the <strong>textVariable</strong>.</p>
</dl>
<p>
</p>
<hr />
<h1><a name="widget_methods">WIDGET METHODS</a></h1>
<p>The <strong>Spinbox</strong> command creates a widget object whose
name is $widget.  This command may be used to invoke various
operations on the widget.  It has the following general form:</p>
<pre>
 <span class="variable">$widget</span><span class="operator">-&gt;</span><span class="variable">method</span><span class="operator">(</span><span class="regex">?arg arg ...?</span><span class="operator">);</span>
</pre>
<p>Many of the methods for Spinboxes take one or more indices as
arguments.  An index specifies a particular character in the Spinbox's
string, in any of the following ways:</p>
<dl>
<dt><strong><a name="item_number"><em>number</em></a></strong>

<dd>
<p>Specifies the character as a numerical index, where 0 corresponds
to the first character in the string.</p>
</dd>
</li>
<dt><strong><a name="item_anchor"><strong>anchor</strong></a></strong>

<dd>
<p>Indicates the anchor point for the selection, which is set with the
<strong>select from</strong> and <strong>select adjust</strong> methods.</p>
</dd>
</li>
<dt><strong><a name="item_end"><strong>end</strong></a></strong>

<dd>
<p>Indicates the character just after the last one in the Spinbox's string.
This is equivalent to specifying a numerical index equal to the length
of the Spinbox's string.</p>
</dd>
</li>
<dt><strong><a name="item_insert"><strong>insert</strong></a></strong>

<dd>
<p>Indicates the character adjacent to and immediately following the
insertion cursor.</p>
</dd>
</li>
<dt><strong><a name="item_sel_2efirst"><strong>sel.first</strong></a></strong>

<dd>
<p>Indicates the first character in the selection.  It is an error to
use this form if the selection isn't in the Spinbox window.</p>
</dd>
</li>
<dt><strong><a name="item_sel_2elast"><strong>sel.last</strong></a></strong>

<dd>
<p>Indicates the character just after the last one in the selection.
It is an error to use this form if the selection isn't in the
Spinbox window.</p>
</dd>
</li>
<dt><strong><a name="item__number"><strong>@</strong><em>number</em></a></strong>

<dd>
<p>In this form, <em>number</em> is treated as an x-coordinate in the
Spinbox's window;  the character spanning that x-coordinate is used.
For example, ``<strong>@0</strong>'' indicates the left-most character in the
window.</p>
</dd>
</li>
</dl>
<p>Abbreviations may be used for any of the forms above, e.g. ``<strong>e</strong>''
or ``<strong>sel.f</strong>''.  In general, out-of-range indices are automatically
rounded to the nearest legal value.</p>
<p>The following commands are possible for Spinbox widgets:</p>
<dl>
<dt><strong><a name="item_bbox"><em>$widget</em>-&gt;<strong>bbox</strong>(<em>index</em>);</a></strong>

<dd>
<p>Returns a list of four numbers describing the bounding box of the
character given by <em>index</em>.
The first two elements of the list give the x and y coordinates of
the upper-left corner of the screen area covered by the character
(in pixels relative to the widget) and the last two elements give
the width and height of the character, in pixels.
The bounding box may refer to a region outside the visible area
of the window.</p>
</dd>
</li>
<dt><strong><a name="item_cget"><em>$widget</em>-&gt;<strong>cget</strong>(<em>option</em>);</a></strong>

<dd>
<p>Returns the current value of the configuration option given
by <em>option</em>.
<em>Option</em> may have any of the values accepted by the <strong>Spinbox</strong>
command.</p>
</dd>
</li>
<dt><strong><a name="item_configure"><em>$widget</em>-&gt;<strong>configure</strong>(?<em>option</em>?, ?<em>value, option, value, ...</em>?);</a></strong>

<dd>
<p>Query or modify the configuration options of the widget.
If no <em>option</em> is specified, returns a list describing all of
the available options for $widget (see <a href="../../Tk/configure.html">the Tk::configure manpage</a> for
information on the format of this list).  If <em>option</em> is specified
with no <em>value</em>, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no <em>option</em> is specified).  If
one or more <em>option-value</em> pairs are specified, then the command
modifies the given widget <code>option(s)</code> to have the given value(s);  in
this case the command returns an empty string.
<em>Option</em> may have any of the values accepted by the <strong>Spinbox</strong>
command.</p>
</dd>
</li>
<dt><strong><a name="item_delete"><em>$widget</em>-&gt;<strong>delete</strong>(<em>first, </em>?<em>last</em>?);</a></strong>

<dd>
<p>Delete one or more elements of the Spinbox.
<em>First</em> is the index of the first character to delete, and
<em>last</em> is the index of the character just after the last
one to delete.
If <em>last</em> isn't specified it defaults to <em>first</em>+1,
i.e. a single character is deleted.
This command returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_get"><em>$widget</em>-&gt;<strong>get</strong>;</a></strong>

<dd>
<p>Returns the Spinbox's string.</p>
</dd>
</li>
<dt><strong><a name="item_icursor"><em>$widget</em>-&gt;<strong>icursor</strong>(<em>index</em>);</a></strong>

<dd>
<p>Arrange for the insertion cursor to be displayed just before the character
given by <em>index</em>.  Returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_identify"><em>$widget</em>-&gt;<strong>identify</strong>(<em>x, y</em>);</a></strong>

<dd>
<p>Returns the name of the window element corresponding to coordinates
<em>x</em> and <em>y</em> in the Spinbox.  Return value is one of:
<strong>none</strong>, <strong>buttondown</strong>, <strong>buttonup</strong>, <strong>entry</strong>.</p>
</dd>
</li>
<dt><strong><a name="item_index"><em>$widget</em>-&gt;<strong>index</strong>(<em>index</em>);</a></strong>

<dd>
<p>Returns the numerical index corresponding to <em>index</em>.</p>
</dd>
</li>
<dt><strong><em>$widget</em>-&gt;<strong>insert</strong>(<em>index, string</em>);</strong>

<dd>
<p>Insert the characters of <em>string</em> just before the character
indicated by <em>index</em>.  Returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_invoke"><em>$widget</em>-&gt;<strong>invoke</strong>(<em>element</em>);</a></strong>

<dd>
<p>Causes the specified element, either <strong>buttondown</strong> or <strong>buttonup</strong>,
to be invoked, triggering the action associated with it.</p>
</dd>
</li>
<dt><strong><a name="item_scan"><em>$widget</em>-&gt;<strong>scan</strong>(<em>option, args</em>);</a></strong>

<dd>
<p>This command is used to implement scanning on Spinboxes.  It has
two forms, depending on <em>option</em>:</p>
</dd>
<dl>
<dt><strong><a name="item_scanmark"><em>$widget</em>-&gt;<strong>scanMark</strong>(<em>x</em>);</a></strong>

<dd>
<p>Records <em>x</em> and the current view in the Spinbox window;  used in
conjunction with later <strong>scan dragto</strong> commands.  Typically this
command is associated with a mouse button press in the widget.  It
returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_scandragto"><em>$widget</em>-&gt;<strong>scanDragto</strong>(<em>x</em>);</a></strong>

<dd>
<p>This command computes the difference between its <em>x</em> argument
and the <em>x</em> argument to the last <strong>scan mark</strong> command for
the widget.  It then adjusts the view left or right by 10 times the
difference in x-coordinates.  This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the Spinbox at high speed through the window.  The return
value is an empty string.</p>
</dd>
</li>
</dl>
<dt><strong><a name="item_selection"><em>$widget</em>-&gt;<strong>selection</strong>(<em>option, arg</em>);</a></strong>

<dd>
<p>This command is used to adjust the selection within a Spinbox.  It
has several forms, depending on <em>option</em>:</p>
</dd>
<dl>
<dt><strong><a name="item_selectionadjust"><em>$widget</em>-&gt;<strong>selectionAdjust</strong>(<em>index</em>);</a></strong>

<dd>
<p>Locate the end of the selection nearest to the character given by
<em>index</em>, and adjust that end of the selection to be at <em>index</em>
(i.e including but not going beyond <em>index</em>).  The other
end of the selection is made the anchor point for future
<strong>select to</strong> commands.  If the selection
isn't currently in the Spinbox, then a new selection is created to
include the characters between <em>index</em> and the most recent
selection anchor point, inclusive.
Returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_selectionclear"><em>$widget</em>-&gt;<strong>selectionClear</strong>;</a></strong>

<dd>
<p>Clear the selection if it is currently in this widget.  If the
selection isn't in this widget then the command has no effect.
Returns an empty string.</p>
</dd>
</li>
<dt><strong><a name="item_selectionelement"><em>$widget</em>-&gt;<strong>selectionElement</strong>(?<em>element</em>?);</a></strong>

<dd>
<p>Sets or gets the currently selected element.  If a spinbutton element
is specified, it will be displayed depressed.</p>
</dd>
</li>
<dt><strong><a name="item_selectionfrom"><em>$widget</em>-&gt;<strong>selectionFrom</strong>(<em>index</em>);</a></strong>