Pratt 1.5.6

data/pkgs/tile-0.8.2/doc/dialog.n

@@ -0,0 +1,122 @@
+'\"
+'\" Copyright (c) 2005 Joe English
+'\"
+.so man.macros
+.TH dialog n 0.8 tile "Tile Widget Set"
+.SH "NAME"
+ttk::dialog \- create a dialog box
+.SH "SYNOPSIS"
+\fBpackage require ttk::dialog\fR ?\fI0.8\fR?
+.br
+\fBttk::dialog\fR \fIpathname\fR ?\fIoptions...\fR?
+\fBttk::dialog::define\fR \fIdialogType\fR ?\fIoptions...\fR?
+.SH "DESCRIPTION"
+A dialog box is a transient top-level window 
+containing an icon, a short message, an optional, longer, detail message,
+and a row of command buttons.
+When the user presses any of the buttons,
+a callback function is invoked
+and then the dialog is destroyed.
+.PP
+Additional widgets may be added in the dialog \fIclient frame\fR.
+.SH "OPTIONS"
+.OP \-title n/a n/a
+Specifies a string to use as the window manager title.
+.OP \-message n/a n/a
+Specifies the message to display in this dialog.
+.OP \-detail n/a n/a
+Specifies a longer auxiliary message.
+.OP \-command n/a n/a
+Specifies a command prefix to be invoked when the user presses
+one of the command buttons.  
+The symbolic name of the button is passed as an additional argument
+to the command.
+The dialog is dismissed after invoking the command.
+.OP \-parent n/a n/a
+Specifies a toplevel window for which the dialog is transient.
+If omitted, the default is the nearest ancestor toplevel.
+If set to the empty string, the dialog will not be a transient window.
+.OP \-type n/a n/a
+Specifies a built-in or user-defined dialog type.
+See \fBPREDEFINED DIALOG TYPES\fR, below.
+.OP \-icon n/a n/a
+Specifies one of the stock dialog icons,
+\fBinfo\fR, \fBquestion\fR, \fBwarning\fR, \fBerror\fR,
+\fBauth\fR, or \fBbusy\fR.
+If set to the empty string (the default), no icon is displayed.
+.OP \-buttons n/a n/a
+A list of symbolic button names.
+.OP \-labels n/a n/a
+A dictionary mapping symbolic button names to textual labels.
+May be omitted if all the buttons are predefined.
+.OP \-default n/a n/a
+The symbolic name of the default button.
+.OP \-cancel n/a n/a
+The symbolic name of the "cancel" button.
+The cancel button is invoked if the user presses the Escape key
+and when the dialog is closed from the window manager.
+If \fB-cancel\fR is not specified, 
+the dialog ignores window manager close commands (WM_DELETE_WINDOW).
+.SH "WIDGET COMMANDS"
+.TP
+\fBttk::dialog::clientframe \fIdlg\fR
+Returns the widget path of the client frame.
+Other widgets may be added to the client frame.
+The client frame appears between the detail message and the command buttons.
+.SH "PREDEFINED DIALOG TYPES"
+The \fB-type\fR option, if present, specifies default values 
+for other options.  \fBttk::dialog::define \fItype options...\fR
+specifies a new stock dialog \fItype\fR.  
+The following stock dialog types are predefined:
+.CS
+ttk::dialog::define ok \e
+    -icon info -buttons {ok} -default ok
+ttk::dialog::define okcancel \e
+    -icon info -buttons {ok cancel} -default ok -cancel cancel
+ttk::dialog::define yesno \e
+    -icon question -buttons {yes no}
+ttk::dialog::define yesnocancel \e
+    -icon question -buttons {yes no cancel} -cancel cancel
+ttk::dialog::define retrycancel \e
+    -icon question -buttons {retry cancel} -cancel cancel
+.CE
+.SH "STOCK BUTTONS"
+The following ``stock'' symbolic button names have predefined labels:
+\fByes\fR, \fBno\fR, \fBok\fR, \fBcancel\fR, and \fBretry\fR.
+.PP
+It is not necessary to list these in the \fB-labels\fR dictionary.
+.\" .SH "DIFFERENCES FROM MESSAGE BOXES"
+.\" The \fBttk::dialog\fR constructor is similar to
+.\" the Tk library procedure \fBtk_messageBox\fR,
+.\" but with the following notable differences:
+.\" .IP \(bu
+.\" The first argument to \fBttk::dialog\fR is the name of
+.\" the widget to create; \fBtk_messageBox\fR has
+.\" .IP \(bu
+.\" Tile dialog boxes are non-modal by default.
+.\" .IP \(bu
+.\" The \fBtk_messageBox\fR command is blocking:
+.\" it does not return until the user presses one of the command buttons.
+.\" \fBttk::dialog\fR returns immediately after creating the dialog box.
+.SH EXAMPLE
+.CS
+proc saveFileComplete {button} {
+    switch -- $button {
+    	yes { # save file ... }
+	no  { exit }
+	cancel { # no-op }
+    }
+}
+
+ttk::dialog .saveFileDialog \e
+    -title "Save file?" \e
+    -icon question \e
+    -message "Save file before closing?" \e
+    -detail "If you do not save the file, your work will be lost" \e
+    -buttons [list yes no cancel] \e 
+    -labels [list yes "Save file" no "Don't save"] \e
+    -command saveFileComplete \e
+    ;
+.CE
+.SH "SEE ALSO"
+tk_messageBox(n), wm(n), toplevel(n)

data/pkgs/tile-0.8.2/doc/entry.n

@@ -0,0 +1,438 @@
+'\"
+'\" SOURCE: entry.n, r1.12
+'\"
+'\" Copyright (c) 1990-1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1998-2000 Scriptics Corporation.
+'\" Copyright (c) 2004 Joe English
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH entry n 0.4 tile "Tile Widget Set"
+.BS
+.SH NAME
+ttk::entry \- Editable text field widget
+.SH SYNOPSIS
+\fBttk::entry\fR \fIpathName \fR?\fIoptions\fR?
+.SH DESCRIPTION
+.PP
+An \fBentry\fR widget displays a one-line text string and
+allows that string to be edited by the user.
+The value of the string may be linked to a Tcl variable 
+with the \fB-textvariable\fR option.
+Entry widgets support horizontal scrolling with the 
+standard \fB-xscrollcommand\fR option and \fBxview\fR widget command.
+.SO
+\-class	\-cursor	\-style	\-takefocus
+\-xscrollcommand
+.SE
+.SH "WIDGET-SPECIFIC OPTIONS"
+.OP \-exportselection exportSelection ExportSelection
+A boolean value specifying whether or not 
+a selection in the widget should be linked to the X selection.
+If the selection is exported, then selecting in the widget deselects
+the current X selection, selecting outside the widget deselects any
+widget selection, and the widget will respond to selection retrieval
+requests when it has a selection.
+.\" MAYBE: .OP \-font font Font
+.\" MAYBE: .OP \-foreground foreground Foreground
+.\" MAYBE: .OP \-insertbackground insertBackground Foreground
+.\" MAYBE: .OP \-insertwidth insertWidth InsertWidth
+.OP \-invalidcommand invalidCommand InvalidCommand
+A script template to evaluate whenever the \fBvalidateCommand\fR returns 0.
+See \fBVALIDATION\fR below for more information.
+.OP \-justify justify Justify
+Specifies how the text is aligned within the entry widget.
+One of \fBleft\fR, \fBcenter\fR, or \fBright\fR.
+.\" MAYBE: .OP \-selectbackground selectBackground Foreground
+.\" MAYBE: .OP \-selectborderwidth selectBorderWidth BorderWidth
+.\" MAYBE: .OP \-selectforeground selectForeground Background
+.OP \-show show Show
+If this option is specified, then the true contents of the entry
+are not displayed in the window.
+Instead, each character in the entry's value will be displayed as
+the first character in the value of this option, such as ``*''.
+This is useful, for example, if the entry is to be used to enter
+a password.
+If characters in the entry are selected and copied elsewhere, the
+information copied will be what is displayed, not the true contents
+of the entry.
+.OP \-state state State
+Compatibility option; see \fBwidget(n)\fR for details.
+Specifies one of three states for the entry,
+\fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR.
+See \fBWIDGET STATES\fR, below.
+.OP \-textvariable textVariable Variable
+Specifies the name of a variable whose value is linked 
+to the entry widget's contents.
+Whenever the variable changes value, the widget's contents are updated,
+and vice versa.
+.OP \-validate validate Validate
+Specifies the mode in which validation should operate:
+\fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR.
+Default is \fBnone\fR, meaning that validation is disabled.
+See \fBVALIDATION\fR below.
+.OP \-validatecommand validateCommand ValidateCommand
+A script template to evaluate whenever validation is triggered.
+If set to the empty string (the default), validation is disabled.
+The script must return a boolean value.
+See \fBVALIDATION\fR below.
+.OP \-width width Width
+Specifies an integer value indicating the desired width of the entry window,
+in average-size characters of the widget's font.
+.\" Not in tile: If the value is less than or equal to zero, the widget picks a
+.\" Not in tile: size just large enough to hold its current text.
+.BE
+.SH NOTES
+A portion of the entry may be selected as described below.
+If an entry is exporting its selection (see the \fBexportSelection\fR
+option), then it will observe the standard X11 protocols for handling the
+selection;  entry selections are available as type \fBSTRING\fR.
+Entries also observe the standard Tk rules for dealing with the
+input focus.  When an entry has the input focus it displays an
+\fIinsert cursor\fR to indicate where new characters will be
+inserted.
+.PP
+Entries are capable of displaying strings that are too long to
+fit entirely within the widget's window.  In this case, only a
+portion of the string will be displayed;  commands described below
+may be used to change the view in the window.  Entries use
+the standard \fBxScrollCommand\fR mechanism for interacting with
+scrollbars (see the description of the \fBxScrollCommand\fR option
+for details).
+.SH "INDICES"
+Many of the \fBentry\fR widget commands take one or more indices as
+arguments.  An index specifies a particular character in the entry's
+string, in any of the following ways:
+.IP \fInumber\fR
+Specifies the character as a numerical index, where 0 corresponds
+to the first character in the string.
+.IP \fB@\fInumber\fR
+In this form, \fInumber\fR is treated as an x-coordinate in the
+entry's window;  the character spanning that x-coordinate is used.
+For example, ``\fB@0\fR'' indicates the left-most character in the
+window.
+.IP \fBend\fR
+Indicates the character just after the last one in the entry's string.
+This is equivalent to specifying a numerical index equal to the length
+of the entry's string.
+.IP \fBinsert\fR
+Indicates the character adjacent to and immediately following the
+insert cursor.
+.IP \fBsel.first\fR
+Indicates the first character in the selection.  It is an error to
+use this form if the selection isn't in the entry window.
+.IP \fBsel.last\fR
+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
+entry window.
+.LP
+Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR''
+or ``\fBsel.f\fR''.  In general, out-of-range indices are automatically
+rounded to the nearest legal value.
+.SH "WIDGET COMMAND"
+.PP
+The following commands are possible for entry widgets:
+.TP
+\fIpathName \fBbbox \fIindex\fR
+Returns a list of four numbers describing the bounding box of the
+character given by \fIindex\fR.
+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.
+.TP
+\fIpathName \fBcget\fR \fIoption\fR
+Returns the current value of the specified \fIoption\fR.
+See \fIwidget(n)\fR.
+.TP
+\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
+Modify or query widget options.
+See \fIwidget(n)\fR.
+.TP
+\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR?
+Delete one or more elements of the entry.
+\fIFirst\fR is the index of the first character to delete, and
+\fIlast\fR is the index of the character just after the last
+one to delete.
+If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1,
+i.e. a single character is deleted.
+This command returns the empty string.
+.TP
+\fIpathName \fBget\fR
+Returns the entry's string.
+.TP
+\fIpathName \fBicursor \fIindex\fR
+Arrange for the insert cursor to be displayed just before the character
+given by \fIindex\fR.  Returns the empty string.
+.TP
+\fIpathName \fBidentify \fIx y\fR
+Returns the name of the element at position \fIx\fR, \fIy\fR,
+or the empty string if the coordinates are outside the window.
+.TP
+\fIpathName \fBindex\fI index\fR
+Returns the numerical index corresponding to \fIindex\fR.
+.TP
+\fIpathName \fBinsert \fIindex string\fR
+Insert \fIstring\fR just before the character
+indicated by \fIindex\fR.  Returns the empty string.
+.TP
+\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR?
+Test the widget state.
+See \fIwidget(n)\fR.
+.TP
+\fIpathName \fBselection \fIoption arg\fR
+This command is used to adjust the selection within an entry.  It
+has several forms, depending on \fIoption\fR:
+.RS
+.TP
+\fIpathName \fBselection clear\fR
+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 the empty string.
+.TP
+\fIpathName \fBselection present\fR
+Returns 1 if there is are characters selected in the entry,
+0 if nothing is selected.
+.TP
+\fIpathName \fBselection range \fIstart\fR \fIend\fR
+Sets the selection to include the characters starting with
+the one indexed by \fIstart\fR and ending with the one just
+before \fIend\fR.
+If \fIend\fR refers to the same character as \fIstart\fR or an
+earlier one, then the entry's selection is cleared.
+.RE
+.TP
+\fIpathName \fBstate\fR ?\fIstateSpec\fR?
+Modify or query the widget state.
+See \fIwidget(n)\fR.
+.TP
+\fIpathName \fBvalidate\fR
+Force revalidation, independent of the conditions specified 
+by the \fB-validate\fR option.
+Returns 0 if validation fails, 1 if it succeeds.
+Sets or clears the \fBinvalid\fR state accordingly.
+.TP
+\fIpathName \fBxview \fIargs\fR
+This command is used to query and change the horizontal position of the
+text in the widget's window.  It can take any of the following
+forms:
+.RS
+.TP
+\fIpathName \fBxview\fR
+Returns a list containing two elements.
+Each element is a real fraction between 0 and 1; together they describe
+the horizontal span that is visible in the window.
+For example, if the first element is .2 and the second element is .6,
+20% of the entry's text is off-screen to the left, the middle 40% is visible
+in the window, and 40% of the text is off-screen to the right.
+These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR
+option.
+.TP
+\fIpathName \fBxview\fR \fIindex\fR
+Adjusts the view in the window so that the character given by \fIindex\fR
+is displayed at the left edge of the window.
+.TP
+\fIpathName \fBxview moveto\fI fraction\fR
+Adjusts the view in the window so that the character \fIfraction\fR of the
+way through the text appears at the left edge of the window.
+\fIFraction\fR must be a fraction between 0 and 1.
+.TP
+\fIpathName \fBxview scroll \fInumber what\fR
+This command shifts the view in the window left or right according to
+\fInumber\fR and \fIwhat\fR.
+\fINumber\fR must be an integer.
+\fIWhat\fR must be either \fBunits\fR or \fBpages\fR.
+'\" or an abbreviation of one of these, but we don't document that.
+If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by
+\fInumber\fR average-width characters on the display;  if it is
+\fBpages\fR then the view adjusts by \fInumber\fR screenfuls.
+If \fInumber\fR is negative then characters farther to the left
+become visible;  if it is positive then characters farther to the right
+become visible.
+.RE
+.SH VALIDATION
+The \fB-validate\fR, \fB-validatecommand\fR, and \fB-invalidcommand\fR
+options are used to enable entry widget validation.
+.SS "VALIDATION MODES"
+There are two main validation modes: \fIprevalidation\fR,
+in which the \fB-validatecommand\fR is evaluated prior to each edit
+and the return value is used to determine whether to accept 
+or reject the change;
+and \fIrevalidation\fR, in which the \fB-validatecommand\fR is 
+evaluated to determine whether the current value is valid.
+.PP
+The \fB-validate\fR option determines when validation occurs;
+it may be set to any of the following values:
+.IP \fBnone\fR
+Default.  This means validation will only occur when 
+specifically requested by the \fBvalidate\fR widget command.
+.IP \fBkey\fR
+The entry will be prevalidated prior to each edit
+(specifically, whenever the \fBinsert\fR or \fBdelete\fR 
+widget commands are called).
+If prevalidation fails, the edit is rejected.
+.IP \fBfocus\fR
+The entry is revalidated when the entry receives or loses focus.
+.IP \fBfocusin\fR
+The entry is revalidated when the entry receives focus.
+.IP \fBfocusout\fR
+The entry is revalidated when the entry loses focus.
+.IP \fBall\fR
+Validation is performed for all above conditions.
+.PP
+The \fB-invalidcommand\fR is evaluated whenever
+the \fB-validatecommand\fR returns a false value.
+.PP
+The \fB-validatecommand\fR and \fB-invalidcommand\fR
+may modify the entry widget's value
+via the widget \fBinsert\fR or \fBdelete\fR commands,
+or by setting the linked \fB-textvariable\fR.
+If either does so during prevalidation,
+then the edit is rejected 
+regardless of the value returned by the \fB-validatecommand\fR.
+.PP
+If \fB-validatecommand\fR is empty (the default), 
+validation always succeeds.
+.SS "VALIDATION SCRIPT SUBSTITUTIONS"
+It is possible to perform percent substitutions on the 
+\fB-validatecommand\fR and \fBinvalidCommand\fR,
+just as in a \fBbind\fR script.
+The following substitutions are recognized:
+.IP \fB%d\fR
+Type of action: 1 for \fBinsert\fR prevalidation, 
+0 for \fBdelete\fR prevalidation,
+or -1 for revalidation.
+.IP \fB%i\fR
+Index of character string to be inserted/deleted, if any, otherwise -1.
+.IP \fB%P\fR
+In prevalidation, the new value of the entry if the edit is accepted.
+In revalidation, the current value of the entry.
+.IP \fB%s\fR
+The current value of entry prior to editing.
+.IP \fB%S\fR
+The text string being inserted/deleted, if any, {} otherwise.
+.IP \fB%v\fR
+The current value of the \fB-validate\fR option.
+.IP \fB%V\fR
+The validation condition that triggered the callback
+(\fBkey\fR, \fBfocusin\fR, \fBfocusout\fR, or \fBforced\fR).
+.IP \fB%W\fR
+The name of the entry widget.
+.SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION"
+.IP \(bu
+The standard Tk entry widget automatically disables validation
+(by setting \fB-validate\fR to \fBnone\fR)
+if the \fB-validatecommand\fR or \fB-invalidcommand\fR modifies 
+the entry's value.
+The Tile entry widget only disables validation if one
+of the validation scripts raises an error, or if \fB-validatecommand\fR
+does not return a valid boolean value.
+(Thus, it is not necessary to reenable validation after 
+modifying the entry value in a validation script).
+.IP \(bu
+The standard entry widget invokes validation whenever the linked
+\fB-textvariable\fR is modified; the Tile entry widget does not.
+.SH "DEFAULT BINDINGS"
+The entry widget's default bindings enable the following behavior.  
+In the descriptions below, ``word'' refers to a contiguous group
+of letters, digits, or ``_'' characters, or any single character
+other than these.
+.IP \(bu
+Clicking mouse button 1 positions the insert cursor
+just before the character underneath the mouse cursor, sets the
+input focus to this widget, and clears any selection in the widget.
+Dragging with mouse button 1 down strokes out a selection between
+the insert cursor and the character under the mouse.
+.IP \(bu
+Double-clicking with mouse button 1 selects the word under the mouse
+and positions the insert cursor at the end of the word.
+Dragging after a double click strokes out a selection consisting
+of whole words.
+.IP \(bu
+Triple-clicking with mouse button 1 selects all of the text in the
+entry and positions the insert cursor at the end of the line.
+.IP \(bu
+The ends of the selection can be adjusted by dragging with mouse
+button 1 while the Shift key is down.
+If the button is double-clicked before dragging then the selection
+will be adjusted in units of whole words.
+.IP \(bu
+Clicking mouse button 1 with the Control key down will position the
+insert cursor in the entry without affecting the selection.
+.IP \(bu
+If any normal printing characters are typed in an entry, they are
+inserted at the point of the insert cursor.
+.IP \(bu
+The view in the entry can be adjusted by dragging with mouse button 2.
+If mouse button 2 is clicked without moving the mouse, the selection
+is copied into the entry at the position of the mouse cursor.
+.IP \(bu
+If the mouse is dragged out of the entry on the left or right sides
+while button 1 is pressed, the entry will automatically scroll to
+make more text visible (if there is more text off-screen on the side
+where the mouse left the window).
+.IP \(bu
+The Left and Right keys move the insert cursor one character to the
+left or right;  they also clear any selection in the entry.
+If Left or Right is typed with the Shift key down, then the insertion
+cursor moves and the selection is extended to include the new character.
+Control-Left and Control-Right move the insert cursor by words, and
+Control-Shift-Left and Control-Shift-Right move the insert cursor
+by words and also extend the selection.
+Control-b and Control-f behave the same as Left and Right, respectively.
+.IP \(bu
+The Home key and Control-a move the insert cursor to the
+beginning of the entry and clear any selection in the entry.
+Shift-Home moves the insert cursor to the beginning of the entry
+and extends the selection to that point.
+.IP \(bu
+The End key and Control-e move the insert cursor to the
+end of the entry and clear any selection in the entry.
+Shift-End moves the cursor to the end and extends the selection
+to that point.
+.IP \(bu
+Control-/ selects all the text in the entry.
+.IP \(bu
+Control-\e clears any selection in the entry.
+.IP \(bu
+The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>>
+virtual events operate on the selection in the expected manner.
+.IP \(bu
+The Delete key deletes the selection, if there is one in the entry.
+If there is no selection, it deletes the character to the right of
+the insert cursor.
+.IP \(bu
+The BackSpace key and Control-h delete the selection, if there is one
+in the entry.
+If there is no selection, it deletes the character to the left of
+the insert cursor.
+.IP \(bu
+Control-d deletes the character to the right of the insert cursor.
+.IP \(bu
+Control-k deletes all the characters to the right of the insertion
+cursor.
+.SH "WIDGET STATES"
+In the \fBdisabled\fR state, 
+the entry cannot be edited and the text cannot be selected.
+In the \fBreadonly\fR state,
+no insert cursor is displayed and 
+the entry cannot be edited 
+(specifically: the \fBinsert\fR and \fBdelete\fR commands have no effect).
+The \fBdisabled\fR state is the same as \fBreadonly\fR, 
+and in addition text cannot be selected.
+.PP
+Note that changes to the linked \fB-textvariable\fR will 
+still be reflected in the entry, even if it is disabled or readonly.
+.PP
+Typically, the text is "grayed-out" in the \fBdisabled\fR state,
+and a different background is used in the \fBreadonly\fR state. 
+.PP
+The entry widget sets the \fBinvalid\fR state if revalidation fails,
+and clears it whenever validation succeeds.
+.SH KEYWORDS
+entry, widget, text field