Tk Library Source Code

Identifier: tklib
Title:  Tk Standard Library
Description: This package is intended to be a collection of
    Tcl packages that provide utility functions useful to a
    large collection of Tk programmers.
Rights: BSD
Version: 0.6
Version: 0.7
URL: http://core.tcl.tk/tklib/
Architecture: tcl
Contributor: Aaron Faupell <afaupell at users dot sourceforge dot net>
Contributor: Andreas Kupries <andreas_kupries at users dot sourceforge dot net>
Contributor: Andreas Kupries <andreask at activestate dot com>
Contributor: Andreas Kupries (AS Senior Dev) <andreask at activestate dot com>
Contributor: Arjen Markus <arjenmarkus at users dot sourceforge dot net>
Contributor: Csaba Nemethi <csaba dot nemethi at t-online dot de>
Contributor: David N. Welton <davidw at dedasys dot com>
Contributor: George Peter Staplin <georgeps at users dot sourceforge dot net>
Contributor: Jean-Luc Fontaine <jfontain at free dot fr>
Contributor: Jeff Hobbs <jeffh at ActiveState dot com>
Contributor: Keith Nash <kjnash at users dot sourceforge dot net>

'\"
'\" Generated from file 'datefield\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>
'\" Copyright (c) Thomas Wunderlich <tcl\&.tk@blindenfreizeiten\&.de>
'\"
.TH "datefield" n 0\&.2 tklib "Tk datefield widget"
.TH "datefield" n 0\&.3 tklib "Tk datefield widget"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,

..
.BS
.SH NAME
datefield \- Tk datefield widget
.SH SYNOPSIS
package require \fBTk \fR
.sp
package require \fBdatefield  ?0\&.2?\fR
package require \fBdatefield  ?0\&.3?\fR
.sp
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
.sp
\fI-format\fR
.sp
.BE
.SH DESCRIPTION
The \fBdatefield\fR package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry\&. Only
valid dates of the form MM/DD/YYYY can be entered\&.
is an enhanced text entry widget for the purpose of date entry\&. There
are three valid formats for the dates which can be entered:
.IP [1]
English form MM/DD/YYYY using \fI-format "%m/%d/%Y"\fR (default)
.IP [2]
German form DD\&.MM\&.YYYY using \fI-format "%d\&.%m\&.%Y"\fR
.IP [3]
ISO form YYYY-MM-DD using \fI-format "%Y-%m-%d"\fR
.PP
.PP
The datefield widget is, in fact, just an entry widget with
specialized bindings\&. This means all the command and options for an
entry widget apply equally here\&.
.SH COMMANDS
.TP
\fB::datefield::datefield\fR \fIwidgetpath\fR ?\fIoptions\fR?
Creates and configures a date field widget\&.
.PP
.SH OPTIONS
.TP
\fI-format\fR
One of "%m/%d/%Y" (English, default if option left), "%d\&.%m\&.%Y" (German),
or "%Y-%m-%d" (ISO)\&.
.PP
.PP
See the \fBentry\fR manual entry for details on all available options\&.
See the \fBentry\fR manual entry for details on all remaining/available
options\&.
.SH EXAMPLE
.CS


 package require datefield

 wm title \&. "Datefield example"
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek

 ::datefield::datefield \&.df -textvariable myDate
 ::datefield::datefield \&.df -textvariable myDate -format "%m/%d/%Y"
 label \&.l1 -text "Enter a date:"   -anchor e
 label \&.l2 -text "That date is a:" -anchor e
 label \&.l3 -textvariable myDate2 -relief sunken -width 12

 grid \&.l1 \&.df -sticky ew
 grid \&.l2 \&.l3 -sticky ew
 focus \&.df

.SH KEYWORDS
clock, date, dateentry, entry, widget
.SH CATEGORY
Widget
.SH COPYRIGHT
.nf
Copyright (c) Keith Vetter <keith@ebook\&.gemstar\&.com>
Copyright (c) Thomas Wunderlich <tcl\&.tk@blindenfreizeiten\&.de>

.fi

package require widgetPlus
::widgetPlus::EnableBWidget
namespace import widgetPlus::*

entryPlus \&.cb\&.e -undo 1 -maxundo 0

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIwidgetPlus\fR of the
\fITklib Trackers\fR [http://core\&.tcl\&.tk/tklib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.SH "SEE ALSO"
BWidget, ComboBox, Entry, entry, persistentSelection, spinbox, text, ttk::combobox, ttk::entry, ttk::spinbox

	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'datefield.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; Keith Vetter &amp;lt;[email protected]&amp;gt;
<!-- Copyright &amp;copy; Keith Vetter &amp;lt;[email protected]&amp;gt;   -- Copyright &amp;copy; Thomas Wunderlich &amp;lt;[email protected]&amp;gt;
   -->
<!-- datefield.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tklib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">datefield(n) 0.2 tklib &quot;Tk datefield widget&quot;</h1>
<h1 class="doctools_title">datefield(n) 0.3 tklib &quot;Tk datefield widget&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>datefield - Tk datefield widget</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>

<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tk</b></li>
<li>package require <b class="pkgname">datefield <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">datefield <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#2"><i class="arg">-format</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">datefield</b> package provides the datefield widget which
is an enhanced text entry widget for the purpose of date entry. Only
valid dates of the form MM/DD/YYYY can be entered.</p>
is an enhanced text entry widget for the purpose of date entry. There
are three valid formats for the dates which can be entered:</p>
<ol class="doctools_enumerated">
<li><p>English form MM/DD/YYYY using <i class="arg">-format &quot;%m/%d/%Y&quot;</i> (default)</p></li>
<li><p>German form DD.MM.YYYY using <i class="arg">-format &quot;%d.%m.%Y&quot;</i></p></li>
<li><p>ISO form YYYY-MM-DD using <i class="arg">-format &quot;%Y-%m-%d&quot;</i></p></li>
</ol>
<p>The datefield widget is, in fact, just an entry widget with
specialized bindings. This means all the command and options for an
entry widget apply equally here.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::datefield::datefield</b> <i class="arg">widgetpath</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Creates and configures a date field widget.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">-format</i></a></dt>
<dd><p>One of &quot;%m/%d/%Y&quot; (English, default if option left), &quot;%d.%m.%Y&quot; (German),
or &quot;%Y-%m-%d&quot; (ISO).</p></dd>
</dl>
<p>See the <b class="cmd"><a href="../../../../index.html#key32">entry</a></b> manual entry for details on all available options.</p>
<p>See the <b class="cmd"><a href="../../../../index.html#key32">entry</a></b> manual entry for details on all remaining/available
options.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLE</a></h2>
<pre class="doctools_example">
 package require datefield
 wm title . &quot;Datefield example&quot;
 proc DayOfWeek {args} {
     set now [clock scan $::myDate]
     set ::myDate2 [clock format $now -format %A]
 }
 trace variable myDate w DayOfWeek
 ::datefield::datefield .df -textvariable myDate
 ::datefield::datefield .df -textvariable myDate -format &quot;%m/%d/%Y&quot;
 label .l1 -text &quot;Enter a date:&quot;   -anchor e
 label .l2 -text &quot;That date is a:&quot; -anchor e
 label .l3 -textvariable myDate2 -relief sunken -width 12
 grid .l1 .df -sticky ew
 grid .l2 .l3 -sticky ew
 focus .df
</pre>

<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key31">clock</a>, <a href="../../../../index.html#key33">date</a>, <a href="../../../../index.html#key6">dateentry</a>, <a href="../../../../index.html#key32">entry</a>, <a href="../../../../index.html#key11">widget</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Widget</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; Keith Vetter &lt;[email protected]&gt;</p>
<p>Copyright &copy; Keith Vetter &lt;[email protected]&gt;<br>
Copyright &copy; Thomas Wunderlich &lt;[email protected]&gt;</p>
</div>
</div></body></html>

<!DOCTYPE html>
<html>
<head>
  <title>The Multi-Entry Widget Package Mentry 3.10</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, entry, label">
</head>

<body>
  <div align="center">
    <h1>The Multi-Entry Widget Package Mentry 3.10</h1>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
    </address>
  </div>

  <hr>

  <h2>Contents</h2>

  <p><a href="mentry.html">Mentry Programmer's Guide</a></p>

  <p><a href="mentryWidget.html">The <code>mentry::mentry</code>
  Command</a></p>

  <p><a href="mentryDateTime.html">Multi-Entry Widgets for Date and
  Time</a></p>

  <p><a href="mentryFixedPoint.html">Multi-Entry Widgets for Real Numbers in
  Fixed-Point Format</a></p>

  <p><a href="mentryIPAddr.html">Multi-Entry Widgets for IP Addresses</a></p>

  <p><a href="mentryIPv6Addr.html">Multi-Entry Widgets for IPv6
  Addresses</a></p>

  <p><a href="mentryThemes.html">Commands Related to Tile Themes</a></p>

  <p><a href="wcbRef.html">Wcb Command Reference</a></p>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Mentry Programmer's Guide</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, entry, label">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Mentry Programmer's Guide</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <h4><a href="#overview">Overview</a></h4>

  <ul>
    <li><a href="#ov_what">What Is Mentry?</a></li>

    <li><a href="#ov_get">How to Get It?</a></li>

    <li><a href="#ov_install">How to Install It?</a></li>

    <li><a href="#ov_use">How to Use It?</a></li>

    <li><a href="#ov_tile">More on Mentry_tile</a></li>
  </ul>

  <h4><a href="#examples">Examples</a></h4>

  <ul>
    <li><a href="#ex_phoneNumber">A mentry Widget for Phone Numbers</a></li>

    <li><a href="#ex_ethernetAddr">A mentry Widget for Ethernet
    Addresses</a></li>

    <li><a href="#ex_dateTime">Using mentry Widgets for Date and Time</a></li>

    <li><a href="#ex_tile">Tile-Based Demo Scripts</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="overview">Overview</h2>

  <h3 id="ov_what">What Is Mentry?</h3>

  <p>Mentry is a library package for Tcl/Tk versions 8.0 or higher, written in
  pure Tcl/Tk code.&nbsp; It contains:</p>

  <ul>
    <li>the implementation of the <a href="mentryWidget.html">multi-entry
    mega-widget <b>mentry</b></a>, including a general utility module for
    mega-widgets;</li>

    <li>procedures that facilitate the use of multi-entry widgets for
    displaying and editing <a href="mentryDateTime.html">date and time</a> in a
    great variety of formats, <a href="mentryFixedPoint.html">real numbers in
    fixed-point format</a>, as well as <a href="mentryIPAddr.html">IP(v4)
    addresses</a> and <a href="mentryIPv6Addr.html">IPv6 addresses</a>;</li>

    <li>two richly commented demo scripts containing the typical steps needed
    to create and handle a mentry widget for a particular purpose;</li>

    <li>two demo scripts that show how to use the date- and time-related
    procedures;</li>

    <li>tile-based counterparts of the above-mentioned demo scripts;</li>

    <li>this tutorial;</li>

    <li>reference pages in HTML format.</li>
  </ul>

  <p>A multi-entry widget consists of any number of entry widgets separated by
  labels, all embedded in a frame.&nbsp; Appropriately chosen configuration
  options make this conglomerate look like one single entry containing
  preinserted text pieces having invariant positions within the widget.&nbsp;
  The initial width of an entry child also determines the maximal number of
  characters that can be inserted into it; when reaching this limit in an entry
  having the input focus, the latter is set automatically to the next enabled
  entry child.&nbsp; The same action is triggered by typing a character
  contained in the label following the current entry, if the latter is
  non-empty.</p>

  <p>Within a mentry widget, the <code>Left</code>, <code>Right</code>,
  <code>Home</code>, <code>End</code>, and <code>BackSpace</code> keys work
  across entry boundaries, while <code>Control-Left</code> and
  <code>Control-Right</code> play the same role as <code>Tab</code> and
  <code>Shift-Tab</code> in the case of ordinary entries.</p>

  <p>Some of the above features are implemented with the aid of the widget
  callback package Wcb, written in pure Tcl/Tk code as well.&nbsp; <b>The
  Mentry package requires version 3.1 or higher of Wcb</b>, whose download
  location is</p>

  <blockquote>
    <address>
      <a href="http://www.nemethi.de">http://www.nemethi.de</a>
    </address>
  </blockquote>

  <p id="ov_example">It is very easy to create a multi-entry widget.&nbsp; For
  example, the command</p>

  <blockquote>
    <pre>
mentry::mentry .me -body {3 - 3 - 4}
</pre>
  </blockquote>

  <p>will create a mentry widget consisting of two entries of width 3 and one
  of width 4, separated by <code>"-"</code> characters.&nbsp; With the
  command</p>

  <blockquote>
    <pre>
foreach w [.me entries] {
    wcb::cbappend $w before insert wcb::checkStrForNum
}
</pre>
  </blockquote>

  <p>you can make sure that the three entries will only accept numeric input,
  thus providing a comfortable and safe user interface for editing 10-digit
  phone numbers.</p>

  <h3 id="ov_get">How to Get It?</h3>

  <p>Mentry is available for free download from the same URL as Wcb.&nbsp; The
  distribution file is <code>mentry3.10.tar.gz</code> for UNIX and
  <code>mentry3_10.zip</code> for Windows.&nbsp; These files contain the same
  information, except for the additional carriage return character preceding
  the linefeed at the end of each line in the text files for Windows.</p>

  <p>Mentry is also included in tklib, which has the address</p>

  <blockquote>
    <address>
      <a href="http://core.tcl.tk/tklib">http://core.tcl.tk/tklib</a>
    </address>
  </blockquote>

  <h3 id="ov_install">How to Install It?</h3>

  <p>Install the package as a subdirectory of one of the directories given by
  the <code>auto_path</code> variable.&nbsp; For example, you can install it as
  a directory at the same level as the Tcl and Tk script libraries.&nbsp; The
  locations of these library directories are given by the
  <code>tcl_library</code> and <code>tk_library</code> variables,
  respectively.</p>

  <p>To install Mentry <i>on UNIX</i>, <code>cd</code> to the desired directory
  and unpack the distribution file <code>mentry3.10.tar.gz</code>:</p>

  <blockquote>
    <pre>
gunzip -c mentry3.10.tar.gz | tar -xf -
</pre>
  </blockquote>

  <p>On most UNIX systems this can be replaced with</p>

  <blockquote>
    <pre>
tar -zxf mentry3.10.tar.gz
</pre>
  </blockquote>

  <p>Both commands will create a directory named <code>mentry3.10</code>, with
  the subdirectories <code>demos</code>, <code>doc</code>, and
  <code>scripts</code>.</p>

  <p><i>On Windows</i>, use WinZip or some other program capable of unpacking
  the distribution file <code>mentry3_10.zip</code> into the directory
  <code>mentry3.10</code>, with the subdirectories <code>demos</code>,
  <code>doc</code>, and <code>scripts</code>.</p>

  <p>The file <code>mentryThemes.tcl</code> in the <code>scripts</code>
  directory is only needed for applications using the package Mentry_tile (see
  next section).</p>

  <p>Notice that in tklib the Mentry <code>demos</code> directory is replaced
  with the subdirectory <code>mentry</code> of the <code>examples</code>
  directory.&nbsp; Please take this into account when reading the <a href=
  "#examples">examples</a> below.</p>

  <h3 id="ov_use">How to Use It?</h3>

  <p>The Mentry distribution provides two packages, called <b>Mentry</b> and
  <b>Mentry_tile</b>.&nbsp; The main difference between the two is that
  Mentry_tile enables the tile-based, theme-specific appearance of mentry
  widgets; this package requires Tcl/Tk 8.4 or higher and tile 0.6 or
  higher.&nbsp; It is not possible to use both packages in one and the same
  application, because both are implemented in the same <code>mentry</code>
  namespace and provide identical commands.</p>

  <p>To be able to access the commands and variables defined in the package
  Mentry, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require mentry ?<i>version</i>?
package require Mentry ?<i>version</i>?
</pre>
  </blockquote>

  <p>You can use either one of the two statements above because the file
  <code>mentry.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide mentry ...
package provide Mentry ...
</pre>
  </blockquote>

  <p>Likewise, to be able to access the commands and variables defined in the
  package Mentry_tile, your scripts must contain one of the lines</p>

  <blockquote>
    <pre>
package require mentry_tile ?<i>version</i>?
package require Mentry_tile ?<i>version</i>?
</pre>
  </blockquote>

  <p>Again, you can use either one of the two statements above because the file
  <code>mentry_tile.tcl</code> contains both lines</p>

  <blockquote>
    <pre>
package provide mentry_tile ...
package provide Mentry_tile ...
</pre>
  </blockquote>

  <p>You are free to remove one of the above lines from <code>mentry.tcl</code>
  and <code>mentry_tile.tcl</code>, respectively, if you want to prevent the
  corresponding packages from making themselves known under two different names
  each.&nbsp; Of course, by doing so you restrict the argument of&nbsp;
  <code>package require</code>&nbsp; to a single name per package.</p>

  <p>Please note that <b>ActiveTcl versions 8.5 and later use a modified
  package mechanism, which only exports the all-lowercase names
  <code>mentry</code> and <code>mentry_tile</code></b>.&nbsp; For this reason,
  the <a href="#examples">examples</a> below use the statement&nbsp;
  <code>package require mentry</code>,&nbsp; and their tile-based counterparts
  invoke the command&nbsp; <code>package require mentry_tile</code>.</p>

  <p>Since the packages Mentry and Mentry_tile are implemented in the
  <code>mentry</code> namespace, you must either invoke the</p>

  <blockquote>
    <pre>
namespace import mentry::<i>pattern</i> ?mentry::<i>pattern ...</i>?
</pre>
  </blockquote>

  <p>command to import the <i>procedures</i> you need, or use qualified names
  like <code>mentry::mentry</code>.&nbsp; In the examples below we have chosen
  the latter approach.</p>

  <p>To access Mentry <i>variables</i>, you <i>must</i> use qualified
  names.&nbsp; There are only three Mentry variables (and one more when using
  Mentry_tile) that are designed to be accessed outside the namespace
  <code>mentry</code>:</p>

  <ul>
    <li>The variable <code>mentry::version</code> holds the current version
    number of the Mentry package.</li>

    <li>The variable <code>mentry::library</code> holds the location of the
    Mentry installation directory.</li>

    <li>The read-only variable <code>mentry::usingTile</code> has the value
    <code>0</code> in the package Mentry and the value <code>1</code> in
    Mentry_tile.</li>

    <li>In Mentry_tile the array <code>mentry::themeDefaults</code> holds the
    theme-specific default values of a series of Mentry configuration
    options.</li>
  </ul>

  <h3 id="ov_tile">More on Mentry_tile</h3>

  <p>As mentioned above, a mentry widget consists of entry and label widgets,
  embedded in a frame.&nbsp; While in the Mentry package all of these
  components are Tk widgets, the Mentry_tile package uses both Tk frame, tile
  entry, and Tk label widgets.&nbsp; Due to several incompatibilities between
  Tk and tile, it is currently not possible to replace all Tk widgets making up
  a mentry with their tile counterparts.&nbsp; Actually, the entry components
  of a tile-based mentry are embedded into Tk frame widgets, which in turn,
  together with the labels, are packed into a specially constructed tile entry
  rather than a frame.&nbsp; This somewhat complicated layout is needed because
  in several themes it is not possible to draw flat, borderless tile enty
  widgets.</p>

  <p>From the above it follows that <b>the package Mentry_tile will only work
  as expected if the Tk <code>frame</code> and <code>label</code> commands
  haven't been overridden by using&nbsp; <code>namespace import -force
  ttk::*</code>&nbsp; at global scope</b>.&nbsp; While earlier tile releases
  suggested using this command at global scope for the really adventurous, in
  newer tile versions this is considered a Really Bad Idea, causing many things
  to break.&nbsp; Instead, <b>you should explicitly invoke
  <code>ttk::frame</code>, <code>ttk::label</code>, etc. whenever you want to
  use a tile widget</b>.</p>

  <p>Another restriction to be taken into account (as of tile version 0.8) is
  due to the fact that the&nbsp; <code>(ttk::)style theme use</code>&nbsp;
  command can only be used to set the current theme, but not to retrieve
  it.&nbsp; For this reason, the package Mentry_tile makes use of the variable
  <code>ttk::currentTheme</code> or <code>tile::currentTheme</code> (depending
  on the tile version), which is set by the <code>ttk::setTheme</code> or
  <code>tile::setTheme</code> procedure.&nbsp; From this it follows that <b>the
  tile-based mentry widgets will only have the expected appearance if the
  platform-specific default theme is either left unchanged or replaced with
  another theme by invoking the procedure <code>ttk::setTheme</code> or
  <code>tile::setTheme</code>, depending on the current tile version</b>.&nbsp;
  (See also the <code><a href=
  "mentryThemes.html#setTheme">mentry::setTheme</a></code> command.)</p>

  <p>After these cautions concerning the use of tile, the rest of this section
  describes the differences between the packages Mentry and Mentry_tile.</p>

  <p>The Mentry_tile package checks whether the required Tk and tile versions
  are present, by executing the commands</p>

  <blockquote>
    <pre>
package require Tk 8.4
if {$::tk_version &lt; 8.5 || [regexp {^8\.5a[1-5]$} $::tk_patchLevel]} {
    package require tile 0.6
}
</pre>
  </blockquote>

  <p>The second command above reflects the fact that, beginning with Tk 8.5a6,
  tile is integrated into the Tk core and therefore it should only be loaded
  explicitly when using an earlier Tk version.</p>

  <p>Apart from this and the <code>_tile</code> suffix in the&nbsp;
  <code>package require</code>&nbsp; command, the only difference (from the
  programmer's point of view) between the packages Mentry and Mentry_tile is
  related to the supported configuration options:&nbsp; The following Tk
  (entry) widget options, present in the Mentry package, are not supported by
  Mentry_tile, because they are not available for tile (entry) widgets:
  <code>-borderwidth</code>, <code>-disabledbackground</code>,
  <code>-disabledforeground</code>, <code>-highlightbackground</code>,
  <code>-highlightcolor</code>, <code>-highlightthickness</code>,
  <code>-insertbackground</code>, <code>-insertborderwidth</code>,
  <code>-insertofftime</code>, <code>-insertontime</code>,
  <code>-insertwidth</code>, <code>-readonlybackground</code>,
  <code>-relief</code>, <code>-selectbackground</code>,
  <code>-selectborderwidth</code>, and <code>-selectforeground</code>.</p>

  <p>Notice that the <code>-background</code> option doesn't work as expected
  if the current theme is <code>plastik</code>, <code>tileqt</code>,
  <code>vista</code>, or <code>xpnative</code>, because these themes silently
  ignore any attempt to change the background color of a tile entry widget.</p>

  <p>Finally, take into account that, when using the <code>tileqt</code> theme,
  the version number of the <code>tile::theme::tileqt</code> package must be
  0.4 or higher, and <code>tileqt</code> itself won't work with tile versions
  earlier than 0.7.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="examples">Examples</h2>

  <h3 id="ex_phoneNumber">A mentry Widget for Phone Numbers</h3>

  <p>Let's resume the <a href="#ov_example">example</a> mentioned in the
  Overview in a bit more systematical manner.&nbsp; First, we will write a
  procedure for creating a mentry widget that allows to display and edit
  10-digit phone numbers and accepts any configuration options supported by the
  <code><a href="mentryWidget.html">mentry::mentry</a></code> command:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# phoneNumberMentry
#
# Creates a new mentry widget win that allows to display and edit 10-digit
# phone numbers.  Sets the type attribute of the widget to PhoneNumber and
# returns the name of the newly created widget.
#------------------------------------------------------------------------------</span>
proc phoneNumberMentry {win args} {
    <span class="cmt">#
    # Create a mentry widget consisting of two entries of width 3 and one of
    # width 4, separated by "-" characters, and set its type to PhoneNumber
    #</span>
    eval [list mentry::mentry $win] $args
    $win configure -body {3 - 3 - 4}
    $win attrib type PhoneNumber

    <span class="cmt">#
    # Allow only decimal digits in all entry children; use
    # wcb::cbappend (or wcb::cbprepend) instead of wcb::callback
    # in order to keep the wcb::checkEntryLen callback,
    # registered by mentry::mentry for all entry children
    #</span>
    for {set n 0} {$n &lt; 3} {incr n} {
        wcb::cbappend [$win entrypath $n] before insert wcb::checkStrForNum
        $win adjustentry $n "0123456789"
    }

    return $win
}
</pre>
  </blockquote>

  <p>The first argument <code>win</code> is the name of the widget, and the
  keyword <code>args</code> represents a list of configuration options and
  their values, just like in the case of the standard Tk widgets.&nbsp; The
  value&nbsp; <code>{3 - 3 - 4}</code>&nbsp; of the <code><a href=
  "mentryWidget.html#body">-body</a></code> option specifies that the mentry
  should consist of two entries of width 3 and one of width 4, separated by
  labels displaying the <code>"-"</code> character.</p>

  <p>Each mentry widget may have any number of private <b>attributes</b>, which
  can be set and retrieved with the aid of the <code><a href=
  "mentryWidget.html#attrib">attrib</a></code> subcommand of the Tcl procedure
  corresponding to the widget.&nbsp; We use this subcommand to define the
  <code>type</code> attribute of the newly created widget and set it to the
  value <code>"PhoneNumber"</code>.&nbsp; Although this is not strictly
  necessary, it will enable us to distinguish a phone number mentry from other
  multi-entry widgets.</p>

  <p>The <code>mentry::mentry</code> command registers the <code><a href=
  "wcbRef.html#entrycb">wcb::checkEntryLen</a></code> callback with each entry
  child of the mentry widget to restrict the number of characters that can be
  inserted into it to the initial width specified in the <code>-body</code>
  option.&nbsp; Besides this constraint, we want our entries to accept only
  decimal digits, therefore we use the <code><a href=
  "wcbRef.html#cbappend">wcb::cbappend</a></code> command to <i>add</i> the
  procedure <code><a href="wcbRef.html#entrycb">wcb::checkStrForNum</a></code>
  to the callback list of each entry child.&nbsp; By invoking <code><a href=
  "wcbRef.html#callback">wcb::callback</a></code> instead of
  <code>wcb::cbappend</code> (or <code><a href=
  "wcbRef.html#cbprepend">wcb::cbprepend</a></code>), we would <i>replace</i>
  the callback list with the one consisting of the single element
  <code>wcb::checkStrForNum</code>.</p>

  <p>Now we know that each entry child of the mentry widget will only accept a
  limited number of decimal digits.&nbsp; But are the widths of the entry
  children large enough to hold the maximal number of 3 or 4 decimal digits,
  respectively?&nbsp; In the case of a fixed-width font the answer is
  definitely "yes", and the same holds true for most proportionally-spaced
  fonts.&nbsp; There are, however, fonts in which not all decimal digits have
  the same width.&nbsp; For this reason, we invoke the <code><a href=
  "mentryWidget.html#adjustentry">adjustentry</a></code> subcommand for each
  entry child, passing to it as last argument a string consisting of the
  allowed characters, which in this example are the decimal digits.&nbsp; This
  subcommand will increase the entry widget's width if needed, to make it just
  large enough for texts of the child-specific maximal length, consisting of
  characters specified by that string.</p>

  <p>Our second procedure outputs a phone number to a mentry widget having a
  <code>type</code> attribute value of <code>"PhoneNumber"</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# putPhoneNumber
#
# Outputs the phone number num to the mentry widget win of type PhoneNumber.
# The phone number must be a string of length 10, consisting of decimal digits.
#------------------------------------------------------------------------------</span>
proc putPhoneNumber {num win} {
    <span class="cmt">#
    # Check the syntax of num
    #</span>
    if {[string length $num] != 10 || ![regexp {^[0-9]*$} $num]} {
        return -code error "expected 10 decimal digits but got \"$num\""
    } 

    <span class="cmt">#
    # Check the widget and display the properly formatted phone number
    #</span>
    checkIfPhoneNumberMentry $win
    $win put 0 [string range $num 0 2] [string range $num 3 5] \
               [string range $num 6 9]
}
</pre>
  </blockquote>

  <p>We use the <code><a href="mentryWidget.html#put">put</a></code> subcommand
  of the Tcl procedure corresponding to the mentry widget to display the three
  substrings of the given phone number in the corresponding entries, starting
  with the entry child whose index is specified as the first argument following
  the word <code>put</code>.</p>

  <p>Next, we need a procedure that returns the phone number contained in a
  mentry widget having a <code>type</code> attribute value of
  <code>"PhoneNumber"</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# getPhoneNumber
#
# Returns the phone number contained in the mentry widget win of type
# PhoneNumber.
#------------------------------------------------------------------------------</span>
proc getPhoneNumber win {
    <span class="cmt">#
    # Check the widget
    #</span>
    checkIfPhoneNumberMentry $win

    <span class="cmt">#
    # Generate an error if any entry child is empty or incomplete
    #</span>
    for {set n 0} {$n &lt; 3} {incr n} {
        if {[$win isempty $n]} {
            focus [$win entrypath $n]
            return -code error EMPTY
        }
        if {![$win isfull $n]} {
            focus [$win entrypath $n]
            return -code error INCOMPL
        }
    }

    <span class="cmt">#
    # Return the phone number built from the
    # values contained in the entry children
    #</span>
    $win getarray strs
    return $strs(0)$strs(1)$strs(2)
}
</pre>
  </blockquote>

  <p>The procedure runs over the indices of the entry children of the given
  mentry widget and invokes the <code><a href=
  "mentryWidget.html#isempty">isempty</a></code> and <code><a href=
  "mentryWidget.html#isfull">isfull</a></code> subcommands of the Tcl command
  corresponding to the given mentry widget.&nbsp; If one of the entries is
  found to be empty or incomplete, the procedure gets its path name by calling
  the <code><a href="mentryWidget.html#entrypath">entrypath</a></code>
  subcommand, sets the focus to that entry, raises an error, and returns the
  value <code>"EMPTY"</code> or <code>"INCOMPL"</code>, respectively.&nbsp; The
  application invoking this procedure should then display an appropriate error
  message corresponding to the return value.</p>

  <p>Notice that the number <code>3</code> in the <code>for</code> loop above
  is nothing else than&nbsp; <code>[$win <a href=
  "mentryWidget.html#entrycount">entrycount</a>]</code>.&nbsp; Also, it would
  be sufficient to check whether all entry children are full, because an empty
  entry is at the same time incomplete.&nbsp; The preliminary check whether an
  entry is empty is just made for the user's convenience.</p>

  <p>To build the phone number from the values contained in the entry children,
  we use a temporary array variable and invoke the <code><a href=
  "mentryWidget.html#getarray">getarray</a></code> subcommand, which copies the
  contents of the entries to the corresponding array elements.</p>

  <p>The last two procedures presented above contain an invocation of the
  command <code>checkIfPhoneNumberMentry</code>, which is implemented as
  folows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# checkIfPhoneNumberMentry
#
# Generates an error if win is not a mentry widget of type PhoneNumber.
#------------------------------------------------------------------------------</span>
proc checkIfPhoneNumberMentry win {
    if {![winfo exists $win]} {
        return -code error "bad window path name \"$win\""
    }

    if {[string compare [winfo class $win] "Mentry"] != 0 ||
        [string compare [$win attrib type] "PhoneNumber"] != 0} {
        return -code error \
               "window \"$win\" is not a mentry widget for phone numbers"
    }
}
</pre>
  </blockquote>

  <p>This procedure retrieves the value of the <code>type</code> attribute of
  its argument to check whether the latter denotes a mentry widget for phone
  numbers (remember that this attribute was set to the value
  <code>"PhoneNumber"</code> in the procedure
  <code>phoneNumberMentry</code>).</p>

  <p>The four procedures discussed above are implemented in the file
  <code>phonenumber.tcl</code>, contained in the <code>demos</code>
  directory.&nbsp; This script also puts them together to build a small
  application displaying the following figure:</p>

  <blockquote>
    <img src="phonenumber.png" alt="Phone Number" width="269" height="228">
  </blockquote>

  <p>Here is the relevant code fragment:</p>

  <blockquote>
    <pre>
package require mentry

set title "Phone Number"
wm title . $title

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option.tcl]

. . .

<span class="cmt">#
# Frame .f with a mentry displaying a phone number
#</span>
frame .f
label .f.l -text "A mentry widget for phone numbers:"
phoneNumberMentry .f.me -background white
pack .f.l .f.me

<span class="cmt">#
# Message strings corresponding to the values
# returned by getPhoneNumber on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    INCOMPL     "Incomplete field value"
}

<span class="cmt">#
# Button .get invoking the procedure getPhoneNumber
#</span>
button .get -text "Get from mentry" -command {
    if {[catch {
        set num ""
        set num [getPhoneNumber .f.me]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .num displaying the result of getPhoneNumber
#</span>
label .num -textvariable num -background white

. . .

putPhoneNumber 1234567890 .f.me
focus [.f.me entrypath 0]
</pre>
  </blockquote>

  <h3 id="ex_ethernetAddr">A mentry Widget for Ethernet Addresses</h3>

  <p>Ethernet addresses are usuallly written in the form
  <code>"XX:XX:XX:XX:XX:XX"</code>, where each <code>"X"</code> is a
  hexadecimal digit.&nbsp; The file <code>ethernetaddr.tcl</code> in the
  <code>demos</code> directory contains the steps needed to create and use a
  multi-entry widget for displaying and editing Ethernet addresses.&nbsp; It
  implements the procedures <code>ethernetAddrMentry</code>,
  <code>putEthernetAddr</code>, and <code>getEthernetAddr</code>; the last two
  invoke the helper procedure <code>checkIfEthernetAddrMentry</code>, while the
  first one is implemented as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# ethernetAddrMentry
#   
# Creates a new mentry widget win that allows to display and edit Ethernet
# addresses.  Sets the type attribute of the widget to EthernetAddr and returns
# the name of the newly created widget.
#------------------------------------------------------------------------------</span>
proc ethernetAddrMentry {win args} {
    <span class="cmt">#
    # Create a mentry widget consisting of 6 entry children of
    # width 2, separated by colons, and set its type to EthernetAddr
    #</span>
    eval [list mentry::mentry $win] $args
    $win configure -body {2 : 2 : 2 : 2 : 2 : 2}
    $win attrib type EthernetAddr

    <span class="cmt">#
    # Install automatic uppercase conversion and allow only hexadecimal
    # digits in all entry children; use wcb::cbappend (or wcb::cbprepend)
    # instead of wcb::callback in order to keep the wcb::checkEntryLen
    # callback, registered by mentry::mentry for all entry children
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        wcb::cbappend [$win entrypath $n] before insert wcb::convStrToUpper \
                      {wcb::checkStrForRegExp {^[0-9A-F]*$}}
        $win adjustentry $n "0123456789ABCDEF"
    }
    
    return $win
}
</pre>
  </blockquote>

  <p>Notice again the invocation of the <code><a href=
  "mentryWidget.html#adjustentry">adjustentry</a></code> subcommand of the Tcl
  command associated with the mentry widget, for each of its entry
  children.&nbsp; This is necessary, because in the case of a
  proportionally-spaced font the characters <code>A</code> - <code>F</code>
  need more room than the digits <code>0</code> - <code>9</code> (and it is not
  even guaranteed that the latters have the same width).</p>

  <p>The procedure <code>putEthernetAddr</code> expects as its first argument a
  string of the form <code>"XX:XX:XX:XX:XX:XX"</code>, where each
  <code>"XX"</code> must be a hexadecimal string in the range <code>0</code> -
  <code>255</code>:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# putEthernetAddr
#
# Outputs the Ethernet address addr to the mentry widget win of type
# EthernetAddr.  The address must be a string of the form XX:XX:XX:XX:XX:XX,
# where each XX must be a hexadecimal string in the range 0 - 255.  Leading
# zeros are allowed (but not required), hence the components may have more (but
# also less) than two characters; the procedure displays them with exactly two
# digits.
#------------------------------------------------------------------------------</span>
proc putEthernetAddr {addr win} {
    set errorMsg "expected an Ethernet address but got \"$addr\""

    <span class="cmt">#
    # Check the syntax of addr
    #</span>
    set lst [split $addr :]
    if {[llength $lst] != 6} {
        return -code error $errorMsg
    }

    <span class="cmt">#
    # Try to convert the 6 components of addr to hexadecimal
    # strings and check whether they are in the range 0 - 255
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        set val 0x[lindex $lst $n]
        if {[catch {format "%02X" $val} str$n] != 0 || $val &lt; 0 || $val &gt; 255} {
            return -code error $errorMsg
        }
    }

    <span class="cmt">#
    # Check the widget and display the properly formatted Ethernet address
    #</span>
    checkIfEthernetAddrMentry $win
    $win put 0 $str0 $str1 $str2 $str3 $str4 $str5
}
</pre>
  </blockquote>

  <p>The procedure <code>getEthernetAddr</code> raises an error if any entry
  child of the given mentry widget is empty.&nbsp; It accepts also entry
  strings of length one, but in the return value all components will have
  exactly two digits:</p>

  <blockquote>
    <pre>
<span class="cmt">#------------------------------------------------------------------------------
# getEthernetAddr
#
# Returns the Ethernet address contained in the mentry widget win of type
# EthernetAddr.
#------------------------------------------------------------------------------</span>
proc getEthernetAddr win {
    <span class="cmt">#
    # Check the widget
    #</span>
    checkIfEthernetAddrMentry $win

    <span class="cmt">#
    # Generate an error if any entry child is empty
    #</span>
    for {set n 0} {$n &lt; 6} {incr n} {
        if {[$win isempty $n]} {
            focus [$win entrypath $n]
            return -code error EMPTY
        }
    }

    <span class="cmt">#
    # Return the properly formatted Ethernet address built
    # from the values contained in the entry children
    #</span>
    $win getarray strs
    return [format "%02X:%02X:%02X:%02X:%02X:%02X" \
            0x$strs(0) 0x$strs(1) 0x$strs(2) 0x$strs(3) 0x$strs(4) 0x$strs(5)]
}
</pre>
  </blockquote>

  <p>We will not show the rest of the code here, because it is very similar to
  the one presented in the preceding section.&nbsp; The mentry widget for
  Ethernet addresses looks like in the following figure:</p>

  <blockquote>
    <img src="ethernetaddr.png" alt="Ethernet Address" width="290"
    height="243">
  </blockquote>

  <h3 id="ex_dateTime">Using mentry Widgets for Date and Time</h3>

  <p>Multi-entry widgets can be used to display and edit date and time in a
  great variety of formats.&nbsp; The Mentry package contains ready-to-use
  commands for this purpose:</p>

  <ul>
    <li>The procedure <code><a href=
    "mentryDateTime.html#dateMentry">mentry::dateMentry</a></code> creates a
    new mentry widget for displaying and editing a date according to the format
    passed to the command as a three-character string consisting of the field
    descriptor characters <code>"d"</code>, <code>"m"</code>, and
    <code>"y"</code> or <code>"Y"</code>, known from the&nbsp; <code>clock
    format</code>&nbsp; command.&nbsp; Another argument expected by the
    procedure is the string (usually a single character) to be displayed in the
    labels separating the three components of the date.</li>

    <li class="tm">Similarly, the procedure <code><a href=
    "mentryDateTime.html#timeMentry">mentry::timeMentry</a></code> creates a
    new mentry widget for displaying and editing a time according to the format
    passed to the command as a two- or three-character string consisting of the
    following field descriptor characters of the&nbsp; <code>clock
    format</code>&nbsp; command: <code>"H"</code> or <code>"I"</code>, followed
    by <code>"M"</code>, and optionally the letter <code>"S"</code>.&nbsp; An
    <code>"H"</code> as first character specifies the time format
    <code>"%H:%M"</code> or <code>"%H:%M:%S"</code> (i.e., with the hour
    between <code>0</code> and <code>23</code>), while the letter
    <code>"I"</code> stands for&nbsp; <code>"%I:%M %p"</code>&nbsp; or&nbsp;
    <code>"%I:%M:%S %p"</code>&nbsp; (i.e., with AM/PM indicator).&nbsp; The
    procedure expects the separator string (which is usually the
    <code>":"</code> character) as another command-line argument.</li>

    <li class="tm">Finally, the procedure <code><a href=
    "mentryDateTime.html#dateTimeMentry">mentry::dateTimeentry</a></code>
    creates a new mentry widget for displaying and editing a date & time
    according to the format passed to the command as a 5- or 6-character
    string, with the first three characters consisting of the letters
    <code>"d"</code>, <code>"m"</code>, and <code>"y"</code> or
    <code>"Y"</code>, followed by two or three further field descriptor
    characters of the&nbsp; <code>clock format</code>&nbsp; command, which must
    be: <code>"H"</code> or <code>"I"</code>, then <code>"M"</code>, and
    optionally the letter <code>"S"</code>.&nbsp; The procedure expects two
    more arguments, specifying the separators to be used in the date and time
    parts of the mentry widget, respectively.</li>
  </ul>

  <p>Before describing the other date- and time-related commands provided by
  the Mentry package, let's see how the first two of the above are invoked in
  the file <code>datetime1.tcl</code>, located in the <code>demos</code>
  directory:</p>

  <blockquote>
    <pre>
package require mentry

set title "Date & Time"
wm title . $title 

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option.tcl]
    
<span class="cmt">#   
# Date and time formats supported by this demo
# script and the corresponding field separators
#</span>
array set dateFmts {0 mdy  1 dmy  2 Ymd}
array set dateSeps {0 /    1 .    2 -  }
array set timeFmts {0 IMS  1 HMS}
array set timeSeps {0 :    1 :  }

<span class="cmt">#
# Choose the date & time formats; don't use the %p field descriptor
# for displaying the AM/PM indicator, because it doesn't work on
# UNIX if Tcl/Tk 8.4 or higher is used in a non-default locale
#</span>
wm withdraw .
set clockVal [clock seconds]
if {[clock format $clockVal -format "%H"] &lt; 12} {
    set meridian AM
} else {
    set meridian PM
}
set dateIdx [tk_dialog .choice $title "Please choose a date format" {} -1 \
                       [clock format $clockVal -format "%m/%d/%y"] \ 
                       [clock format $clockVal -format "%d.%m.%y"] \ 
                       [clock format $clockVal -format "%Y-%m-%d"]]
set timeIdx [tk_dialog .choice $title "Please choose a time format" {} -1 \
                       [clock format $clockVal -format "%I:%M:%S $meridian"] \
                       [clock format $clockVal -format "%H:%M:%S"]]
wm deiconify .

<span class="cmt">#   
# Frame .f with mentries displaying the date & time
#</span>   
frame .f
label .f.lDate -text "Date: "
mentry::dateMentry .f.date $dateFmts($dateIdx) $dateSeps($dateIdx) \ 
                   -justify center -background white
frame .f.gap -width 10
label .f.lTime -text "Time: "
mentry::timeMentry .f.time $timeFmts($timeIdx) $timeSeps($timeIdx) \
                   -justify center -background white
pack .f.lDate .f.date .f.gap .f.lTime .f.time -side left
</pre>
  </blockquote>

  <p>Before displaying the main window, the script lets the user choose one out
  of three date and one out of two time formats.&nbsp; The corresponding
  command-line arguments passed to <code>mentry::dateMentry</code> and
  <code>mentry::timeMentry</code> are taken from the arrays
  <code>dateFmts</code>, <code>dateSeps</code>, <code>timeFmts</code>, and
  <code>timeSeps</code>.</p>

  <p>The following figure corresponds to the choices&nbsp; <code>dateIdx =
  2</code>&nbsp; and&nbsp; <code>timeIdx = 1</code>:</p>

  <blockquote>
    <img src="datetime1.png" alt="Date & Time" width="279" height="209">
  </blockquote>

  <p>The demo script <code>datetime2.tcl</code> displays both the date and time
  in the same mentry widget, with the aid of the third command described
  above:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Frame .f with a mentry displaying the date & time
#</span>
frame .f
label .f.l -text "Date & time: "
mentry::dateTimeMentry .f.me $dateFmts($dateIdx)$timeFmts($timeIdx) \
                       $dateSeps($dateIdx) $timeSeps($timeIdx) \
                       -justify center -background white
pack .f.l .f.me
</pre>
  </blockquote>

  <blockquote>
    <img src="datetime2.png" alt="Date & Time" width="272" height="209">
  </blockquote>

  <p>The Mentry package exports two further commands for date, time, and date &
  time mentries:</p>

  <ul>
    <li>The procedure <code><a href=
    "mentryDateTime.html#putClockVal">mentry::putClockVal</a></code> outputs
    the date, time, or date & time corresponding to an integer clock value
    specified as its first argument to a date, time, or date & time mentry
    widget, passed to it as the second parameter.&nbsp; Like the
    &nbsp;<code>clock format</code>&nbsp; command, the procedure accepts the
    optional argument pair&nbsp; <code>-gmt <i>boolean</i></code>.</li>

    <li class="tm">The procedure <code><a href=
    "mentryDateTime.html#getClockVal">mentry::getClockVal</a></code> returns
    the clock value corresponding to the date, time, or date & time contained
    in the date, time, or date & time mentry specified as its first
    argument.&nbsp; Like the &nbsp;<code>clock scan</code>&nbsp; command, the
    procedure accepts the optional argument pairs&nbsp; <code>-base
    <i>clockValue</i></code>&nbsp; and&nbsp; <code>-gmt
    <i>boolean</i></code>.&nbsp; On failure, the procedure sets the focus to
    the first erronous entry child, generates an error, and returns one of the
    values contained in the following code fragment taken from the scripts
    <code>datetime1.tcl</code> and <code>datetime2.tcl</code>:

      <blockquote>
        <pre>
<span class="cmt">#
# Message strings corresponding to the values
# returned by mentry::getClockVal on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    BAD         "Invalid field value"
    BAD_DATE    "Invalid date"
    BAD_YEAR    "Unsupported year"
}
</pre>
      </blockquote>

      <p>The string <code>"EMPTY"</code> is returned if any entry child (except
      the one containing the seconds) was found to be empty.&nbsp; The value
      <code>"BAD"</code> means a day, month, or hour value of <code>0</code>
      (the hour must not be <code>0</code> if the AM/PM indicator is
      present).&nbsp; The string <code>"BAD_DATE"</code> is returned when the
      &lt;year, month, day&gt; triple is invalid (note that the procedure is
      aware of leap years).&nbsp; Finally, even if this triple is valid, the
      conversion (made with the aid of the&nbsp; <code>clock scan</code>&nbsp;
      command) can fail because of an unsupported year value (e.g., between
      <code>38</code> and <code>70</code>); in this case the string
      <code>"BAD_YEAR"</code> is returned.</p>
    </li>
  </ul>

  <p>The demo script <code>datetime1.tcl</code> invokes the last two commands
  as follows:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Button .get invoking the procedure mentry::getClockVal
#</span>
button .get -text "Get from mentries" -command {
    if {[catch {
        set dateTime ""
        set base [mentry::getClockVal .f.date]
        set clockVal [mentry::getClockVal .f.time -base $base]
        set dateTime [clock format $clockVal -format "%c"]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .dateTime displaying the result of mentry::getClockVal
#</span>
label .dateTime -textvariable dateTime -background white

. . .

set clockVal [clock seconds]
mentry::putClockVal $clockVal .f.date
mentry::putClockVal $clockVal .f.time
focus [.f.date entrypath 0]
</pre>
  </blockquote>

  <p>To obtain the clock value from the mentry widgets <code>.f.date</code> and
  <code>.f.time</code>, we first pass the name of the date mentry to the
  command <code>mentry::getClockVal</code> and then use the result as the value
  of the <code>-base</code> option when passing the name of the time mentry to
  the same procedure.</p>

  <p>The demo script <code>datetime2.tcl</code> is simpler:</p>

  <blockquote>
    <pre>
<span class="cmt">#
# Button .get invoking the procedure mentry::getClockVal
#</span>
button .get -text "Get from mentry" -command {
    if {[catch {
        set dateTime ""
        set clockVal [mentry::getClockVal .f.me]
        set dateTime [clock format $clockVal -format "%c"]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label .dateTime displaying the result of mentry::getClockVal
#</span>
label .dateTime -textvariable dateTime -background white

. . .

set clockVal [clock seconds]
mentry::putClockVal $clockVal .f.me
focus [.f.me entrypath 0]
</pre>
  </blockquote>

  <h3 id="ex_tile">Tile-Based Demo Scripts</h3>

  <p>The Mentry distribution contains also tile-based counterparts of the demo
  scripts discussed above.&nbsp; As described in the <a href="#ov_tile">More on
  Mentry_tile</a> section of this tutorial, it is quite easy to port an
  application using the Mentry package to one based on Mentry_tile.&nbsp; For
  example, let's see how to transform the demo script
  <code>phonenumber.tcl</code> into a tile-based one, called
  <code>phonenumber_tile.tcl</code>.&nbsp; The changes are shown below in
  <span class="red">red</span> color:</p>

  <blockquote>
    <pre>
package require mentry<span class="red">_tile</span>

set title "Phone Number"
wm title . $title

<span class="cmt">#
# Add some entries to the Tk option database
#</span>
source [file join [file dirname [info script]] option<span class="red">_tile</span>.tcl]

. . .

<span class="red">#
# Improve the window's appearance by using a tile
# frame as a container for the other widgets
#
ttk::frame .base</span>

<span class="cmt">#
# Frame <span class="red">.base</span>.f with a mentry displaying a phone number
#</span>
<span class="red">ttk::</span>frame .base.f
<span class="red">ttk::</span>label .base.f.l -text "A mentry widget for phone numbers:"
phoneNumberMentry <span class="red">.base</span>.f.me
pack <span class="red">.base</span>.f.l <span class="red">.base</span>.f.me

<span class="cmt">#
# Message strings corresponding to the values
# returned by getPhoneNumber on failure
#</span>
array set msgs {
    EMPTY       "Field value missing"
    INCOMPL     "Incomplete field value"
}

<span class="cmt">#
# Button <span class="red">.base</span>.get invoking the procedure getPhoneNumber
#</span>
<span class="red">ttk</span>::button <span class="red">.base</span>.get -text "Get from mentry" -command {
    if {[catch {
        set num ""
        set num [getPhoneNumber <span class="red">.base</span>.f.me]
    } result] != 0} {
        bell
        tk_messageBox -icon error -message $msgs($result) \
                      -title $title -type ok
    }
}

<span class="cmt">#
# Label <span class="red">.base</span>.num displaying the result of getPhoneNumber
#</span>
<span class="red">ttk::</span>label <span class="red">.base</span>.num -textvariable num -background white

. . .

putPhoneNumber 1234567890 <span class="red">.base</span>.f.me
focus [<span class="red">.base</span>.f.me entrypath 0]
</pre>
  </blockquote>

  <p>That's all!&nbsp; The resulting window has a nice theme-specific
  appearance:</p>

  <blockquote>
    <img src="phonenumber_tile.png" alt="Phone Number" width="267"
    height="216">
  </blockquote>

  <p>The only Mentry-specific change in the code above consists of the use of
  the <code>_tile</code> suffix in <code>mentry_tile</code>.</p>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for Date and Time</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, date, time, clock">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for Date and Time</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#dateMentry">The <code><b>mentry::dateMentry</b></code>
    Command</a></li>

    <li><a href="#timeMentry">The <code><b>mentry::timeMentry</b></code>
    Command</a></li>

    <li><a href="#dateTimeMentry">The
    <code><b>mentry::dateTimeMentry</b></code> Command</a></li>

    <li><a href="#putClockVal">The <code><b>mentry::putClockVal</b></code>
    Command</a></li>

    <li><a href="#getClockVal">The <code><b>mentry::getClockVal</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="dateMentry">The <code><b>mentry::dateMentry</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::dateMentry</code> &ndash; Create and manipulate mentry
    widgets for date</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::dateMentry</b> <i>pathName format separator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a date according to the
    <code><i>format</i></code> argument, which must be a string of length 3,
    consisting of the letters <code><b>"d"</b></code> for the day
    (<code>01</code> - <code>31</code>), <code><b>"m"</b></code> for the month
    (<code>01</code> - <code>12</code>), and <code><b>"y"</b></code> or
    <code><b>"Y"</b></code> for the year without century (<code>00</code> -
    <code>99</code>) or with century (e.g., <code>2008</code>), in an arbitrary
    order.&nbsp; These field descriptor characters have the same meanings as in
    the&nbsp; <code><b>clock format</b></code>&nbsp; command.&nbsp; The
    <code><i>separator</i></code> argument specifies the text to be displayed
    in the labels separating the three entry children of the mentry widget (the
    most common values are the <code><b>"/"</b></code>,
    <code><b>"-"</b></code>, and <code><b>"."</b></code> characters).&nbsp; The
    supported <code><i>options</i></code> are the same as in the case of the
    <code><b><a href="mentryWidget.html">mentry::mentry</a></b></code>
    command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"Date"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::dateMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="timeMentry">The <code><b>mentry::timeMentry</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::timeMentry</code> &ndash; Create and manipulate mentry
    widgets for time</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::timeMentry</b> <i>pathName format separator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a time according to the
    <code><i>format</i></code> argument, which must be a string of length 2 or
    3, consisting of the following field descriptor characters of the&nbsp;
    <code><b>clock format</b></code>&nbsp; command: <code><b>"H"</b></code> or
    <code><b>"I"</b></code>, followed by <code><b>"M"</b></code>, and
    optionally the letter <code><b>"S"</b></code>.&nbsp; An
    <code><b>"H"</b></code> as first character specifies the time format
    <code><b>"%H:%M"</b></code> or <code><b>"%H:%M:%S"</b></code> (i.e., with
    the hour between <code>0</code> and <code>23</code>), while the letter
    <code><b>"I"</b></code> stands for&nbsp; <code><b>"%I:%M
    %p"</b></code>&nbsp; or&nbsp; <code><b>"%I:%M:%S %p"</b></code>&nbsp;
    (i.e., with AM/PM indicator).&nbsp; The <code><i>separator</i></code>
    argument specifies the text to be displayed in the labels separating the
    entry children of the mentry widget (this is usually the
    <code><b>":"</b></code> character).&nbsp; The <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"Time"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::timeMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, time</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="dateTimeMentry">The <code><b>mentry::dateTimeMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::dateTimeMentry</code> &ndash; Create and manipulate
    mentry widgets for date & time</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::dateTimeMentry</b> <i>pathName format dateSeparator timeSeparator</i> ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing a date & time according to the
    <code><i>format</i></code> argument, which must be a string of length 5 or
    6, with the first 3 characters consisting of the letters
    <code><b>"d"</b></code> for the day (<code>01</code> - <code>31</code>),
    <code><b>"m"</b></code> for the month (<code>01</code> - <code>12</code>),
    and <code><b>"y"</b></code> or <code><b>"Y"</b></code> for the year without
    century (<code>00</code> - <code>99</code>) or with century (e.g.,
    <code>2008</code>), in an arbitrary order, followed by 2 or 3 further field
    descriptor characters of the&nbsp;<code><b>clock format</b></code>&nbsp;
    command, which must be: <code><b>"H"</b></code> or <code><b>"I"</b></code>,
    then <code><b>"M"</b></code>, and optionally the letter
    <code><b>"S"</b></code>.&nbsp; An <code><b>"H"</b></code> specifies the
    time format <code><b>"%H:%M"</b></code> or <code><b>"%H:%M:%S"</b></code>
    (i.e., with the hour between <code>0</code> and <code>23</code>), while the
    letter <code><b>"I"</b></code> stands for&nbsp; <code><b>"%I:%M
    %p"</b></code>&nbsp; or&nbsp; <code><b>"%I:%M:%S %p"</b></code>&nbsp;
    (i.e., with AM/PM indicator).&nbsp; The <code><i>dateSeparator</i></code>
    argument specifies the text to be displayed in the labels separating the
    entry children in the date part of the mentry widget (the most common
    values are the <code><b>"/"</b></code>, <code><b>"-"</b></code>, and
    <code><b>"."</b></code> characters).&nbsp; Similarly, the
    <code><i>timeSeparator</i></code> argument stands for the text to be
    displayed in the labels separating the entry children in the time part of
    mentry widget (this is usually the <code><b>":"</b></code>
    character).&nbsp; The date and time parts in turn are separated from each
    other by a space character.&nbsp; The supported <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"DateTime"</code>, saves the value of
    <code><i>format</i></code> in its <code><b>format</b></code> attribute, and
    returns the name of the newly created widget.</dd>

    <dt class="tm"><b>DEFAULT BINDINGS</b></dt>

    <dd>The <code><b>mentry::dateTimeMentry</b></code> command defines four new
    keyboard bindings for the entry children of the mentry widget it
    creates:&nbsp; The <code>Up</code> key increments the entry's value by 1 if
    the latter is less than the allowed maximum for that child.&nbsp;
    Similarly, the <code>Down</code> key decrements the entry's value by 1 if
    the latter is greater than the allowed minimum for that child.&nbsp; The
    <code>Prior</code> key increments the entry's value by at most 10 if the
    latter is less than the allowed maximum for that child.&nbsp; Similarly,
    the <code>Next</code> key decrements the entry's value by at most 10 if the
    latter is greater than the allowed minimum for that child.&nbsp; If the
    entry is empty then all of these keys insert the child-specific minimum
    value into the entry.</dd>

    <dd class="tm">The actions performed by the <code>Up</code> and
    <code>Down</code> keys can also be triggered by rolling the mouse
    wheel.&nbsp; In addition, on Mac OS Classic and Mac OS X Aqua, the actions
    performed by the <code>Prior</code> and <code>Next</code> keys can also be
    triggered by rolling the mouse wheel while holding down the
    <code>Option</code> key.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putClockVal">The <code><b>mentry::putClockVal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putClockVal</code> &ndash; Output a clock value to a
    date, time, or date & time mentry</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putClockVal</b> <i>clockValue</i> <i>pathName</i> ?<b>-gmt</b> <i>boolean</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the date, time, or date & time corresponding to
    the integer <code><i>clockValue</i></code> to the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href="#dateMentry">mentry::dateMentry</a></b></code>,
    <code><b><a href="#timeMentry">mentry::timeMentry</a></b></code>, or
    <code><b><a href="#dateTimeMentry">mentry::dateTimeMentry</a></b></code>
    command (this is checked by examining the widget's <code><b>type</b></code>
    attribute, which must have the value <code>"Date"</code>,
    <code>"Time"</code>, or <code>"DateTime"</code>).</dd>

    <dd class="tm">Like in the case of the&nbsp; <code><b>clock
    format</b></code>&nbsp; command, the optional argument pair&nbsp;
    <code><b>-gmt</b> <i>boolean</i></code> specifies whether the clock value
    is to be formatted as Greenwich Mean Time or according to the local
    timezone as defined by the operating environment.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time, clock</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getClockVal">The <code><b>mentry::getClockVal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getClockVal</code> &ndash; Get the clock value from a
    date, time, or date & time mentry</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getClockVal</b> <i>pathName</i> ?<b>-base</b> <i>clockValue</i>? ?<b>-gmt</b> <i>boolean</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the clock value corresponding to the date, time,
    or date & time contained in the mentry widget <code><i>pathName</i></code>,
    which must have been created with the <code><b><a href=
    "#dateMentry">mentry::dateMentry</a></b></code>, <code><b><a href=
    "#timeMentry">mentry::timeMentry</a></b></code>, or <code><b><a href=
    "#dateTimeMentry">mentry::dateTimeMentry</a></b></code> command (this is
    checked by examining the widget's <code><b>type</b></code> attribute, which
    must have the value <code>"Date"</code>, <code>"Time"</code>, or
    <code>"DateTime"</code>).</dd>

    <dd class="tm">Like in the case of the&nbsp; <code><b>clock
    scan</b></code>&nbsp; command, the optional argument pair&nbsp;
    <code><b>-base</b> <i>clockValue</i></code> specifies that the date
    contained in <code><i>clockValue</i></code> is to be used when getting the
    clock value from the given mentry widget, and the optional argument
    pair&nbsp; <code><b>-gmt</b> <i>boolean</i></code> specifies whether the
    clock value is to be calculated relative to Greenwich Mean Time or
    according to the local timezone as defined by the operating
    environment.</dd>

    <dd class="tm">If an error occurs during the conversion, the command sets
    the focus to the first erronous entry child, generates an error, and
    returns one of the values contained in the following table:</dd>

    <dd class="tm">
      <table border="2" cellspacing="0" cellpadding="3">
        <tr bgcolor="#FFFFE0">
          <th align="left" nowrap>Return Value</th>

          <th align="left">Meaning</th>
        </tr>

        <tr>
          <td><code>"EMPTY"</code></td>

          <td>Any entry child (except the one containing the seconds) is
          empty.</td>
        </tr>

        <tr>
          <td><code>"BAD"</code></td>

          <td>The value of the day, month, or hour (the latter only if the
          AM/PM indicator is present) is <code>0</code>.</td>
        </tr>

        <tr>
          <td><code>"BAD_DATE"</code></td>

          <td>The &lt;year, month, day&gt; triple is invalid (note that the
          command is aware of leap years).</td>
        </tr>

        <tr>
          <td><code>"BAD_YEAR"</code></td>

          <td>The above triple is valid, but the conversion (made with the aid
          of the&nbsp; <code><b>clock scan</b></code>&nbsp; command) failed
          because of an unsupported year value (e.g., between <code>38</code>
          and <code>70</code>).</td>
        </tr>
      </table>
    </dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, date, time, clock</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <title>Multi-Entry Widgets for Real Numbers in Fixed-Point Format</title>

  <meta name="Author" content="Csaba Nemethi">
  <meta name="Keywords" content="mentry, widget, real number">

  <link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>

<body>
  <div align="center">
    <h1>Multi-Entry Widgets for Real Numbers<br>
    in Fixed-Point Format</h1>

    <h2>For Mentry Version 3.10</h2>

    <h3>by</h3>

    <h2>Csaba Nemethi</h2>

    <address>
      <a href="mailto:[email protected]">[email protected]</a>
    </address>
  </div>

  <hr>

  <h2 id="contents">Contents</h2>

  <ul>
    <li><a href="#fixedPointMentry">The
    <code><b>mentry::fixedPointMentry</b></code> Command</a></li>

    <li><a href="#putReal">The <code><b>mentry::putReal</b></code>
    Command</a></li>

    <li><a href="#getReal">The <code><b>mentry::getReal</b></code>
    Command</a></li>
  </ul>

  <div align="center">
    <p><a href="index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="fixedPointMentry">The <code><b>mentry::fixedPointMentry</b></code>
  Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::fixedPointMentry</code> &ndash; Create and manipulate
    mentry widgets for real numbers in fixed-point format</dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::fixedPointMentry</b> <i>pathName count1 count2</i> ?<b>-comma</b>? ?<i>options</i>?
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command creates a new mentry widget <code><i>pathName</i></code>
    for displaying and editing real numbers in fixed-point format, with
    <code><i>count1</i></code> characters before and <code><i>count2</i></code>
    digits after the decimal point.&nbsp; Both <code><i>count1</i></code> and
    <code><i>count2</i></code> must be positive integers.&nbsp; The mentry will
    have two entry children, separated by a label displaying a
    <code><b>"."</b></code> character by default; the optional
    <code><b>-comma</b></code> switch changes the label text to
    <code><b>","</b></code>.&nbsp; The supported <code><i>options</i></code>
    are the same as in the case of the <code><b><a href=
    "mentryWidget.html">mentry::mentry</a></b></code> command.</dd>

    <dd class="tm">The command sets the <code><b>type</b></code> attribute of
    the widget to the value <code>"FixedPoint"</code> and returns the name of
    the newly created widget.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="putReal">The <code><b>mentry::putReal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::putReal</code> &ndash; Output a real number to a mentry
    of type <code>"FixedPoint"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::putReal</b> <i>number</i> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command outputs the real number <code><i>number</i></code> to the
    mentry widget <code><i>pathName</i></code>, which must have been created
    with the <code><b><a href=
    "#fixedPointMentry">mentry::fixedPointMentry</a></b></code> command (this
    is checked by examining the widget's <code><b>type</b></code> attribute,
    which must have the value <code>"FixedPoint"</code>).</dd>

    <dd class="tm">The command generates an error if the number does not fit
    into the widget because it has too many characters before the decimal
    point.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>

  <hr>

  <h2 id="getReal">The <code><b>mentry::getReal</b></code> Command</h2>

  <dl>
    <dt><b>NAME</b></dt>

    <dd><code>mentry::getReal</code> &ndash; Get a real number from a mentry of
    type <code>"FixedPoint"</code></dd>

    <dt class="tm"><b>SYNOPSIS</b></dt>

    <dd>
      <pre>
<b>mentry::getReal</b> <i>pathName</i>
</pre>
    </dd>

    <dt><b>DESCRIPTION</b></dt>

    <dd>This command returns the number contained in the mentry widget
    <code><i>pathName</i></code>, which must have been created with the
    <code><b><a href=
    "#fixedPointMentry">mentry::fixedPointMentry</a></b></code> command (this
    is checked by examining the widget's <code><b>type</b></code> attribute,
    which must have the value <code>"FixedPoint"</code>).</dd>

    <dd class="tm">If both entry children of the widget are empty, the command
    sets the focus to the first entry child, generates an error, and returns
    the string <code>"EMPTY"</code>.</dd>

    <dt class="tm"><b>KEYWORDS</b></dt>

    <dd>mentry, widget, real number</dd>
  </dl>

  <div align="center">
    <p><a href="#contents">Contents</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href=
    "index.html">Start page</a></p>
  </div>
</body>
</html>