diff options
| author | Charles.Forsyth <devnull@localhost> | 2006-12-22 20:52:35 +0000 |
|---|---|---|
| committer | Charles.Forsyth <devnull@localhost> | 2006-12-22 20:52:35 +0000 |
| commit | 46439007cf417cbd9ac8049bb4122c890097a0fa (patch) | |
| tree | 6fdb25e5f3a2b6d5657eb23b35774b631d4d97e4 /man/9 | |
| parent | 37da2899f40661e3e9631e497da8dc59b971cbd0 (diff) | |
20060303-partial
Diffstat (limited to 'man/9')
| -rw-r--r-- | man/9/0intro | 134 | ||||
| -rw-r--r-- | man/9/1copyright | 55 | ||||
| -rw-r--r-- | man/9/INDEX | 34 | ||||
| -rw-r--r-- | man/9/bind | 194 | ||||
| -rw-r--r-- | man/9/button | 133 | ||||
| -rw-r--r-- | man/9/canvas | 1358 | ||||
| -rw-r--r-- | man/9/checkbutton | 193 | ||||
| -rw-r--r-- | man/9/choicebutton | 148 | ||||
| -rw-r--r-- | man/9/cursor | 47 | ||||
| -rw-r--r-- | man/9/destroy | 24 | ||||
| -rw-r--r-- | man/9/entry | 316 | ||||
| -rw-r--r-- | man/9/focus | 21 | ||||
| -rw-r--r-- | man/9/frame | 79 | ||||
| -rw-r--r-- | man/9/grab | 58 | ||||
| -rw-r--r-- | man/9/grid | 332 | ||||
| -rw-r--r-- | man/9/image | 75 | ||||
| -rw-r--r-- | man/9/label | 79 | ||||
| -rw-r--r-- | man/9/listbox | 304 | ||||
| -rw-r--r-- | man/9/lower | 12 | ||||
| -rw-r--r-- | man/9/menu | 461 | ||||
| -rw-r--r-- | man/9/menubutton | 134 | ||||
| -rw-r--r-- | man/9/options | 244 | ||||
| -rw-r--r-- | man/9/pack | 227 | ||||
| -rw-r--r-- | man/9/panel | 121 | ||||
| -rw-r--r-- | man/9/radiobutton | 192 | ||||
| -rw-r--r-- | man/9/raise | 13 | ||||
| -rw-r--r-- | man/9/scale | 198 | ||||
| -rw-r--r-- | man/9/scrollbar | 252 | ||||
| -rw-r--r-- | man/9/see | 37 | ||||
| -rw-r--r-- | man/9/send | 38 | ||||
| -rw-r--r-- | man/9/text | 1188 | ||||
| -rw-r--r-- | man/9/types | 147 | ||||
| -rw-r--r-- | man/9/update | 24 | ||||
| -rw-r--r-- | man/9/variable | 25 |
34 files changed, 6897 insertions, 0 deletions
diff --git a/man/9/0intro b/man/9/0intro new file mode 100644 index 00000000..4b7cd4fd --- /dev/null +++ b/man/9/0intro @@ -0,0 +1,134 @@ +.TH INTRO 9 +.SH NAME +intro \- introduction to Inferno Tk +.SH DESCRIPTION +This section of the manual provides a reference for the Inferno +Tk implementation, +which is accessed by Limbo programs via +.IR tk (2), +and from +.IR sh (1) +via +.IR sh-tk (1). +.PP +The following pages were derived by Vita Nuova from documentation that is +.IP +Copyright © 1990 The Regents of the University of California +.br +Copyright © 1994-1996 Sun Microsystems, Inc. +.br +See +.IR copyright (9) +for the full copyright notice. +.PP +The format of the pages has changed to follow the format of the rest of +this manual, but more important, the content has been changed +(typically in small ways) to reflect the variant of Tk implemented by +Inferno. +.SS Programming Interface +The interface to Inferno Tk is exclusively through the +.IR tk (2) +module; all the Tk commands described in this section of +the manual are excecuted by passing them as strings to the +.B cmd +function in that module. +The Inferno Tk implementation is based on the Tk 4.0 documentation, +but there are many differences, probably the greatest of which is that +there is no associated Tcl implementation, so almost every +Inferno application using Tk will need to have some Limbo code +associated with it (the +.IR sh-tk (1) +shell module can also fulful this rôle). See ``An Overview of Limbo/Tk'' +in Volume 2 for a tutorial-style introduction to the use of Inferno Tk +which summarises the differences from Tk 4.0. +.SS Tk Commands +The command string passed to +.B tk->cmd +may contain one or more Tk commands, separated by semicolons. +A semicolon is not a command separator when it is nested in braces +.RB ( {} ) +or brackets +.RB ( [] ) +or it is escaped by a backslash +.RB ( \e ). +Each command is divided into +.IR words : +sequences of characters separated by one or more +blanks and tabs. +.PP +There is also a `super quote' convention: at any point in the command +string a single quote mark +.RB ( ' ) +means that the entire rest of the string should be treated as one word. +.PP +A word beginning with an opening brace +.RB ( { ) +continues until the balancing closing brace +.RB ( } ) +is reached. The outer brace characters are stripped. A backslash +can be used to escape a brace in this context. Backslash +characters not used to escape braces are left unchanged. +.PP +A word beginning with an opening bracket +.RB ( [ ) +continues until the balancing closing bracket +.RB ( ] ) +is reached. The enclosed string is then evaluated as if it +were a command string, and the resulting value +is used as the contents of the word. +.PP +Single commands are executed in order until they are all done +or an error is encountered. By convention, an error is signaled by a +return value starting with an exclamation mark +.RB ( ! ). +The return value from +.B tk->cmd +is the return value of the first error-producing +command or else the return value of the final single command. +.PP +To execute a single command, the first word is examined. It +must either begin with dot +.RB ( . ) +in which case it must name an existing widget, which will +interpret the rest of the command according to its type, +or one of the following words, each of which is +documented in a manual page of that name in this section: +.EX + +bind focus lower scrollbar +button frame menu see +canvas grab menubutton send +checkbutton grid pack text +cursor image radiobutton update +destroy label raise variable +entry listbox scale +.EE +.SS Widget Options +Each manual page in this section documents the options +that a particular command will accept. A number of options +are common to several of the widgets and are named as +``standard options'' near the beginning of the manual page +for each widget. These options are documented in +.IR options (9). +The types of value required as arguments to options within +Inferno Tk are documented under +.IR types (9). +.SH SEE ALSO +.IR options (9), +.IR types (9), +.IR tk (2), +.IR sh-tk (1), +.IR tkcmd (1), +.IR wmlib (2), +.IR draw-intro (2), +``An Overview of Limbo/Tk'' in Volume 2. +.SH BUGS +The bracket +.RB ( [] ) +command interpretation is not applied consistently throughout +the Inferno Tk commands (notably, the argument to +the +.IR send (9) +command will not interpret this correctly). +Moreover, if the string to be substituted is significantly bigger +than the command it was substituting, then it will be truncated. diff --git a/man/9/1copyright b/man/9/1copyright new file mode 100644 index 00000000..a4087032 --- /dev/null +++ b/man/9/1copyright @@ -0,0 +1,55 @@ +.TH COPYRIGHT 9 +.SH NAME +copyright \- copyright notice for Tk documentation +.SH DESCRIPTION +The following pages were derived by Vita Nuova from documentation that is +.IP +Copyright © 1990 The Regents of the University of California +.br +Copyright © 1994-1996 Sun Microsystems, Inc. +.PP +and was made available on the following terms: +.IP +.ps -1 +.vs -1 +This software is copyrighted by the Regents of the University of +California, Sun Microsystems, Inc., and other parties. The following +terms apply to all files associated with the software unless explicitly +disclaimed in individual files. + +The authors hereby grant permission to use, copy, modify, distribute, +and license this software and its documentation for any purpose, provided +that existing copyright notices are retained in all copies and that this +notice is included verbatim in any distributions. No written agreement, +license, or royalty fee is required for any of the authorized uses. +Modifications to this software may be copyrighted by their authors +and need not follow the licensing terms described here, provided that +the new terms are clearly indicated on the first page of each file where +they apply. + +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE +IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE +NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR +MODIFICATIONS. + +GOVERNMENT USE: If you are acquiring this software on behalf of the +U.S. government, the Government shall have only "Restricted Rights" +in the software and related documentation as defined in the Federal +Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you +are acquiring the software on behalf of the Department of Defense, the +software shall be classified as "Commercial Computer Software" and the +Government shall have only "Restricted Rights" as defined in Clause +252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the +authors grant the U.S. Government and others acting in its behalf +permission to use and distribute the software in accordance with the +terms specified in this license. +.ps +1 +.vs +1 diff --git a/man/9/INDEX b/man/9/INDEX new file mode 100644 index 00000000..1444c3a8 --- /dev/null +++ b/man/9/INDEX @@ -0,0 +1,34 @@ +intro 0intro +1copyright 1copyright +copyright 1copyright +bind bind +button button +canvas canvas +checkbutton checkbutton +choicebutton choicebutton +cursor cursor +destroy destroy +entry entry +focus focus +frame frame +grab grab +grid grid +image image +label label +listbox listbox +lower lower +menu menu +menubutton menubutton +options options +pack pack +panel panel +radiobutton radiobutton +raise raise +scale scale +scrollbar scrollbar +see see +send send +text text +types types +update update +variable variable diff --git a/man/9/bind b/man/9/bind new file mode 100644 index 00000000..103e61a3 --- /dev/null +++ b/man/9/bind @@ -0,0 +1,194 @@ +.TH BIND 9 +.SH NAME +bind \- Arrange for events to invoke Tk scripts +.SH SYNOPSIS +\f5bind\fI tag sequence script\fR +.sp +\f5bind\fI tag sequence \f5+\fIscript\fR +.SH INTRODUCTION +The \f5bind\fR command associates Tk scripts with window events. +If all three arguments are specified, \f5bind\fR will +arrange for \fIscript\fR (a Tk script) to be evaluated whenever +the event(s) given by \fIsequence\fR occur in the window(s) +identified by \fItag\fR. +If \fIscript\fR is prefixed with a ``+'', then it is appended to +any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces +any existing binding. +If \fIscript\fR is an empty string then the current binding for +\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound. +In all of the cases where a \fIscript\fR argument is provided, +\f5bind\fR returns an empty string. +If \fIscript\fR is prefixed with a ``-'', then any existing binding for +\fIsequence\fR, whose script is exactly the same as \fIscript\fR, is removed. +The \fItag\fR argument gives the pathname of the window +to which \fIsequence\fR is bound. +.SH "EVENT PATTERNS" +The \fIsequence\fR argument specifies a sequence of one or more +event patterns, with optional white space between the patterns. Each +event pattern may +take one of two forms. In the simplest case it is a single +printing ASCII character, such as \f5a\fR or \f5[\fR. The character +may not be a space character or the character \f5<\fR. This form of +pattern matches a \f5KeyPress\fR event for the particular +character. The second form of pattern is longer but more general. +It has the following syntax: +.RS +.EX +\f5<\fIevent\f5-\fIevent\f5-\fR...\f5-\fIevent\f5>\fR +.EE +.RE +The following events are accepted: +.TP +.BR Key \ or\ Keypress +This represents the press of the character in the following +.IR event . +If there is no following event, this represents the press of +any key. The key letter may be escaped with a backslash +.RB ( \e ) +to prevent any character (e.g. +.BR > ) +from being treated specially. +.TP +.B Configure +This event occurs whenever the widget is configured +such that its requested size changes. +.TP +.B Control +This represents the press of the character in the following +.I +event +with the Control key pressed. The character may be quoted +as for +.BR Key . +.TP +.BR ButtonPress \ or\ Button +This represents the pressed state of the mouse button given by +the following event, which should be 1, 2, or 3. If there is no +following event, this represents the press of any button. +If the mouse is moved with a button pressed, the +Button event is delivered in combination with a Motion event +so long as the button remains pressed. +.TP +.B ButtonRelease +Like +.BR ButtonPress , +but represents the release of any button. +.TP +.B Motion +Mouse movement. +.TP +.B Double +Any events in the sequence representing button presses must +be double-clicked for the sequence to match. +.TP +.B Map +The event that a toplevel widget is mapped onto the screen. +.TP +.B Unmap +The event that a toplevel widget is unmapped from the screen. +.TP +.B Enter +The event of the mouse entering the widget from outside. +.TP +.B Leave +The event of the mouse leaving the boundaries of the widget. +.TP +.B FocusIn +The event of the widget getting the keyboard focus. +.TP +.B FocusOut +The event of the widget losing the keyboard focus. +.RE +The event sequence can contain any combination of the above +events. They are treated independently, and if any of the +events occur, the sequence matches. You cannot combine +key presses of more than one key. Events will not be combined +on delivery, except that +.B Motion +events may be combined with button presses (possibly doubled). +.TP +.B Destroy +The event of the widget being destroyed. +See +.IR destroy (9) +for details of widget destruction. + +.SH "BINDING SCRIPTS AND SUBSTITUTIONS" +The \fIscript\fR argument to \f5bind\fR is a Tk script, +which will be executed whenever the given event sequence occurs. +If \fIscript\fR contains +any \f5%\fR characters, then the script will not be +executed directly. Instead, a new script will be +generated by replacing each \f5%\fR, and the character following +it, with information from the current event. The replacement +depends on the character following the \f5%\fR, as defined in the +list below. Unless otherwise indicated, the +replacement string is the decimal value of the given field from +the current event. +Some of the substitutions are only valid for +certain types of events; if they are used for other types of events +the value substituted is undefined. +.IP \f5%%\fR 5 +Replaced with a single percent. +.IP \f5%b\fR 5 +The number of the button that was pressed or released. Valid only +for \f5ButtonPress\fR and \f5ButtonRelease\fR events. +.IP \f5%h\fR 5 +For +.B Configure +events, this is +the old requested height of the widget. +.IP \f5%s\fR 5 +For mouse events, this is the logical OR of the mouse buttons; +for keyboard events, it is the decimal value of the pressed character. +.IP \f5%w\fR 5 +For +.B Configure +events, this is the old requested width of the widget. +.IP \f5%x\fR 5 +The x coordinate from the event, relative to the origin +of the toplevel window. Valid only for +.BR Enter , +.BR Leave , +and mouse events. +.IP \f5%y\fR 5 +The y coordinate from the event, relative to the origin +of the toplevel window. Valid only for +.BR Enter , +.BR Leave , +and mouse events. +.IP \f5%A\fR 5 +The ASCII character corresponding to a \f5Key\fP event. +.IP \f5%K\fR 5 +The pressed character for the event, as four hexadecimal digits. +Valid only for \f5Key\fP events. +.IP \f5%W\fR 5 +The path name of the window to which the event was reported (the +\fIwindow\fR field from the event). Valid for all event types. +.IP \f5%X\fR 5 +Same as +.B %x +except that the screen coordinate system is used. +.IP \f5%Y\fR 5 +Same as +.B %y +except that the screen coordinate system is used. +.LP +The replacement string for a %-replacement is formatted as a proper +Tk list element. +This means that it will be surrounded with braces +if it contains spaces, or special characters such as \f5$\fR and +\f5{\fR may be preceded by backslashes. +This guarantees that the string will be passed through the Tk +parser when the binding script is evaluated. +.SH BUGS +The above scheme is not ideal, and will probably be fixed +in the future. +Quoting is a mess - in particular, the quoting provided for the +.B %A +substitution does not work correctly when a quoted character +is re-interpreted by Tk. +.LP +The length of binding scripts is limited to +128 characters. + diff --git a/man/9/button b/man/9/button new file mode 100644 index 00000000..57ba93c7 --- /dev/null +++ b/man/9/button @@ -0,0 +1,133 @@ +.TH BUTTON 9 +.SH NAME +button \- Create and manipulate button widgets +.SH SYNOPSIS +\f5button\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -disabledcolor -justify +-activeforeground -font -relief +-anchor -foreground -takefocus +-background -highlightcolor -text +-bitmap -highlightthickness -underline +-borderwidth -image +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -command \fItkcmd\fP +Specifies a Tk command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. +.TP +.B -height \fIdist\fP +Specifies a desired height for the button. +If this option isn't specified, the button's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.B -state \fIstate\fP +Specifies one of three states for the button: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the button is displayed using the +\f5foreground\fR and \f5background\fR options. The active state is +typically used when the pointer is over the button. In active state +the button is displayed using the \f5activeForeground\fR and +\f5activeBackground\fR options. Disabled state means that the button +should be insensitive: the default bindings will refuse to activate +the widget and will ignore mouse button presses. +In this state the \f5background\fR option determines how the button is +displayed. +.TP +.B -width \fIdist\fP +Specifies a desired width for the button. +If this option isn't specified, the button's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.SH DESCRIPTION +The \f5button\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a button widget. +Additional +options, described above, may be specified on the command line. +to configure aspects of the button such as its colours, font, +text, and initial relief. The \f5button\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A button is a widget that displays a textual string, bitmap or image. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. +It can display itself in either of three different ways, according +to +the \f5state\fR option; +it can be made to appear raised, sunken, or flat. When a user invokes the +button (by pressing mouse button 1 with the cursor over the +button), then the Tk command specified in the \f5-command\fR +option is invoked. +.SH "WIDGET COMMAND" +The \f5button\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for button widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5button\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5button\fR +command. +.TP +\fIpathName \f5invoke\fR +Invoke the Tk command associated with the button, if there is one. +The return value is the return value from the Tk command, or an +empty string if there is no command associated with the button. +This command is ignored if the button's state is \f5disabled\fR. + +.SH "DEFAULT BINDINGS" +Tk automatically creates bindings for buttons that give them +the following default behaviour: +.IP [1] +A button activates whenever the mouse passes over it and deactivates +whenever the mouse leaves the button. +.IP [2] +A button's relief is changed to sunken whenever mouse button 1 is +pressed over the button, and the relief is restored to its original +value when button 1 is later released. +.IP [3] +If mouse button 1 is pressed over a button and later released over +the button, the button is invoked. However, if the mouse is not +over the button when button 1 is released, then no invocation occurs. +.IP [4] +If the +.B Enter +or +.B Space +key is pressed when the button has keyboard focus, +the button is invoked. +.PP +If the button's state is \f5disabled\fR then none of the above +actions occur: the button is completely non-responsive. +.PP +The behaviour of buttons can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR checkbutton (9), +.IR choicebutton (9), +.IR options (9), +.IR radiobutton (9), +.IR types (9) diff --git a/man/9/canvas b/man/9/canvas new file mode 100644 index 00000000..6941cba0 --- /dev/null +++ b/man/9/canvas @@ -0,0 +1,1358 @@ +.TH CANVAS 9 +.SH NAME +canvas \- Create and manipulate canvas widgets +.SH SYNOPSIS +\f5canvas\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-background -selectbackground -takefocus +-borderwidth -selectborderwidth -xscrollcommand +-relief -selectforeground -yscrollcommand +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -closeenough \fIdist\fP +Specifies a floating-point value indicating how close the mouse cursor +must be to an item before it is considered to be ``inside'' the item. +Defaults to 1.0. +.TP +.B -confine \fIboolean\fP +Specifies a boolean value that indicates whether or not it should be +allowable to set the canvas's view outside the region defined by the +\f5scrollRegion\fR argument. +Defaults to true, which means that the view will +be constrained within the scroll region. +.TP +.B -height \fIdist\fP +Specifies a desired window height that the canvas widget should request from +its geometry manager. The value may be specified in any +of the forms described in the COORDINATES section below. +.TP +.B -scrollregion \fIlist\fP +Specifies a list with four \fIdist\fP coordinates describing the left, top, right, and +bottom coordinates of a rectangular region. +This region is used for scrolling purposes and is considered to be +the boundary of the information in the canvas. +Each of the coordinates may be specified +in any of the forms given in the COORDINATES section below. +.TP +.B -width \fIdist\fP +Specifies a desired window width that the canvas widget should request from +its geometry manager. The value may be specified in any +of the forms described in the COORDINATES section below. +.br +.TP +.B -xscrollincrement \fIdist\fP +Specifies an increment for horizontal scrolling, in any of the usual forms +permitted for screen distances. If the value of this option is greater +than zero, the horizontal view in the window will be constrained so that +the canvas x coordinate at the left edge of the window is always an even +multiple of \f5xscrollicrement\fR; furthermore, the units for scrolling +(e.g., the change in view when the left and right arrows of a scrollbar +are selected) will also be \f5xscrollicrement\fR. If the value of +this option is less than or equal to zero, then horizontal scrolling +is unconstrained. +.TP +.B -yscrollincrement \fIdist\fP +Specifies an increment for vertical scrolling, in any of the usual forms +permitted for screen distances. If the value of this option is greater +than zero, the vertical view in the window will be constrained so that +the canvas y coordinate at the top edge of the window is always an even +multiple of \f5yscrollicrement\fR; furthermore, the units for scrolling +(e.g., the change in view when the top and bottom arrows of a scrollbar +are selected) will also be \f5yscrollicrement\fR. If the value of +this option is less than or equal to zero, then vertical scrolling +is unconstrained. +.TP +.B -buffer \fIwhat\fP +Specifies how much of the canvas region will be +backed by an offscreen bitmap buffer. +\fIWhat\fP can be one of \f5all\fP (the entire scroll region +will be buffered), \f5visible\fP (only the visible area), \f5none\fP +(no buffering) or \f5auto\fP (equivalent to either \f5none\fP +or \f5visible\fP depending on whether the canvas is packed inside +another canvas or not). + +.SH INTRODUCTION +The \f5canvas\fR command creates a new window (given +by the \fIpathName\fR argument) and makes it into a canvas widget. +Additional options, described above, may be specified on the +command line +to configure aspects of the canvas such as its colours and 3-D relief. +The \f5canvas\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +Canvas widgets implement structured graphics. +A canvas displays any number of \fIitems\fR, which may be things like +rectangles, circles, lines, and text. +Items may be manipulated (e.g. moved or re-coloured) and commands may +be associated with items in much the same way that the \f5bind\fR +command allows commands to be bound to widgets. For example, +a particular command may be associated with the <Button-1> event +so that the command is invoked whenever button 1 is pressed with +the mouse cursor over an item. +This means that items in a canvas can have behaviours defined by +the Tk scripts bound to them. + +.SH "DISPLAY LIST" +The items in a canvas are ordered for purposes of display, +with the first item in the display list being displayed +first, followed by the next item in the list, and so on. +Items later in the display list obscure those that are +earlier in the display list and are sometimes referred to +as being ``on top'' of earlier items. +When a new item is created it is placed at the end of the +display list, on top of everything else. +Widget commands may be used to re-arrange the order of the +display list. + +.SH "ITEM IDS AND TAGS" +Items in a canvas widget may be named in either of two ways: +by id or by tag. +Each item has a unique identifying number which is assigned to +that item when it is created. The id of an item never changes +and id numbers are never re-used within the lifetime of a +canvas widget. +.PP +Each item may also have any number of \fItags\fR associated +with it. A tag is just a string of characters, and it may +take any form except that of an integer. +For example, ``x123'' is OK but ``123'' isn't. +The same tag may be associated with many different items. +This is commonly done to group items in various interesting +ways; for example, all selected items might be given the +tag ``selected''. +.PP +The tag \f5all\fR is implicitly associated with every item +in the canvas; it may be used to invoke operations on +all the items in the canvas. +.PP +The tag \f5current\fR is managed automatically by Tk; +it applies to the \fIcurrent item\fR, which is the +topmost item whose drawn area covers the position of +the mouse cursor. +If the mouse is not in the canvas widget or is not over +an item, then no item has the \f5current\fR tag. +.PP +When specifying items in canvas widget commands, if the +specifier is an integer then it is assumed to refer to +the single item with that id. +If the specifier is not an integer, then it is assumed to +refer to all of the items in the canvas that have a tag +matching the specifier. +The symbol \fItagOrId\fR is used below to indicate that +an argument specifies either an id that selects a single +item or a tag that selects zero or more items. +Some widget commands only operate on a single item at a +time; if \fItagOrId\fR is specified in a way that +names multiple items, then the normal behaviour is for +the command to use the first (lowest) of these items in +the display list that is suitable for the command. +Exceptions are noted in the widget command descriptions +below. +.SH COORDINATES +All coordinates related to canvases are stored as fixed-point +numbers. +Coordinates and distances are specified as documented +in the +.I dist +section of +.IR types (9). +.SH TRANSFORMATIONS +Normally the origin of the canvas coordinate system is at the +upper-left corner of the window containing the canvas. +It is possible to adjust the origin of the canvas +coordinate system relative to the origin of the window using the +\f5xview\fR and \f5yview\fR widget commands; this is typically used +for scrolling. +Canvases do not support scaling or rotation of the canvas coordinate +system relative to the window coordinate system. +.PP +Individual items may be moved or scaled using widget commands +described below, but they may not be rotated. + +.SH INDICES +Text items support the notion of an \fIindex\fR for identifying +particular positions within the item. +Indices are used for commands such as inserting text, deleting +a range of characters, and setting the insertion cursor position. +An index may be specified in any of a number of ways, and +different types of items may support different forms for +specifying indices. +Text items support the following forms for an index. +Note that it is possible to refer to the character just after +the last one in the text item; this is necessary for such +tasks as inserting new text at the end of the item. +.TP 10 +\fInumber\fR +A decimal number giving the position of the desired character +within the text item. +0 refers to the first character, 1 to the next character, and +so on. +A number less than 0 is treated as if it were zero, and a +number greater than the length of the text item is treated +as if it were equal to the length of the text item. +.TP 10 +\f5end\fR +Refers to the character just after the last one in the item +(same as the number of characters in the item). +.TP 10 +\f5insert\fR +Refers to the character just before which the insertion cursor +is drawn in this item. +.TP 10 +\f5sel.first\fR +Refers to the first selected character in the item. +If the selection isn't in this item then this form is illegal. +.TP 10 +\f5sel.last\fR +Refers to the last selected character in the item. +If the selection isn't in this item then this form is illegal. +.TP 10 +\f5@\fIx,y\fR +Refers to the character at the point given by \fIx\fR and +\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate +system of the canvas. +If \fIx\fR and \fIy\fR lie outside the coordinates covered by the +text item, then they refer to the first or last character in the +line that is closest to the given point. + +.SH "WIDGET COMMAND" +The \f5canvas\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. +The following widget commands are possible for canvas widgets: +.TP +\fIpathName \f5addtag \fItag searchSpec \fR?\fIarg arg ...\fR? +For each item that meets the constraints specified by +\fIsearchSpec\fR and the \fIarg\fRs, add +\fItag\fR to the list of tags associated with the item if it +isn't already present on that list. +It is possible that no items will satisfy the constraints +given by \fIsearchSpec and \fIarg\fRs, in which case the +command has no effect. +This command returns an empty string as result. +\fISearchSpec\fR and \fIarg\fR's may take any of the following +forms: +.RS +.TP +\f5above \fItagOrId\fR +Selects the item just after (above) the one given by \fItagOrId\fR +in the display list. +If \fItagOrId\fR denotes more than one item, then the last (topmost) +of these items in the display list is used. +.TP +\f5all\fR +Selects all the items in the canvas. +.TP +\f5below \fItagOrId\fR +Selects the item just before (below) the one given by \fItagOrId\fR +in the display list. +If \fItagOrId\fR denotes more than one item, then the first (lowest) +of these items in the display list is used. +.TP +\f5closest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR? +Selects the item closest to the point given by \fIx\fR and \fIy\fR. +If more than one item is at the same closest distance (e.g. two +items overlap the point), then the top-most of these items (the +last one in the display list) is used. +If \fIhalo\fR is specified, then it must be a non-negative +value. +Any item closer than \fIhalo\fR to the point is considered to +overlap it. +The \fIstart\fR argument may be used to step circularly through +all the closest items. +If \fIstart\fR is specified, it names an item using a tag or id +(if by tag, it selects the first item in the display list with +the given tag). +Instead of selecting the topmost closest item, this form will +select the topmost closest item that is below \fIstart\fR in +the display list; if no such item exists, then the selection +behaves as if the \fIstart\fR argument had not been specified. +.TP +\f5enclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +Selects all the items completely enclosed within the rectangular +region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. +\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be +no greater than \fIy2\fR. +.TP +\f5overlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR +Selects all the items that overlap or are enclosed within the +rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, +and \fIy2\fR. +\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be +no greater than \fIy2\fR. +.TP +\f5withtag \fItagOrId\fR +Selects all the items given by \fItagOrId\fR. +.RE +.TP +\fIpathName \f5bbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? +Returns a list with four elements giving an approximate bounding box +for all the items named by the \fItagOrId\fR arguments. +The list has the form ``\fIx1 y1 x2 y2\fR'' such that the drawn +areas of all the named elements are within the region bounded by +\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top, +and \fIy2\fR on the bottom. +The return value may overestimate the actual bounding box by +a few pixels. +If no items match any of the \fItagOrId\fR arguments or if the +matching items have empty bounding boxes (i.e. they have nothing +to display) +then an empty string is returned. +.TP +\fIpathName \f5bind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? +This command associates \fIcommand\fR with all the items given by +\fItagOrId\fR such that whenever the event sequence given by +\fIsequence\fR occurs for one of the items the command will +be invoked. +This widget command is similar to the \f5bind\fR command except that +it operates on items in a canvas rather than entire widgets. +See the \f5bind\fR manual entry for complete details +on the syntax of \fIsequence\fR and the substitutions performed +on \fIcommand\fR before invoking it. +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagOrId\fR +(if the first character of \fIcommand\fR is ``+'' then \fIcommand\fR +augments an existing binding rather than replacing it). +In this case the return value is an empty string. +If \fIcommand\fR is omitted then the command returns the \fIcommand\fR +associated with \fItagOrId\fR and \fIsequence\fR (an error occurs +if there is no such binding). +If both \fIcommand\fR and \fIsequence\fR are omitted then the command +returns a list of all the sequences for which bindings have been +defined for \fItagOrId\fR. +.RS +.PP +The only events for which bindings may be specified are those related +to the mouse and keyboard, such as \f5Enter\fR, \f5Leave\fR, +\f5ButtonPress\fR, \f5Motion\fR, and \f5KeyPress\fR. +The handling of events in canvases uses the current item defined +in ITEM IDS AND TAGS above. +\f5Enter\fR and \f5Leave\fR events trigger for an item when it +becomes the current item or ceases to be the current item; note +that these events are different than \f5Enter\fR and \f5Leave\fR +events for windows. +Mouse-related events are directed to the current item, if any. +Keyboard-related events are directed to the focus item, if any +(see the \f5focus\fR widget command below for more on this). +.PP +It is possible for multiple bindings to match a particular event. +This could occur, for example, if one binding is associated with the +item's id and another is associated with one of the item's tags. +When this occurs, all of the matching bindings are invoked. +A binding associated with the \f5all\fR tag is invoked first, +followed by one binding for each of the item's tags (in order), +followed by a binding associated with the item's id. +If there are multiple matching bindings for a single tag, +then only the most specific binding is invoked. +A \f5continue\fR command in a binding script terminates that +script, and a \f5break\fR command terminates that script +and skips any remaining scripts for the event, just as for the +\f5bind\fR command. +.PP +If bindings have been created for a canvas window using the \f5bind\fR +command, then they are invoked in addition to bindings created for +the canvas's items using the \f5bind\fR widget command. +The bindings for items will be invoked before any of the bindings +for the window as a whole. +.RE +.TP +\fIpathName \f5canvasx \fIscreenx\fR ?\fIgridspacing\fR? +Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns +the canvas x-coordinate that is displayed at that location. +If \fIgridspacing\fR is specified, then the canvas coordinate is +rounded to the nearest multiple of \fIgridspacing\fR units. +.TP +\fIpathName \f5canvasy \fIscreeny\fR ?\fIgridspacing\fR? +Given a window y-coordinate in the canvas \fIscreeny\fR this command returns +the canvas y-coordinate that is displayed at that location. +If \fIgridspacing\fR is specified, then the canvas coordinate is +rounded to the nearest multiple of \fIgridspacing\fR units. +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5canvas\fR +command. +.TP +\fIpathName \f5configure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5canvas\fR +command. +.TP +\fIpathName\fR \f5coords \fItagOrId \fR?\fIx0 y0 ...\fR? +Query or modify the coordinates that define an item. +If no coordinates are specified, this command returns a list +whose elements are the coordinates of the item named by +\fItagOrId\fR. +If coordinates are specified, then they replace the current +coordinates for the named item. +If \fItagOrId\fR refers to multiple items, then +the first one in the display list is used. +.TP +\fIpathName \f5create \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? +Create a new item in \fIpathName\fR of type \fItype\fR. +The exact format of the arguments after \f5type\fR depends +on \f5type\fR, but usually they consist of the coordinates for +one or more points, followed by specifications for zero or +more item options. +See the subsections on individual item types below for more +on the syntax of this command. +This command returns the id for the new item. +.TP +\fIpathName \f5dchars \fItagOrId first \fR?\fIlast\fR? +For each item given by \fItagOrId\fR, delete the characters +in the range given by \fIfirst\fR and \fIlast\fR, +inclusive. +If some of the items given by \fItagOrId\fR don't support +text operations, then they are ignored. +\fIFirst\fR and \fIlast\fR are indices of characters +within the item(s) as described in INDICES above. +If \fIlast\fR is omitted, it defaults to \fIfirst\fR. +This command returns an empty string. +.TP +\fIpathName \f5delete \fR?\fItagOrId tagOrId ...\fR? +Delete each of the items given by each \fItagOrId\fR, and return +an empty string. +.TP +\fIpathName \f5dtag \fItagOrId \fR?\fItagToDelete\fR? +For each of the items given by \fItagOrId\fR, delete the +tag given by \fItagToDelete\fR from the list of those +associated with the item. +If an item doesn't have the tag \fItagToDelete\fR then +the item is unaffected by the command. +If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. +This command returns an empty string. +.TP +\fIpathName \f5find \fIsearchCommand \fR?\fIarg arg ...\fR? +This command returns a list consisting of all the items that +meet the constraints specified by \fIsearchCommand\fR and +\fIarg\fR's. +\fISearchCommand\fR and \fIargs\fR have any of the forms +accepted by the \f5addtag\fR command. +If \fIsearchCommand\fR is \f5enclosed\fR, \f5overlapping\fR, +or \f5all\fR, the items are returned in display-list order, +i.e. bottommost first. +.TP +\fIpathName \f5focus \fR?\fItagOrId\fR? +Set the keyboard focus for the canvas widget to the item given by +\fItagOrId\fR. +If \fItagOrId\fR refers to several items, then the focus is set +to the first such item in the display list that supports the +insertion cursor. +If \fItagOrId\fR doesn't refer to any items, or if none of them +support the insertion cursor, then the focus isn't changed. +If \fItagOrId\fR is an empty +string, then the focus item is reset so that no item has the focus. +If \fItagOrId\fR is not specified then the command returns the +id for the item that currently has the focus, or an empty string +if no item has the focus. +.RS +.PP +Once the focus has been set to an item, the item will display +the insertion cursor and all keyboard events will be directed +to that item. +The focus item within a canvas and the focus window on the +screen (set with the \f5focus\fR command) are totally independent: +a given item doesn't actually have the input focus unless (a) +its canvas is the focus window and (b) the item is the focus item +within the canvas. +In most cases it is advisable to follow the \f5focus\fR widget +command with the \f5focus\fR command to set the focus window to +the canvas (if it wasn't there already). +.RE +.TP +\fIpathName \f5gettags\fR \fItagOrId\fR +Return a list whose elements are the tags associated with the +item given by \fItagOrId\fR. +If \fItagOrId\fR refers to more than one item, then the tags +are returned from the first such item in the display list. +If \fItagOrId\fR doesn't refer to any items, then an error is returned. If the item +contains no tags, then an empty string is returned. +.TP +\fIpathName \f5grab\fR \fIwhat\fR \fItagOrId\fR +Does for canvas widgets what \fIgrab\fR(9) does for +normal tk widgets: mouse events will only be delivered +to \fItagOrId\fR. If \fItagOrId\fR refers to more than one item, +then the first such item in the display list is grabbed. +\fIWhat\fR is as described in +.IR grab (9). +.PP +Note that the canvas grab item, as set by this command, +and the tk grab item, as set by +.IR grab (9) +are totally independent; a canvas item doesn't actually grab +the mouse unless a) the canvas itself has grabbed the mouse +or b) the mouse events are being delivered to the canvas as +a matter of course. +.TP +\fIpathName \f5icursor \fItagOrId index\fR +Set the position of the insertion cursor for the item(s) +given by \fItagOrId\fR +to just before the character whose position is given by \fIindex\fR. +If some or all of the items given by \fItagOrId\fR don't support +an insertion cursor then this command has no effect on them. +See INDICES above for a description of the +legal forms for \fIindex\fR. +Note: the insertion cursor is only displayed in an item if +that item currently has the keyboard focus (see the widget +command \f5focus\fR, below), but the cursor position may +be set even when the item doesn't have the focus. +This command returns an empty string. +.TP +\fIpathName \f5index \fItagOrId index\fR +This command returns a decimal string giving the numerical index +within \fItagOrId\fR corresponding to \fIindex\fR. +\fIIndex\fR gives a textual description of the desired position +as described in INDICES above. +The return value is guaranteed to lie between 0 and the number +of characters within the item, inclusive. +If \fItagOrId\fR refers to multiple items, then the index +is processed in the first of these items that supports indexing +operations (in display list order). +.TP +\fIpathName \f5insert \fItagOrId beforeThis string\fR +For each of the items given by \fItagOrId\fR, if the item supports +text insertion then \fIstring\fR is inserted into the item's +text just before the character whose index is \fIbeforeThis\fR. +See INDICES above for information about the forms allowed +for \fIbeforeThis\fR. +This command returns an empty string. +.TP +\fIpathName \f5itemcget\fR \fItagOrId\fR \fIoption\fR +Returns the current value of the configuration option for the +item given by \fItagOrId\fR whose name is \fIoption\fR. +This command is similar to the \f5cget\fR widget command except that +it applies to a particular item rather than the widget as a whole. +\fIOption\fR may have any of the values accepted by the \f5create\fR +widget command when the item was created. +If \fItagOrId\fR is a tag that refers to more than one item, +the first (lowest) such item is used. +.TP +\fIpathName \f5itemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \f5configure\fR widget command except +that it modifies item-specific options for the items given by +\fItagOrId\fR instead of modifying options for the overall +canvas widget. +If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s) in +each of the items given by \fItagOrId\fR; in +this case the command returns an empty string. +The \fIoption\fRs and \fIvalue\fRs are the same as those permissible +in the \f5create\fR widget command when the item(s) were created; +see the sections describing individual item types below for details +on the legal options. +.TP +\fIpathName \f5lower \fItagOrId \fR?\fIbelowThis\fR? +Move all of the items given by \fItagOrId\fR to a new position +in the display list just before the item given by \fIbelowThis\fR. +If \fItagOrId\fR refers to more than one item then all are moved +but the relative order of the moved items will not be changed. +\fIBelowThis\fR is a tag or id; if it refers to more than one +item then the first (lowest) of these items in the display list is used +as the destination location for the moved items. +This command returns an empty string. +.TP +\fIpathName \f5move \fItagOrId xAmount yAmount\fR +Move each of the items given by \fItagOrId\fR in the canvas coordinate +space by adding \fIxAmount\fR to the x-coordinate of each point +associated with the item and \fIyAmount\fR to the y-coordinate of +each point associated with the item. +This command returns an empty string. +.TP +\fIpathName \f5raise \fItagOrId \fR?\fIaboveThis\fR? +Move all of the items given by \fItagOrId\fR to a new position +in the display list just after the item given by \fIaboveThis\fR. +If \fItagOrId\fR refers to more than one item then all are moved +but the relative order of the moved items will not be changed. +\fIAboveThis\fR is a tag or id; if it refers to more than one +item then the last (topmost) of these items in the display list is used +as the destination location for the moved items. +This command returns an empty string. +.TP +\fIpathName \f5scale \fItagOrId xOrigin yOrigin xScale yScale\fR +Rescale all of the items given by \fItagOrId\fR in canvas coordinate +space. +\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling +operation and \fIxScale\fR and \fIyScale\fR identify the scale +factors for x- and y-coordinates, respectively (a scale factor of +1.0 implies no change to that coordinate). +For each of the points defining each item, the x-coordinate is +adjusted to change the distance from \fIxOrigin\fR by a factor +of \fIxScale\fR. +Similarly, each y-coordinate is adjusted to change the distance +from \fIyOrigin\fR by a factor of \fIyScale\fR. +This command returns an empty string. +.TP +\fIpathName \f5screenx \fIcanvasx\fR +Given an x-coordinate \fIcanvasx\fR in the canvas, this command returns +the equivalent screen x-coordinate. +.TP +\fIpathName \f5screeny \fIcanvasy\fR +Given an x-coordinate \fIcanvasy\fR in the canvas, this command returns +the equivalent screen y-coordinate. +.TP +\fIpathName \f5see \fIx1 y1\fR ?\fIx2 y2\fR? +Adjusts the view in the window such that, if possible +the point [\fIx1\fR, \fIy1\fR] (and, if given, the point +[\fIx2\fR, \fIy2\fR]) are made visible. +.TP +\fIpathName \f5select \fIoption\fR ?\fItagOrId arg\fR? +Manipulates the selection in one of several ways, depending on +\fIoption\fR. +The command may take any of the forms described below. +In all of the descriptions below, \fItagOrId\fR must refer to +an item that supports indexing and selection; if it refers to +multiple items then the first of +these that supports indexing and the selection is used. +\fIIndex\fR gives a textual description of a position +within \fItagOrId\fR, as described in INDICES above. +.RS +.TP +\fIpathName \f5select adjust \fItagOrId index\fR +Locate the end of the selection in \fItagOrId\fR nearest +to the character given by \fIindex\fR, and adjust that +end of the selection to be at \fIindex\fR (i.e. including +but not going beyond \fIindex\fR). +The other end of the selection is made the anchor point +for future \f5select to\fR commands. +If the selection isn't currently in \fItagOrId\fR then +this command behaves the same as the \f5select to\fR widget +command. +Returns an empty string. +.TP +\fIpathName \f5select clear\fR +Clear the selection if it is in this widget. +If the selection isn't in this widget then the command +has no effect. +Returns an empty string. +.TP +\fIpathName \f5select from \fItagOrId index\fR +Set the selection anchor point for the widget to be just +before the character +given by \fIindex\fR in the item given by \fItagOrId\fR. +This command doesn't change the selection; it just sets +the fixed end of the selection for future \f5select to\fR +commands. +Returns an empty string. +.TP +\fIpathName \f5select item\fR +Returns the id of the selected item, if the selection is in an +item in this canvas. +If the selection is not in this canvas then an empty string +is returned. +.TP +\fIpathName \f5select to \fItagOrId index\fR +Set the selection to consist of those characters of \fItagOrId\fR +between the selection anchor point and +\fIindex\fR. +The new selection will include the character given by \fIindex\fR; +it will include the character given by the anchor point only if +\fIindex\fR is greater than or equal to the anchor point. +The anchor point is determined by the most recent \f5select adjust\fR +or \f5select from\fR command for this widget. +If the selection anchor point for the widget isn't currently in +\fItagOrId\fR, then it is set to the same character given +by \fIindex\fR. +Returns an empty string. +.RE +.TP +\fIpathName \f5type\fI tagOrId\fR +Returns the type of the item given by \fItagOrId\fR, such as +\f5rectangle\fR or \f5text\fR. +If \fItagOrId\fR refers to more than one item, then the type +of the first item in the display list is returned. +If \fItagOrId\fR doesn't refer to any items at all then +an empty string is returned. +.TP +\fIpathName \f5xview \fR?\fIargs\fR? +This command is used to query and change the horizontal position of the +information displayed in the canvas's window. +It can take any of the following forms: +.RS +.TP +\fIpathName \f5xview\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 canvas's area (as defined by the \f5-scrollregion\fR option) +is off-screen to the left, the middle 40% is visible +in the window, and 40% of the canvas is off-screen to the right. +These are the same values passed to scrollbars via the \f5-xscrollcommand\fR +option. +.TP +\fIpathName \f5xview moveto\fI fraction\fR +Adjusts the view in the window so that \fIfraction\fR of the +total width of the canvas is off-screen to the left. +\fIFraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \f5xview 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 \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts left or right in units +of the \f5xscrollicrement\fR option, if it is greater than zero, +or in units of one-tenth the window's width otherwise. +If \fIwhat is \f5pages\fR then the view +adjusts in units of nine-tenths the window's width. +If \fInumber\fR is negative then information farther to the left +becomes visible; if it is positive then information farther to the right +becomes visible. +.RE +.TP +\fIpathName \f5yview \fI?args\fR? +This command is used to query and change the vertical position of the +information displayed in the canvas's window. +It can take any of the following forms: +.RS +.TP +\fIpathName \f5yview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the vertical span that is visible in the window. +For example, if the first element is .6 and the second element is 1.0, +the lowest 40% of the canvas's area (as defined by the \f5-scrollregion\fR +option) is visible in the window. +These are the same values passed to scrollbars via the \f5-yscrollcommand\fR +option. +.TP +\fIpathName \f5yview moveto\fI fraction\fR +Adjusts the view in the window so that \fIfraction\fR of the canvas's +area is off-screen to the top. +\fIFraction\fR is a fraction between 0 and 1. +.TP +\fIpathName \f5yview scroll \fInumber what\fR +This command adjusts the view in the window up or down according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts up or down in units +of the \f5yscrollicrement\fR option, if it is greater than zero, +or in units of one-tenth the window's height otherwise. +If \fIwhat\fR is \f5pages\fR then +the view adjusts in units of nine-tenths the window's height. +If \fInumber\fR is negative then higher information becomes +visible; if it is positive then lower information +becomes visible. +.RE + +.SH "OVERVIEW OF ITEM TYPES" +The sections below describe the various types of items supported +by canvas widgets. Each item type is characterized by two things: +first, the form of the \f5create\fR command used to create +instances of the type; and second, a set of configuration options +for items of that type, which may be used in the +\f5create\fR and \f5itemconfigure\fR widget commands. +Most items don't support indexing or selection or the commands +related to them, such as \f5index\fR and \f5insert\fR. +Where items do support these facilities, it is noted explicitly +in the descriptions below (at present, only text items provide +this support). + +.SH "ARC ITEMS" +Items of type \f5arc\fR appear on the display as arc-shaped regions. +An arc is a section of an oval delimited by two angles (specified +by the \f5-start\fR and \f5-extent\fR options) and displayed in +one of several ways (specified by the \f5-style\fR option). +Arcs are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give +the coordinates of two diagonally opposite corners of a +rectangular region enclosing the oval that defines the arc. +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for arcs: +.TP +\f5-extent \fIdegrees\fR +Specifies the size of the angular range occupied by the arc. +The arc's range extends for \fIdegrees\fR degrees counter-clockwise +from the starting angle given by the \f5-start\fR option. +\fIDegrees\fR may be negative. +If it is greater than 360 or less than -360, then \fIdegrees\fR +modulo 360 is used as the extent. +.TP +\f5-fill \fIcolour\fR +Fill the region of the arc with \fIcolour\fR. +If \fIcolour\fR is an empty string (the default), then +the arc will not be filled. +.TP +\f5-outline \fIcolour\fR +\fIColour\fR specifies a colour to use for drawing the arc's +outline. +This option defaults to \f5black\fR. If \fIcolour\fR is specified +as an empty string then no outline is drawn for the arc. +.TP +\f5-start \fIdegrees\fR +Specifies the beginning of the angular range occupied by the +arc. +\fIDegrees\fR is given in units of degrees measured counter-clockwise +from the 3-o'clock position; it may be either positive or negative. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the arc should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use. +If the \f5-fill\fR option hasn't been specified then this option +has no effect. +If \fIbitmap\fR is an empty string (the default), then filling is done +in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-style \fItype\fR +Specifies how to draw the arc. If \fItype\fR is \f5pieslice\fR +(the default) then the arc's region is defined by a section +of the oval's perimeter plus two line segments, one between the center +of the oval and each end of the perimeter section. +If \fItype\fR is \f5chord\fR then the arc's region is defined +by a section of the oval's perimeter plus a single line segment +connecting the two end points of the perimeter section. +This type is not implemented at the moment. It behaves as \f5arc\fR. +If \fItype\fR is \f5arc\fR then the arc's region consists of +a section of the perimeter alone. +In this last case the \f5-fill\fR option is ignored. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-width \fIoutlineWidth\fR +Specifies the width of the outline to be drawn around +the arc's region, in any of the forms described in the COORDINATES +section above. +If the \f5-outline\fR option has been specified as an empty string +then this option has no effect. +Wide outlines will be drawn centered on the edges of the arc's region. +This option defaults to 1.0. + +.SH "BITMAP ITEMS" +Items of type \f5bitmap\fR appear on the display as images with +two colours, foreground and background. +Bitmaps are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create bitmap \fIx y \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the bitmap on the display (see the \f5-anchor\fR +option below for more information on how bitmaps are displayed). +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for bitmaps: +.TP +\f5-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the bitmap relative to the +positioning point for the item. For example, if \fIanchorPos\fR +is \f5center\fR then the bitmap is centered on the point; if +\fIanchorPos\fR is \f5n\fR then the bitmap will be drawn so that +its top center point is at the positioning point. +This option defaults to \f5center\fR. +.TP +\f5-bitmap \fIbitmap\fR +Specifies the bitmap to display in the item. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. + +.SH "IMAGE ITEMS" +Items of type \f5image\fR are used to display images on a +canvas. +Images are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create image \fIx y \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the image on the display (see the \f5-anchor\fR +option below for more information). +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for images: +.TP +\f5-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the image relative to the +positioning point for the item. For example, if \fIanchorPos\fR +is \f5center\fR then the image is centered on the point; if +\fIanchorPos\fR is \f5n\fR then the image will be drawn so that +its top center point is at the positioning point. +This option defaults to \f5center\fR. +.TP +\f5-image \fIname\fR +Specifies the name of the image to display in the item. +This image must have been created previously with the +\f5image create\fR command. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item; it may be an empty list. + +.SH "LINE ITEMS" +Items of type \f5line\fR appear on the display as one or more connected +line segments or curves. +Lines are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx1\fR through \fIyn\fR give +the coordinates for a series of two or more points that describe +a series of connected line segments. +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for lines: +.TP +\f5-arrow \fIwhere\fR +Indicates whether or not arrowheads are to be drawn at one or both +ends of the line. +\fIWhere\fR must have one of the values \f5none\fR (for no arrowheads), +\f5first\fR (for an arrowhead at the first point of the line), +\f5last\fR (for an arrowhead at the last point of the line), or +\f5both\fR (for arrowheads at both ends). +This option defaults to \f5none\fR. +.TP +\f5-arrowshape \fIshape\fR +This option indicates how to draw arrowheads. +The \fIshape\fR argument must be a list with three elements, each +specifying a distance in any of the forms described in +the COORDINATES section above. +The first element of the list gives the distance along the line +from the neck of the arrowhead to its tip. +The second element gives the distance along the line from the +trailing points of the arrowhead to the tip, and the third +element gives the distance from the outside edge of the line to the +trailing points. +If this option isn't specified then Tk picks a ``reasonable'' shape. +.TP +\f5-capstyle \fIstyle\fR +Specifies the ways in which caps are to be drawn at the endpoints +of the line. +\fIStyle\fR may one of +\f5butt\fR, \f5projecting\fR, or \f5round\fR. +If this option isn't specified then it defaults to \f5butt\fR. +Where arrowheads are drawn the cap style is ignored. Note that the first two options +currently have the same effect. +.TP +\f5-fill \fIcolour\fR +\fIColour\fR specifies a colour to use for drawing the line. It may also be an +empty string, in which case the line will be transparent. +This option defaults to \f5black\fR. +.TP +\f5-smooth \fIboolean\fR +\fIBoolean\fR indicates whether or not the line should be drawn as a curve. +If so, the line is rendered as a set of Bezier splines: one spline +is drawn for the first and second line segments, one for the second +and third, and so on. Straight-line segments can be generated within +a curve by duplicating the end-points of the desired line segment. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the line should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use. +If \fIbitmap\fR is an empty string (the default), then filling is +done in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-width \fIlineWidth\fR +\fILineWidth\fR specifies the width of the line, in any of the forms +described in the COORDINATES section above. +Wide lines will be drawn centered on the path specified by the +points. +If this option isn't specified then it defaults to 1.0. + +.SH "OVAL ITEMS" +Items of type \f5oval\fR appear as circular or oval regions on +the display. Each oval may have an outline, a fill, or +both. Ovals are created with widget commands of the +following form: +.RS +.EX +\fIpathName \f5create oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give +the coordinates of two diagonally opposite corners of a +rectangular region enclosing the oval. +The oval will include the top and left edges of the rectangle +not the lower or right edges. +If the region is square then the resulting oval is circular; +otherwise it is elongated in shape. +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for ovals: +.TP +\f5-fill \fIcolour\fR +Fill the area of the oval with \fIcolour\fR. +If \fIcolour\fR is an empty string (the default), then +then the oval will not be filled. +.TP +\f5-outline \fIcolour\fR +\fIColour\fR specifies a colour to use for drawing the oval's +outline. +This option defaults to \f5black\fR. +If \fIcolour\fR is an empty string then no outline will be +drawn for the oval. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the oval should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use. +If the \f5-fill\fR option hasn't been specified then this option +has no effect. +If \fIbitmap\fR is an empty string (the default), then filling is done +in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-width \fIoutlineWidth\fR +\fIoutlineWidth\fR specifies the width of the outline to be drawn around +the oval, in any of the forms described in the COORDINATES section above. +If the \f5-outline\fR option hasn't been specified then this option +has no effect. +Wide outlines are drawn centered on the oval path defined by +\fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. +This option defaults to 1.0. + +.SH "POLYGON ITEMS" +Items of type \f5polygon\fR appear as polygonal or curved filled regions +on the display. +Polygons are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx1\fR through \fIyn\fR specify the coordinates for +three or more points that define a closed polygon. +The first and last points may be the same; whether they are or not, +Tk will draw the polygon as a closed polygon. +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for polygons: +.TP +\f5-fill \fIcolour\fR +\fIColour\fR specifies a colour to use for filling the area of the +polygon. +If \fIcolour\fR is an empty string then the polygon will be +transparent. +This option defaults to the empty string (transparent). +.TP +\f5-outline \fIcolour\fR +\fIColour\fR specifies a colour to use for drawing the polygon's +outline. +If \fIcolour\fR is an empty string then no outline will be +drawn for the polygon. +This option defaults to black. +.TP +\f5-smooth \fIboolean\fR +\fIBoolean\fP indicates whether or not the polygon should be drawn with a +curved perimeter. +If so, the outline of the polygon becomes a set of Bezier splines, +one spline for the first and second line segments, one for the second +and third, and so on. Straight-line segments can be generated in a +smoothed polygon by duplicating the end-points of the desired line segment. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the polygon should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use. +If \fIbitmap\fR is an empty string (the default), then filling is +done in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-winding \fItype\fR +Specifies the winding rule to use when filling the polygon. +\fIType\fR can be either \f5nonzero\fR (the default) +or \f5odd\fR +See \f5fillpoly\fR in +.IR draw-image(2) +for an explanation. +.TP +\f5-width \fIoutlineWidth\fR +\fIOutlineWidth\fR specifies the width of the outline to be drawn around +the polygon, in any of the forms described in the COORDINATES section above. +If the \f5-outline\fR option hasn't been specified then this option +has no effect. This option defaults to 1.0. +.PP +Polygon items are different from other items such as rectangles, ovals +and arcs in that interior points are considered to be ``inside'' a +polygon (e.g. for purposes of the \f5find closest\fR and +\f5find overlapping\fR widget commands) even if it is not filled. +For most other item types, an +interior point is considered to be inside the item only if the item +is filled or if it has neither a fill nor an outline. If you would +like an unfilled polygon whose interior points are not considered +to be inside the polygon, use a line item instead. + +.SH "RECTANGLE ITEMS" +Items of type \f5rectangle\fR appear as rectangular regions on +the display. Each rectangle may have an outline, a fill, or +both. Rectangles are created with widget commands of the +following form: +.RS +.EX +\fIpathName \f5create rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give +the coordinates of two diagonally opposite corners of the rectangle +(the rectangle will include its upper and left edges but not +its lower or right edges). +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for rectangles: +.TP +\f5-fill \fIcolour\fR +Fill the area of the rectangle with \fIcolour\fR. +If \fIcolour\fR is an empty string (the default), +then the rectangle will not be filled. +.TP +\f5-outline \fIcolour\fR +Draw an outline around the edge of the rectangle in \fIcolour\fR. +This option defaults to \f5black\fR. +If \fIcolour\fR is an empty string then no outline will be +drawn for the rectangle. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the rectangle should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use. +If the \f5-fill\fR option hasn't been specified then this option +has no effect. +If \fIbitmap\fR is an empty string (the default), then filling +is done in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-width \fIoutlineWidth\fR +\fIOutlineWidth\fR specifies the width of the outline to be drawn around +the rectangle, in any of the forms described in the COORDINATES section above. +If the \f5-outline\fR option hasn't been specified then this option +has no effect. +Wide outlines are drawn centered on the rectangular path +defined by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. +This option defaults to 1.0. + +.SH "TEXT ITEMS" +A text item displays a string of characters on the screen in one +or more lines. +Text items support indexing and selection, along with the +following text-related canvas widget commands: \f5dchars\fR, +\f5focus\fR, \f5icursor\fR, \f5index\fR, \f5insert\fR, +\f5select\fR. +Text items are created with widget commands of the following +form: +.RS +.EX +\fIpathName \f5create text \fIx y \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the text on the display (see the options +below for more information on how text is displayed). +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for text items: +.TP +\f5-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the text relative to the +positioning point for the text. For example, if \fIanchorPos\fR +is \f5center\fR then the text is centered on the point; if +\fIanchorPos\fR is \f5n\fR then the text will be drawn such that +the top center point of the rectangular region occupied by the +text will be at the positioning point. +This option defaults to \f5center\fR. +.TP +\f5-fill \fIcolour\fR +\fIColour\fR specifies a colour to use for filling the text characters. +If this option isn't specified then it defaults to \f5black\fR. +.TP +\f5-font \fIfont\fR +Specifies the font to use for the text item. +If this option isn't specified, it defaults to a system-dependent +font. +.TP +\f5-justify \fIhow\fR +Specifies how to justify the text within its bounding region. +\fIHow\fR must be one of the values \f5left\fR, \f5right\fR, +or \f5center\fR. +This option will only matter if the text is displayed as multiple +lines. +If the option is omitted, it defaults to \f5left\fR. +.TP +\f5-stipple \fIbitmap\fR +Indicates that the text should be drawn in a stippled pattern +rather than solid; +\fIbitmap\fR specifies the stipple pattern to use. +If \fIbitmap\fR is an empty string (the default) then the text +is drawn in a solid fashion. +The results are undefined if \fIbitmap\fR is not +a 1-bit image. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-text \fIstring\fR +\fIString\fR specifies the characters to be displayed in the text item. +Newline characters cause line breaks. +The characters in the item may also be changed with the +\f5insert\fR and \f5delete\fR widget commands. +This option defaults to an empty string. +.TP +\f5-width \fIlineLength\fR +Specifies a maximum line length for the text, in any of the forms +described in the COORDINATES section above. +If this option is zero (the default) the text is broken into +lines only at newline characters. +However, if this option is non-zero then any line that would +be longer than \fIlineLength\fR is broken just before a space +character to make the line shorter than \fIlineLength\fR; the +space character is treated as if it were a newline +character. + +.SH "WINDOW ITEMS" +Items of type \f5window\fR cause a particular window to be displayed +at a given position on the canvas. +Window items are created with widget commands of the following form: +.RS +.EX +\fIpathName \f5create window \fIx y \fR?\fIoption value option value ...\fR? +.EE +.RE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the window on the display (see the \f5-anchor\fR +option below for more information on how bitmaps are displayed). +After the coordinates there may be any number of \fIoption\fR-\fIvalue\fR +pairs, each of which sets one of the configuration options +for the item. These same \fIoption\fR-\fIvalue\fR pairs may be +used in \f5itemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for window items: +.TP +\f5-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the window relative to the +positioning point for the item. For example, if \fIanchorPos\fR +is \f5center\fR then the window is centered on the point; if +\fIanchorPos\fR is \f5n\fR then the window will be drawn so that +its top center point is at the positioning point. +This option defaults to \f5center\fR. +.TP +\f5-height \fIdist\fR +Specifies the height to assign to the item's window. +\fIDist\fR may have any of the +forms described in the COORDINATES section above. +If this option isn't specified, or if it is specified as an empty +string, then the window is given whatever height it requests internally. +.TP +\f5-tags \fItagList\fR +Specifies a set of tags to apply to the item. +\fITagList\fR consists of a list of tag names, which replace any +existing tags for the item. +\fITagList\fR may be an empty list. +.TP +\f5-width \fIdist\fR +Specifies the width to assign to the item's window. +\fIDist\fR may have any of the +forms described in the COORDINATES section above. +If this option isn't specified, or if it is specified as an empty +string, then the window is given whatever width it requests internally. +.TP +\f5-window \fIpathName\fR +Specifies the window to associate with this item. +The window specified by \fIpathName\fR must either be a child of +the canvas widget or a child of some ancestor of the canvas widget. +\fIPathName\fR may not refer to a top-level window. + +.SH BINDINGS +In the current implementation, new canvases are not given any +default behaviour: you'll have to execute explicit Tk commands +to give the canvas its behaviour. + +.SH CREDITS +Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's +\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme +environment and preceded canvases by a year or two. Its simple +mechanisms for placing and animating graphical objects inspired the +functions of canvases. + +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/checkbutton b/man/9/checkbutton new file mode 100644 index 00000000..dfc71001 --- /dev/null +++ b/man/9/checkbutton @@ -0,0 +1,193 @@ +.TH CHECKBUTTON 9 +.SH NAME +checkbutton \- Create and manipulate checkbutton widgets +.SH SYNOPSIS +\f5checkbutton\fI pathname \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -disabledcolor -justify +-activeforeground -font -relief +-anchor -foreground -takefocus +-background -highlightcolor -text +-bitmap -highlightthickness -underline +-borderwidth -image +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -command \fIcommand\fP +Specifies a Tk command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. The button's global variable (\f5-variable\fR option) will +be updated before the command is invoked. +.TP +.B -height \fIdist\fP +Specifies a desired height for the button. +If this option isn't specified, the button's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.B -indicatoron \fIboolean\fP +Specifies whether or not the indicator should be drawn. +If false, the \f5relief\fP option is ignored and the widget's +relief is always \f5sunken\fP if the widget is selected +and \f5raised\fP otherwise. +.TP +.B -offvalue \fIstring\fP +Specifies value to store in the button's associated variable whenever +this button is deselected. Defaults to ``0''. +.TP +.B -onvalue \fIstring\fP +Specifies value to store in the button's associated variable whenever +this button is selected. Defaults to ``1''. +.TP +.B -selectcolor \fIcolour\fP +Specifies a background colour to use when the button is selected. +If \f5indicatoron\fR is true then the colour applies to the indicator. +If \f5indicatoron\fR is false, this colour is used as the background +for the entire widget, in place of \f5background\fR or \f5activebackground\fR, +whenever the widget is selected. +If specified as an empty string then no special colour is used for +displaying when the widget is selected. +.ig +.TP +.B -selectimage \fIimage\fP +Specifies an image to display (in place of the \f5image\fR option) +when the checkbutton is selected. +This option is ignored unless the \f5image\fR option has been +specified. +.. +.TP +.B -state \fIstate\fP +Specifies one of three states for the checkbutton: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the checkbutton is displayed using the +\f5foreground\fR and \f5background\fR options. The active state is +typically used when the pointer is over the checkbutton. In active state +the checkbutton is displayed using the \f5activeforeground\fR and +\f5activebackground\fR options. Disabled state means that the checkbutton +should be insensitive: the default bindings will refuse to activate +the widget and will ignore mouse button presses. +In this state the \f5disabledcolor\fR and +\f5background\fR options determine how the checkbutton is displayed. +.TP +.B -variable \fIstring\fP +Specifies name of global variable to set whenever this button is +selected. Changes in this variable also cause the button to select +or deselect itself. +.TP +.B -width \fIdist\fP +Specifies a desired width for the button. +If this option isn't specified, the button's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.SH DESCRIPTION +The \f5checkbutton\fR command creates a new window (given by the +\fIpathname\fR argument) and makes it into a checkbutton widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the checkbutton such as its colours, font, +text, and initial relief. The \f5checkbutton\fR command returns its +\fIpathname\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathname\fR. +.PP +A checkbutton is a widget +that displays a textual string, bitmap or image +and a square called an \fIindicator\fR. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. +A checkbutton has +all of the behaviour of a simple button, including the +following: it can display itself in either of three different +ways, according to the \f5state\fR option; +it can be made to appear +raised, sunken, or flat; and it invokes +a Tk command whenever mouse button 1 is clicked over the +checkbutton. +.PP +In addition, checkbuttons can be \fIselected\fR. +If a checkbutton is selected then the indicator is normally +drawn with a sunken relief and a special colour, and +a Tk variable associated with the checkbutton is set to the +.B onvalue +(normally 1). +If the checkbutton is not selected, then the indicator is drawn with a +raised relief and no special colour, and the associated variable is +set to the +.B offvalue +(normally 0). +The variable name +may be modified with options on the command line (\f5-variable\fR option). +Configuration options may also be used to modify the way the +indicator is displayed (or whether it is displayed at all). +By default a checkbutton is configured to select and deselect +itself on alternate button clicks. +.SH "WIDGET COMMAND" +The \f5checkbutton\fR command creates a new Tk command whose +name is \fIpathname\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathname option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for checkbutton widgets: +.TP +\fIpathname \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5checkbutton\fR +command. +.TP +\fIpathname \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathname\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5checkbutton\fR +command. +.TP +\fIpathname \f5deselect\fR +Deselects the checkbutton and sets the associated variable to its ``off'' +value. +.TP +\fIpathname \f5invoke\fR +Does just what would have happened if the user invoked the checkbutton +with the mouse: toggle the selection state of the button and invoke +the Tk command associated with the checkbutton, if there is one. +The return value is the return value from the Tk command, or an +empty string if there is no command associated with the checkbutton. +This command is ignored if the checkbutton's state is \f5disabled\fR. +.TP +\fIpathname \f5select\fR +Selects the checkbutton and sets the associated variable to 1. +.TP +\fIpathname \f5toggle\fR +Toggles the selection state of the button, redisplaying it and +modifying its associated variable to reflect the new state. + +.SH BINDINGS +Tk automatically creates bindings for checkbuttons that give them +the following default behaviour: +.IP [1] +A checkbutton activates whenever the mouse passes over it and deactivates +whenever the mouse leaves the checkbutton. +.IP [2] +When mouse button 1 is pressed over a checkbutton it is invoked (its +selection state toggles and the command associated with the button is +invoked, if there is one). +.PP +If the checkbutton's state is \f5disabled\fR then none of the above +actions occur: the checkbutton is completely non-responsive. +.PP +The behaviour of checkbuttons can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR button (9), +.IR choicebutton (9), +.IR options (9), +.IR radiobutton (9), +.IR types (9) diff --git a/man/9/choicebutton b/man/9/choicebutton new file mode 100644 index 00000000..b9702d3b --- /dev/null +++ b/man/9/choicebutton @@ -0,0 +1,148 @@ +.TH CHOICEBUTTON 9 +.SH NAME +choicebutton \- create and manipulate choicebutton widgets +.SH SYNOPSIS +\f5choicebutton\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -borderwidth -relief +-activeforeground -font -text +-anchor -foreground +-background -image +-bitmap -justify +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -command \fIcommand\fP +Specifies a Tk command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. The button's global variable (\f5-variable\fR option) will +be updated before the command is invoked. +.TP +.B -height \fIdist\fP +Specifies a desired height for the button. +If this option isn't specified, the button's desired height is computed +from the size of the highest item in the +.B -values +list. +.TP +.B -selectcolor \fIcolour\fP +Specifies a background colour to use when the button is selected. +If specified as an empty string, no special colour is used for +displaying when the widget is selected. +.TP +.B -values \fIlist\fP +Specifies a list of all the values the choicebutton can choose from. +.TP +.B -variable \fIstring\fP +Specifies name of global variable to set whenever this button is +selected. The variable will be set to the index of the currently +selected item. Changes in this variable also cause the button to +choose the appropriate item (provided it is an integer and within +range). +.TP +.B -width \fIdist\fP +Specifies a desired width for the button. +If this option isn't specified, the button's desired width is computed +from the size of the widest item in the +.B -values +list. +.SH DESCRIPTION +The \f5choicebutton\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a choicebutton widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the choicebutton such as its colours, font, +text, and initial relief. The \f5choicebutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A choicebutton is a widget that displays a textual string, +one of the items given in the +.I list +argument to the +.B -values +option. +When clicked on, the choicebutton displays a menu showing +all the available choices, allowing the user to change +the choice by selecting an item. +In the description below, an +.I index +is a zero-based index into the set of values specified with +the +.B -values +option. +.SH "WIDGET COMMAND" +The \f5choicebutton\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for choicebutton widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5choicebutton\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5choicebutton\fR +command. +.TP +\fIpathName \f5get\fR ?\fIvalue\fR? +Get the index of the first item with +.IR value . +If +.I value +is not given, get the index of the currently selected item. +.TP +\fIpathName \f5set\fR \fIindex\fR +Sets the current item to the +.IR index th +value. +.TP +\fIpathName \f5getvalue\fR ?\fIindex\fR? +Get the value of the +.IR index th +item. If +.I index +is not given, get the value of the currently selected item. +.TP +\fIpathName \f5setvalue\fR \fIvalue\fR +Set the current item to the first item having +.IR value . +If no item has that value, no change is made, +and an error is returned. +.TP +\fIpathName \f5invoke\fR \fIindex\fR +Does just what would have happened if the user invoked the choicebutton +with the mouse and selected the item at +.IR index : +sets the current item to +.I index +and runs +its associated Tk command, if there is one. +The return value is that from invoking the Tk command, or an +empty string if there is no associated command. +.TP +\fIpathName \f5valuecount\fR +Returns the number of values configured in the choicebutton. +.SH SEE ALSO +.IR button (9), +.IR checkbutton (9), +.IR options (9), +.IR radiobutton (9), +.IR types (9) diff --git a/man/9/cursor b/man/9/cursor new file mode 100644 index 00000000..0f8ae601 --- /dev/null +++ b/man/9/cursor @@ -0,0 +1,47 @@ +.TH CURSOR 9 +.SH NAME +cursor \- change the current mouse cursor +.SH SYNOPSIS +.B cursor +?\fIoptions\fP? +.SH INTRODUCTION +.B Cursor +changes the image displayed at the current mouse position. +The following options are supported: +.TP +\f5-image \fIimage\fR +.I Image +gives a name created using the +.IR image (9) +command; the image must conform to the rules +given for +.B Display.cursor +(see +.IR draw-display (2)). +.TP +\f5-bitmap \fIbitmap\fR +Similar to +.B -image +but using the +.I bitmap +syntax (see +.IR types (9)). +.TP +\f5-x \fIdist\fP +The cursor will be drawn +.I dist +to the right of the actual position of the mouse. +.TP +\f5-y \fIdist\fP +The cursor will be drawn +.I dist +below the actual position of the mouse. +.TP +.B -default +Revert the cursor to its default image. +.SH BUGS +A cursor image should have some inherent association with +its hot-spot offset. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/destroy b/man/9/destroy new file mode 100644 index 00000000..caaf5f47 --- /dev/null +++ b/man/9/destroy @@ -0,0 +1,24 @@ +.TH DESTROY 9 +.SH NAME +destroy \- Destroy one or more windows +.SH SYNOPSIS +\f5destroy \fR?\fIwindow window ...\fR? + +.SH DESCRIPTION +This command deletes the windows given by the +\fIwindow\fR arguments, plus all of their descendants. +The \fIwindow\fRs are destroyed in order, and if an error occurs +in destroying a window the command aborts without destroying the +remaining windows. +.PP +The +.B Destroy +event is fired for each window destroyed, including descendants. +.PP +If the window ``.'' is specified, it is unmapped rather than destroyed +and the +.B Destroy +event is not fired on it. +However, all of its decendants are destroyed as normal. +.SH SEE ALSO +.IR bind (9) diff --git a/man/9/entry b/man/9/entry new file mode 100644 index 00000000..2913be53 --- /dev/null +++ b/man/9/entry @@ -0,0 +1,316 @@ +.TH ENTRY 9 +.SH NAME +entry \- Create and manipulate entry widgets +.SH SYNOPSIS +\f5entry\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-background -highlightcolor -selectbackground +-borderwidth -highlightthickness -selectforeground +-font -justify -takefocus +-foreground -relief -xscrollcommand +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -show \fIstring\fP +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. +.TP +.B -state \fIstate\fP +Specifies one of two states for the entry: \f5normal\fR or \f5disabled\fR. +If the entry is disabled then the value may not be changed using widget +commands and no insertion cursor will be displayed, even if the input focus is +in the widget. +.TP +.B -width \fIdist\fP +Specifies an integer value indicating the desired width of the entry window. + +.SH DESCRIPTION +The \f5entry\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into an entry widget. +Additional options, described above, may be specified on the +command line +to configure aspects of the entry such as its colours, font, +and relief. The \f5entry\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +An entry is a widget that displays a one-line text string and +allows that string to be edited using widget commands described below, which +are typically bound to keystrokes and mouse actions. +When first created, an entry's string is empty. +A portion of the entry may be selected as described below. +Entries observe the standard Tk rules for dealing with the +input focus. When an entry has the input focus it displays an +\fIinsertion 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 \f5xscrollcommand\fR mechanism for interacting with +scrollbars (see the description of the \f5xscrollcommand\fR option +for details). + +.SH "WIDGET COMMAND" +The \f5entry\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. +.PP +Many of the widget commands for entries take one or more indices as +arguments. An index specifies a particular character in the entry's +string, in any of the following ways: +.TP 12 +\fInumber\fR +Specifies the character as a numerical index, where 0 corresponds +to the first character in the string. +.TP 12 +\f5anchor\fR +Indicates the anchor point for the selection, which is set with the +\f5select from\fR and \f5select adjust\fR widget commands. +.TP 12 +\f5end\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. +.TP 12 +\f5insert\fR +Indicates the character adjacent to and immediately following the +insertion cursor. +.TP 12 +\f5sel.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. +.TP 12 +\f5sel.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. +.TP 12 +\f5@\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, ``\f5@0\fR'' indicates the left-most character in the +window. +.PP +The following commands are possible for entry widgets: +.TP +\fIpathName \f5bbox \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 \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5entry\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5entry\fR +command. +.TP +\fIpathName \f5delete \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 an empty string. +.TP +\fIpathName \f5get\fR +Returns the entry's string. +.TP +\fIpathName \f5icursor \fIindex\fR +Arrange for the insertion cursor to be displayed just before the character +given by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \f5index\fI index\fR +Returns the numerical index corresponding to \fIindex\fR. +.TP +\fIpathName \f5insert \fIindex string\fR +Insert the characters of \fIstring\fR just before the character +indicated by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \f5see \fIindex\fR +Adjusts the view in the window so that the character given by \fIindex\fR +is completely visible. +.TP +\fIpathName \f5selection \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 \f5selection adjust \fIindex\fR +Locate the end of the selection nearest to the character given by +\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR +(i.e including but not going beyond \fIindex\fR). The other +end of the selection is made the anchor point for future +\f5select to\fR commands. If the selection +isn't currently in the entry, then a new selection is created to +include the characters between \fIindex\fR and the most recent +selection anchor point, inclusive. +Returns an empty string. +.TP +\fIpathName \f5selection 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 an empty string. +.TP +\fIpathName \f5selection from \fIindex\fR +Set the selection anchor point to just before the character +given by \fIindex\fR. Doesn't change the selection. +Returns an empty string. +.TP +\fIpathName \f5selection present\fR +Returns 1 if there are characters selected in the entry, +0 if nothing is selected. +.TP +\fIpathName \f5selection 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. +.TP +\fIpathName \f5selection to \fIindex\fR +If \fIindex\fR is before the anchor point, set the selection +to the characters from \fIindex\fR up to but not including +the anchor point. +If \fIindex\fR is the same as the anchor point, do nothing. +If \fIindex\fR is after the anchor point, set the selection +to the characters from the anchor point up to but not including +\fIindex\fR. +The anchor point is determined by the most recent \f5select from\fR +or \f5select adjust\fR command in this widget. +If the selection isn't in this widget then a new selection is +created using the most recent anchor point specified for the widget. +Returns an empty string. +.RE +.TP +\fIpathName \f5xview \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 \f5xview\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 \f5-xscrollcommand\fR +option. +.TP +\fIpathName \f5xview\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 \f5xview 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 \f5xview 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 \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\f5pages\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 "DEFAULT BINDINGS" +Tk automatically creates bindings for entries that give them +the following default behaviour. +In the descriptions below, ``word'' refers to a contiguous group +of letters, digits, or ``_'' characters, or any single character +other than these. +.IP [1] +Clicking mouse button 1 positions the insertion 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 strokes out a selection between +the insertion cursor and the character under the mouse. +.IP [2] +Double-clicking with mouse button 1 selects the word under the mouse +and positions the insertion cursor at the beginning of the word. +.IP [3] +If any normal printing characters are typed in an entry, the current +selection is deleted, and they are +inserted at the point of the insertion cursor +.IP [4] +The view in the entry can be adjusted by dragging with mouse button 2. +.IP [5] +The Left and Right keys move the insertion cursor one character to the +left or right; they also clear any selection in the entry and set +the selection anchor. +Control-b and Control-f behave the same as Left and Right, respectively. +.IP [6] +The Home key, or Control-a, will move the insertion cursor to the +beginning of the entry and clear any selection in the entry. +.IP [7] +The End key, or Control-e, will move the insertion cursor to the +end of the entry and clear any selection in the entry. +.IP [8] +Control-/ selects all the text in the entry. +.IP [9] +Control-\e clears any selection in the entry. +.IP [10] +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 insertion cursor. +.IP [11] +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 insertion cursor. +.IP [12] +Control-d deletes the character to the right of the insertion cursor. +.IP [13] +Control-k deletes all the characters to the right of the insertion +cursor. +.IP [14] +Control-w deletes the word to the left of the insertion cursor. +.PP +If the entry is disabled using the \f5-state\fR option, then the entry's +view can still be adjusted and text in the entry can still be selected, +but no insertion cursor will be displayed and no text modifications will +take place. +.PP +The behaviour of entries can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/focus b/man/9/focus new file mode 100644 index 00000000..36284864 --- /dev/null +++ b/man/9/focus @@ -0,0 +1,21 @@ +.TH FOCUS 9 +.SH NAME +focus \- change or query keyboard focus +.SH SYNOPSIS +\f5focus \fR?\fIwhat\fR? +.SH DESCRIPTION +With no arguments, \f5focus\fP returns the +name of the widget to which keyboard events +are currently delivered, known as the +.IR "keyboard focus" . +When given an argument, +\f5focus\fP changes the keyboard focus. +If \fIwhat\fP is the name of a widget, that +widget will be made the keyboard focus. +If \fIwhat\fP is \f5next\fP, the keyboard focus +will be changed to the next item in the +focus order for that window. If \fIwhat\fP is +\f5previous\fP, the keyboard focus will be +changed to the previous item in the focus order +for that window. The focus order is determined +automatically by Tk. diff --git a/man/9/frame b/man/9/frame new file mode 100644 index 00000000..fe38e8ce --- /dev/null +++ b/man/9/frame @@ -0,0 +1,79 @@ +.TH FRAME 9 +.SH NAME +frame \- Create and manipulate frame widgets +.SH SYNOPSIS +\f5frame\fI \fIpathName ?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-borderwidth -relief +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -background \fIcolour\fP +This option is the same as the standard \f5background\fR option +except that its value may also be specified as an empty string. +In this case, the widget will display no background or border, and +no colours will be consumed from its colourmap for its background +and border. +.TP +.B -height \fIdist\fP +Specifies the desired height for the window. +If this option is less than or equal to zero then the window will +not request any size at all. +.TP +.B -width \fIdist\fP +Specifies the desired width for the window. +If this option is less than or equal to zero then the window will +not request any size at all. + +.SH DESCRIPTION +The \f5frame\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a frame widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the frame such as its background colour +and relief. The \f5frame\fR command returns the +path name of the new window. +.PP +A frame is a simple widget. Its primary purpose is to act as a +spacer or container for complex window layouts. The only features +of a frame are its background colour and an optional 3-D border to make the +frame appear raised or sunken. + +.SH "WIDGET COMMAND" +The \f5frame\fR command creates a new Tk command whose +name is \fIpathName\fR.. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIPathName\fR is the name of the command, which is the same as +the frame widget's path name. \fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for frame widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5frame\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? \fI?value option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5frame\fR +command. + +.SH BINDINGS +When a new frame is created, it has no default event bindings: +frames are not intended to be interactive. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/grab b/man/9/grab new file mode 100644 index 00000000..fab349fc --- /dev/null +++ b/man/9/grab @@ -0,0 +1,58 @@ +.TH GRAB 9 +.SH NAME +grab \- Confine pointer and keyboard events to a window sub-tree +.SH SYNOPSIS +\f5grab \fIwhat \fR?\fIarg arg \fR...? +.SH DESCRIPTION +This command implements simple pointer grabbing for Tk. +When a grab is set for a particular window, Tk restricts all pointer +events to the grab window and its descendants in Tk's window hierarchy. +Whenever the pointer is within the grab window's subtree, the pointer +will behave exactly the same as if there had been no grab at all +and all events will be reported in the normal fashion. +When the pointer is outside \fIwindow\fR's tree, button presses and +releases and +mouse motion events are reported to \fIwindow\fR, and window entry +and window exit events are ignored. +The grab subtree ``owns'' the pointer: +windows outside the grab subtree will be visible on the screen +but they will be insensitive until the grab is released. +The tree of windows underneath the grab window can include top-level +windows, in which case all of those top-level windows +and their descendants will continue to receive mouse events +during the grab. +.PP +A grab locks out all applications on the screen, +so that only the given subtree of the grabbing application will be +sensitive to pointer events (mouse button presses, mouse button releases, +pointer motions, window entries, and window exits). +During grabs the window manager will not receive pointer +events either (which means that if the grab is not released +the whole GUI will freeze, so be careful!). +.PP +The \f5grab\fR command can take any of the following forms: +.TP +\f5grab release \fIwindow\fR +Releases the grab on \fIwindow\fR if there is one, otherwise does +nothing. Returns an empty string. +.TP +\f5grab set \fIwindow\fR +If a grab was already in effect for this application on +\fIwindow\fR's display then it is automatically released. +If there is already a grab on \fIwindow\fR then the command +does nothing. Returns an empty string. +.TP +\f5grab ifunset \fIwindow\fR +Same as +.B grab set +except that \fIwindow\fR is only grabbed if there is no +other grab currently in effect. +.TP +\f5grab status \fIwindow\fR +Returns \f5none\fR if no grab is currently set on \fIwindow\fR, +or +\fIwindow\fR if it has the grab. +.SH BUGS +The current application-exclusive nature of +.B grab +is a problem which will be adressed in the future. diff --git a/man/9/grid b/man/9/grid new file mode 100644 index 00000000..95b84204 --- /dev/null +++ b/man/9/grid @@ -0,0 +1,332 @@ +.TH GRID 9 +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +grid \- Geometry manager that arranges widgets in a grid +.SH SYNOPSIS +\f5grid \fIoption arg \fR?\fIarg ...\fR? + +.SH DESCRIPTION +.PP +The \f5grid\fR command is used to communicate with the grid +geometry manager that arranges widgets in rows and columns inside +of another window, called the geometry master (or master window). +The \f5grid\fR command can have any of several forms, depending +on the \fIoption\fR argument: +.TP +\f5grid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? +With no arguments, +the bounding box (in pixels) of the grid is returned. +The return value consists of 4 integers. The first two are the pixel +offset from the master window (x then y) of the top-left corner of the +grid, and the second two integers are the bottom-right corner of the grid, +also in pixels. If a single \fIcolumn\fP and \fIrow\fP is specified on +the command line, then the bounding box for that cell is returned, where the +top left cell is numbered from zero. If both \fIcolumn\fP and \fIrow\fP +arguments are specified, then the bounding box spanning the rows and columns +indicated is returned. +.TP +\f5grid cellinfo \fImaster column row\fR +Returns a list giving information about the slave +currently held in the grid cell specified by +\fIcolumn\fP and \fIrow\fP. +The first element of the list is the name of the slave, +and the rest have the same option-value form that +might be specified to \f5grid configure\fR +(the same form as returned by \f5grid info\fR). +.TP +\f5grid columnconfigure \fImaster index \fR?\fI-option value...\fR? +Set the column properties of the \fIindex\fP column of the +geometry master, \fImaster\fP. +The valid options are \f5-minsize\fP, \f5-weight\fP, \f5-pad\fP and \f5-name\fP. +If one or more options are provided, then \fIindex\fP may be given as +a list of column indices to which the configuration options will operate on. +The \f5-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this column. +The \f5-weight\fP option (an integer value) +sets the relative weight for apportioning +any extra spaces among +columns. +A weight of zero (0) indicates the column will not deviate from its requested +size. A column whose weight is two will grow at twice the rate as a column +of weight one when extra space is allocated to the layout. +The \f5-pad\fP option specifies a pad distance that will be +added either side of the column; adjacent columns merge their padding, +creating a pad sized to the larger of the pads on either column. +The \f5-name\fP option associates a name with the column, which can +then be used as an index to refer to that column. +.TP +\f5grid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +The arguments consist of the names of one or more slave windows +followed by pairs of arguments that specify how +to manage the slaves. +The characters \f5-\fP, \f5x\fP and \f5^\fP, +can be specified instead of a window name to alter the default +location of a \fIslave\fP, as described in the ``RELATIVE PLACEMENT'' +section, below. +The following options are supported: +.RS +.TP +\f5-column \fIindex\fR +Insert the slave so that it occupies the \fIindex\fPth column in the grid. +Column numbers start with 0. If this option is not supplied, then the +slave is arranged just to the right of previous slave specified on this +call to \fIgrid\fP, or column "0" if it is the first slave. For each +\f5x\fP that immediately precedes the \fIslave\fP, the column position +is incremented by one. Thus the \f5x\fP represents a blank column +for this row in the grid. +.TP +\f5-columnspan \fIn\fR +Insert the slave so that it occupies \fIn\fP columns in the grid. +The default is one column, unless the window name is followed by a +\f5-\fP, in which case the columnspan is incremented once for each immediately +following \f5-\fP. +.TP +\f5-in \fIother\fR +Insert the slave(s) in the master +window given by \fIother\fR. The default is the first slave's +parent window. +.TP +\f5-ipadx \fIamount\fR +The \fIamount\fR specifies how much horizontal internal padding to +leave on each side of the slave(s). This is space is added +inside the slave(s) border. +The \fIamount\fR must be a valid screen distance, such as \f52\fR or \f5.5c\fR. +It defaults to 0. +.TP +\f5-ipady \fIamount\fR +The \fIamount\fR specifies how much vertical internal padding to +leave on on the top and bottom of the slave(s). +This space is added inside the slave(s) border. +The \fIamount\fR defaults to 0. +.TP +\f5-padx \fIamount\fR +The \fIamount\fR specifies how much horizontal external padding to +leave on each side of the slave(s), in screen units. +The \fIamount\fR defaults to 0. +This space is added outside the slave(s) border. +.TP +\f5-pady \fIamount\fR +The \fIamount\fR specifies how much vertical external padding to +leave on the top and bottom of the slave(s), in screen units. +The \fIamount\fR defaults to 0. +This space is added outside the slave(s) border. +.TP +\f5-row \fIindex\fR +Insert the slave so that it occupies the \fIindex\fPth row in the grid. +Row numbers start with 0. If this option is not supplied, then the +slave is arranged on the same row as the previous slave specified on this +call to \f5grid\fP, or the first unoccupied row if this is the first slave. +.TP +\f5-rowspan \fIn\fR +Insert the slave so that it occupies \fIn\fP rows in the grid. +The default is one row. If the next \f5grid\fP command contains +\f5^\fP characters instead of \fIslaves\fP that line up with the columns +of this \fIslave\fP, then the \f5rowspan\fP of this \fIslave\fP is +extended by one. +.TP +\f5-sticky \fIstyle\fR +If a slave's cell is larger than its requested dimensions, this +option may be used to position (or stretch) the slave within its cell. +\fIStyle\fR is a string that contains zero or more of the characters +\f5n\fP, \f5s\fP, \f5e\fP or \f5w\fP. +The string can optionally contains spaces or +commas, but they are ignored. Each letter refers to a side (north, south, +east, or west) that the slave will "stick" to. If both \f5n\fP and \f5s\fP (or +\f5e\fP and \f5w\fP) are specified, the slave will be stretched to fill the entire +height (or width) of its cavity. The \f5sticky\fP option subsumes the +combination of \f5-anchor\fP and \f5-fill\fP that is used by \f5pack\fP. +The default is \f5{}\fP, which causes the slave to be centered in its cavity, +at its requested size. +.LP +If any of the slaves are already managed by the geometry manager +then any unspecified options for them retain their previous values rather +than receiving default values. +.LP +It is an error if any \fIslave\fP covers an area already covered by an +existing slave of the grid. +.RE +.TP +\f5grid columndelete \fImaster index0 \fR?\fIindex1\fR? +Deletes columns from \fIindex0\fP up to but not including \fIindex1\fP, +If \fIindex1\fP is not given, it defaults to \fIindex0\fP+1. +The deleted columns may not contain cells spanned by +slaves outside the deleted columns. +.TP +\f5grid columnindex \fImaster index\fP +Returns \fIindex\fP as a numerical index into the column. +.TP +\f5grid columninsert \fImaster index \fR?\fIcount\fR? +Inserts \fIcount\fP (default 1) new columns just before \fIindex\fP. +The inserted rows may not split a spanning cell. +.TP +\f5grid forget \fIslave \fR?\fIslave ...\fR? +Removes each of the \fIslave\fRs from grid for its +master and unmaps their windows. +The slaves will no longer be managed by the grid geometry manager. +The configuration options for that window are forgotten, so that if the +slave is managed once more by the grid geometry manager, the initial +default settings are used. +.TP +\f5grid info \fIslave\fR +Returns a list whose elements are the current configuration state of +the slave given by \fIslave\fR in the same option-value form that +might be specified to \f5grid configure\fR. +The first two elements of the list are ``\f5-in \fImaster\fR'' where +\fImaster\fR is the slave's master. +.TP +\f5grid location \fImaster x y\fR +Given \fIx\fP and \fIy\fP values in screen units relative to the master window, +the column and row number at that \fIx\fP and \fIy\fP location is returned. +For locations that are above or to the left of the grid, \f5-1\fP is returned. +.TP +\f5grid propagate \fImaster\fR ?\fIboolean\fR? +If \fIboolean\fR has a true boolean value such as \f51\fR or \f5on\fR +then propagation is enabled for \fImaster\fR, which must be a window +name (see ``GEOMETRY PROPAGATION'' below). +If \fIboolean\fR has a false boolean value then propagation is +disabled for \fImaster\fR. +In either of these cases an empty string is returned. +If \fIboolean\fR is omitted then the command returns \f50\fR or +\f51\fR to indicate whether propagation is currently enabled +for \fImaster\fR. +Propagation is enabled by default. +.TP +\f5grid rowconfigure \fImaster index \fR?\fI-option value...\fR? +Set the row properties of the \fIindex\fP row of the +geometry master, \fImaster\fP. +The valid options are \f5-minsize\fP, \f5-weight\fP, \f5-pad\fP and \f5-name\fP. +If one or more options are provided, then \fIindex\fP may be given as +a list of row indices to which the configuration options will operate on. +The \f5-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this row. +The \f5-weight\fP option (an integer value) +sets the relative weight for apportioning +any extra spaces among +rows. +A weight of zero (0) indicates the row will not deviate from its requested +size. A row whose weight is two will grow at twice the rate as a row +of weight one when extra space is allocated to the layout. +The \f5-pad\fP option specifies a pad distance that will be +added either side of the row; adjacent rows merge their padding, +creating a pad sized to the larger of the pads on either row. +The \f5-name\fP option associates a name with the row, which can +then be used as an index to refer to that row. +.TP +\f5grid rowdelete \fImaster index0 \fR?\fIindex1\fR? +Deletes rows from \fIindex0\fP up to but not including \fIindex1\fP, +If \fIindex1\fP is not given, it defaults to \fIindex0\fP+1. +The deleted rows may not contain cells spanned by +slaves outside the deleted columns. +.TP +\f5grid rowindex \fImaster index\fP +Returns \fIindex\fP as a numerical index into the row. +.TP +\f5grid rowinsert \fImaster index \fR?\fIcount\fR? +Inserts \fIcount\fP (default 1) new rows just before \fIindex\fP. +The inserted rows may not split a spanning cell. +.TP +\f5grid size \fImaster\fR +Returns the size of the grid (in columns then rows) for \fImaster\fP. +The size is determined either by the largest row or column that has +been occupied by a slave, or the largest column or row that has been explicitly +configured. +.TP +\f5grid slaves \fImaster\fR ?\fI-option value\fR? +If no options are supplied, a list of all of the slaves in \fImaster\fR +are returned, most recently manages first. +\fIOption\fP can be either \f5-row\fP or \f5-column\fP which +causes only the slaves in the row (or column) specified by \fIvalue\fP +to be returned. +.SS INDICES +.PP +An index is either a non-negative integer value, the string +\f5end\fP, (one beyond the last index in the row or column in question), +or a name identifying a row or column previously named with +the \f5-name\fP option to \f5rowconfigure\fP or \f5columnconfigure\fP. +.SS "RELATIVE PLACEMENT" +.PP +The \f5grid\fP command contains a limited set of capabilities that +permit layouts to be created without specifying the row and column +information for each slave. This permits slaves to be rearranged, +added, or removed without the need to explicitly specify row and +column information. +When no column or row information is specified for a \fIslave\fP, +default values are chosen for +\f5column\fP, \f5row\fP, \f5columnspan\fP and \f5rowspan\fP +at the time the \fIslave\fP is managed. The values are chosen +based upon the current layout of the grid, the position of the \fIslave\fP +relative to other \fIslave\fPs in the same grid command, and the presence +of the characters \f5-\fP, \f5^\fP, and \f5^\fP in \f5grid\fP +command where \fIslave\fP names are normally expected. +.RS +.TP +\f5-\fP +This increases the columnspan of the \fIslave\fP to the left. Several +\f5-\fP's in a row will successively increase the columnspan. A \f5-\fP +may not follow a \f5^\fP or a \f5x\fP. +.TP +\f5x\fP +This leaves an empty column between the \fIslave\fP on the left and +the \fIslave\fP on the right. +.TP +\f5^\fP +This extends the \f5rowspan\fP of the \fIslave\fP above the \f5^\fP's +in the grid. The number of \f5^\fP's in a row must match the number of +columns spanned by the \fIslave\fP above it. +.RE +.SS "THE GRID ALGORITHM" +.PP +The grid geometry manager lays out its slaves in three steps. +In the first step, the minimum size needed to fit all of the slaves +is computed, then (if propagation is turned on), a request is made +of the master window to become that size. +In the second step, the requested size is compared against the actual size +of the master. If the sizes are different, then spaces is added to or taken +away from the layout as needed. +For the final step, each slave is positioned in its row(s) and column(s) +based on the setting of its \fIsticky\fP flag. +.PP +To compute the minimum size of a layout, the grid geometry manager +first looks at all slaves whose columnspan and rowspan values are one, +and computes the nominal size of each row or column to be either the +\fIminsize\fP for that row or column, or the sum of the \fIpad\fPding +plus the size of the largest slave, whichever is greater. Then the +slaves whose rowspans or columnspans are greater than one are +examined. If a group of rows or columns need to be increased in size +in order to accommodate these slaves, then extra space is added to each +row or column in the group according to its \fIweight\fP. For each +group whose weights are all zero, the additional space is apportioned +equally. +.PP +For masters whose size is larger than the requested layout, the additional +space is apportioned according to the row and column weights. If all of +the weights are zero, the layout is centered within its master. +For masters whose size is smaller than the requested layout, space is taken +away from columns and rows according to their weights. However, once a +column or row shrinks to its minsize, its weight is taken to be zero. +If more space needs to be removed from a layout than would be permitted, as +when all the rows or columns are at their minimum sizes, the layout is +clipped on the bottom and right. +.SS "GEOMETRY PROPAGATION" +.PP +The grid geometry manager normally computes how large a master must be to +just exactly meet the needs of its slaves, and it sets the +requested width and height of the master to these dimensions. +This causes geometry information to propagate up through a +window hierarchy to a top-level window so that the entire +sub-tree sizes itself to fit the needs of the leaf windows. +However, the \f5grid propagate\fR command may be used to +turn off propagation for one or more masters. +If propagation is disabled then grid will not set +the requested width and height of the master window. +This may be useful if, for example, you wish for a master +window to have a fixed size that you specify. +.SS CREDITS +.PP +The \f5grid\fP command is based on ideas taken from the \fIGridBag\fP +geometry manager written by Doug. Stein, and the \f5blt_table\fR geometry +manager, written by George Howlett. +.SH "SEE ALSO" +.IR pack (9), +.IR types (9), +.IR options (9) diff --git a/man/9/image b/man/9/image new file mode 100644 index 00000000..d6603606 --- /dev/null +++ b/man/9/image @@ -0,0 +1,75 @@ +.TH IMAGE 9 +.SH NAME +image \- Create and manipulate images +.SH SYNOPSIS +\f5image\fR \fIoption \fR?\fIarg arg ...\fR? +.SH DESCRIPTION +The \f5image\fR command is used to create, delete, and query images. +It can take several different forms, depending on the +\fIoption\fR argument. The legal forms are: +.TP +\f5image create bitmap \fR?\fIname\fR? ?\fIoption value ...\fR? +Creates a new image and returns its name. +\fIname\fR specifies the name for the image; if it is omitted then +Tk picks a name of the form \f5image\fIx\fR, where \fIx\fR is +an integer. +The following options are supported: +.RS +.TP +\f5-file \fIname\fR +\fIname\fR gives the name of a file whose contents define the +source bitmap. +The file must be in +.IR image (6) +format. +.TP +\f5-maskfile \fIname\fR +\fIname\fR gives the name of a file whose contents define the +mask. The file must be in +.IR image (6) +format. +.RE +.PP +If an image already exists by the given name then it is replaced +with the new image. +.PP +Transparency effects can be achieved by either the source image including an alpha channel +or by specifying a mask image. +If a mask is specified then the resultant image is generated by rendering the source +through the mask onto a transparent destination image. +.PP +The following commands are posible for images: +.TP +\f5image delete \fR?\fIname name\fR ...? +Deletes each of the named images and returns an empty string. +Each image name is invalidated. +If there are instances of the images displayed in widgets, +the images won't actually be deleted until all of the instances +are released. +.TP +\f5image height \fIname\fR +Returns a decimal string giving the height of image \fIname\fR +in pixels. +.TP +\f5image names\fR +Returns a list containing the names of all existing images. +.TP +\f5image type \fIname\fR +Returns ``bitmap'' if +.I name +is an existing image, or an error otherwise. +.TP +\f5image width \fIname\fR +Returns a decimal string giving the width of image \fIname\fR +in pixels. +.SH BUGS +When an image is reconfigured the widgets that refer to it +will continue to render the original image until their +.B -image +option is reconfigured. +.SH SEE ALSO +.IR options (9), +.IR types (9), +.B imageput +in +.IR tk (2), diff --git a/man/9/label b/man/9/label new file mode 100644 index 00000000..f837d8e9 --- /dev/null +++ b/man/9/label @@ -0,0 +1,79 @@ +.TH LABEL 9 +.SH NAME +label \- Create and manipulate label widgets +.SH SYNOPSIS +\f5label\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-anchor -font -justify +-background -foreground -relief +-bitmap -highlightcolor -takefocus +-borderwidth -highlightthickness -text +-disabledcolor -image -underline +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -height \fIdist\fP +Specifies a desired height for the label. +If this option isn't specified, the label's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.B -width \fIdist\fP +Specifies a desired width for the label. +If this option isn't specified, the label's desired width is computed +from the size of the image or bitmap or text being displayed in it. + +.SH DESCRIPTION +The \f5label\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a label widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the label such as its colours, font, +text, and initial relief. The \f5label\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A label is a widget that displays a textual string, bitmap or image. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. +The label can be manipulated in a few simple ways, such as +changing its relief or text, using the commands described below. + +.SH "WIDGET COMMAND" +The \f5label\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for label widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5label\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5label\fR +command. + +.SH BINDINGS +When a new label is created, it has no default event bindings: +labels are not intended to be interactive. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/listbox b/man/9/listbox new file mode 100644 index 00000000..5c1e1b30 --- /dev/null +++ b/man/9/listbox @@ -0,0 +1,304 @@ +.TH LISTBOX 9 +.SH NAME +listbox \- Create and manipulate listbox widgets +.SH SYNOPSIS +\f5listbox\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-background -highlightcolor -selectforeground +-borderwidth -highlightthickness -takefocus +-font -relief -width +-foreground -selectbackground -xscrollcommand +-height -selectborderwidth -yscrollcommand +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -height \fIdist\fP +Specifies the desired height for the window. +.TP +.B -selectmode \fIval\fP +Specifies one of several styles for manipulating the selection. +The value of the option may be arbitrary, but the default bindings +expect it to be either \f5single\fR, \f5browse\fR, \f5multiple\fR, +or \f5extended\fR; the default value is \f5single\fR. +.TP +.B -width \fIdist\fP +Specifies the desired width for the window. +.SH DESCRIPTION +The \f5listbox\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a listbox widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the listbox such as its colours, font, +text, and relief. The \f5listbox\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A listbox is a widget that displays a list of strings, one per line. +When first created, a new listbox has no elements. +Elements may be added or deleted using widget commands described +below. In addition, one or more elements may be selected as described +below. +.PP +It is not necessary for all the elements to be +displayed in the listbox window at once; commands described below +may be used to change the view in the window. Listboxes allow +scrolling in both directions using the standard \f5-xscrollcommand\fR +and \f5-yscrollcommand\fR options. +.SH INDICES +Many of the widget commands for listboxes take one or more indices +as arguments. +An index specifies a particular element of the listbox, in any of +the following ways: +.TP 12 +\fInumber\fR +Specifies the element as a numerical index, where 0 corresponds +to the first element in the listbox. +.TP 12 +\f5active\fR +Indicates the element that has the location cursor. This element +will be displayed with a highlight rectangle when the listbox has the +keyboard focus, and it is specified with the \f5activate\fR +widget command. +.TP 12 +\f5anchor\fR +Indicates the anchor point for the selection, which is set with the +\f5selection anchor\fR widget command. +.TP 12 +\f5end\fR +Indicates the end of the listbox. +For some commands this means just after the last element; +for other commands it means the last element. +.TP 12 +\f5@\fIx\f5,\fIy\fR +Indicates the element that covers the point in the listbox window +specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no +element covers that point, then the closest element to that +point is used. +.LP +In the widget command descriptions below, arguments named \fIindex\fR, +\fIfirst\fR, and \fIlast\fR always contain text indices in one of +the above forms. + +.SH "WIDGET COMMAND" +The \f5listbox\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for listbox widgets: +.TP +\fIpathName \f5activate\fR \fIindex\fR +Sets the active element to the one indicated by \fIindex\fR. +The active element is drawn with an underline when the widget +has the input focus, and its index may be retrieved with the +index \f5active\fR. +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5listbox\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5listbox\fR +command. +.TP +\fIpathName \f5curselection\fR +Returns a list containing the numerical indices of +all of the elements in the listbox that are currently selected. +If there are no elements selected in the listbox then an empty +string is returned. +.TP +\fIpathName \f5delete \fIfirst \fR?\fIlast\fR? +Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR +are indices specifying the first and last elements in the range +to delete. If \fIlast\fR isn't specified it defaults to +\fIfirst\fR, i.e. a single element is deleted. +.TP +\fIpathName \f5get \fIfirst\fR ?\fIlast\fR? +If \fIlast\fR is omitted, returns the contents of the listbox +element indicated by \fIfirst\fR. +If \fIlast\fR is specified, the command returns a list whose elements +are all of the listbox elements between \fIfirst\fR and \fIlast\fR, +inclusive. +Both \fIfirst\fR and \fIlast\fR may have any of the standard +forms for indices. +.TP +\fIpathName \f5index \fIindex\fR +Returns a decimal string giving the integer index value that +corresponds to \fIindex\fR. +.TP +\fIpathName \f5insert \fIindex \fR?\fIelement element ...\fR? +Inserts zero or more new elements in the list just before the +element given by \fIindex\fR. If \fIindex\fR is specified as +\f5end\fR then the new elements are added to the end of the +list. Returns an empty string. +.TP +\fIpathName \f5nearest \fIy\fR +Given a y-coordinate within the listbox window, this command returns +the index of the (visible) listbox element nearest to that y-coordinate. +.TP +\fIpathName \f5see \fIindex\fR +Adjust the view in the listbox so that the element given by \fIindex\fR +is visible. +If the element is already visible then the command has no effect; +if the element is near one edge of the window then the listbox +scrolls to bring the element into view at the edge; otherwise +the listbox scrolls to center the element. +.TP +\fIpathName \f5selection \fIoption arg\fR +This command is used to adjust the selection within a listbox. It +has several forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \f5selection anchor \fIindex\fR +Sets the selection anchor to the element given by \fIindex\fR. +The selection anchor is the end of the selection that is fixed +while dragging out a selection with the mouse. +The index \f5anchor\fR may be used to refer to the anchor +element. +.TP +\fIpathName \f5selection clear \fIfirst \fR?\fIlast\fR? +If any of the elements between \fIfirst\fR and \fIlast\fR +(inclusive) are selected, they are deselected. +The selection state is not changed for elements outside +this range. +.TP +\fIpathName \f5selection includes \fIindex\fR +Returns 1 if the element indicated by \fIindex\fR is currently +selected, 0 if it isn't. +.TP +\fIpathName \f5selection set \fIfirst \fR?\fIlast\fR? +Selects all of the elements in the range between +\fIfirst\fR and \fIlast\fR, inclusive, without affecting +the selection state of elements outside that range. +.RE +.TP +\fIpathName \f5size\fR +Returns a decimal string indicating the total number of elements +in the listbox. +.TP +\fIpathName \f5xview \fIargs\fR +This command is used to query and change the horizontal position of the +information in the widget's window. It can take any of the following +forms: +.RS +.TP +\fIpathName \f5xview\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 listbox'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 \f5-xscrollcommand\fR +option. +.TP +\fIpathName \f5xview\fR \fIindex\fR +Adjusts the view in the window so that the character position given by +\fIindex\fR is displayed at the left edge of the window. +Character positions are defined by the width of the character \f50\fR. +.TP +\fIpathName \f5xview moveto\fI fraction\fR +Adjusts the view in the window so that \fIfraction\fR of the +total width of the listbox text is off-screen to the left. +\fIfraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \f5xview 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 \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts left or right by +\fInumber\fR character units (the width of the \f50\fR character) +on the display; if it is \f5pages\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 +.TP +\fIpathName \f5yview \fI?args\fR? +This command is used to query and change the vertical position of the +text in the widget's window. +It can take any of the following forms: +.RS +.TP +\fIpathName \f5yview\fR +Returns a list containing two elements, both of which are real fractions +between 0 and 1. +The first element gives the position of the listbox element at the +top of the window, relative to the listbox as a whole (0.5 means +it is halfway through the listbox, for example). +The second element gives the position of the listbox element just after +the last one in the window, relative to the listbox as a whole. +These are the same values passed to scrollbars via the \f5-yscrollcommand\fR +option. +.TP +\fIpathName \f5yview\fR \fIindex\fR +Adjusts the view in the window so that the element given by +\fIindex\fR is displayed at the top of the window. +.TP +\fIpathName \f5yview moveto\fI fraction\fR +Adjusts the view in the window so that the element given by \fIfraction\fR +appears at the top of the window. +\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first +element in the listbox, 0.33 indicates the element one-third the +way through the listbox, and so on. +.TP +\fIpathName \f5yview scroll \fInumber what\fR +This command adjusts the view in the window up or down according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts up or down by +\fInumber\fR lines; if it is \f5pages\fR then +the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then earlier elements +become visible; if it is positive then later elements +become visible. +.RE +.SH "DEFAULT BINDINGS" +If the selection mode is \f5single\fR or \f5browse\fR, at most one +element can be selected in the listbox at once. +In both modes, clicking button 1 on an element selects +it and deselects any other selected item. +In \f5browse\fR mode it is also possible to drag the selection +with button 1. +.PP +If the selection mode is \f5multiple\fR or \f5extended\fR, +any number of elements may be selected at once, including discontiguous +ranges. In \f5multiple\fR mode, clicking button 1 on an element +toggles its selection state without affecting any other elements. +In \f5extended\fR mode, pressing button 1 on an element selects +it, deselects everything else, and sets the anchor to the element +under the mouse; dragging the mouse with button 1 +down extends the selection to include all the elements between +the anchor and the element under the mouse, inclusive. +.PP +Most people will probably want to use \f5browse\fR mode for +single selections and \f5extended\fR mode for multiple selections; +the other modes appear to be useful only in special situations. +.PP +The behaviour of listboxes can be changed by defining new bindings for +individual widgets. The default bindings do a grab set when button 1 is pressed +and a grab release when button 1 is released. Care must be taken when overriding +either or both of these defaults to ensure that grabbing is consistent. +.SH BUGS +At least one entry is required for the widget to indicate that it has keyboard focus. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/lower b/man/9/lower new file mode 100644 index 00000000..5c066b3f --- /dev/null +++ b/man/9/lower @@ -0,0 +1,12 @@ +.TH LOWER 9 +.SH NAME +lower \- Change a window's position in the stacking order +.SH SYNOPSIS +\f5lower \fIwindow +.SH DESCRIPTION +\f5Lower\fR lowers +\fIwindow\fR so that it is below all of its siblings in the stacking +order (it will be obscured by any siblings that overlap it and +will not obscure any siblings). +.SH "SEE ALSO" +.IR raise (9) diff --git a/man/9/menu b/man/9/menu new file mode 100644 index 00000000..3a69b85d --- /dev/null +++ b/man/9/menu @@ -0,0 +1,461 @@ +.TH MENU 9 +.SH NAME +menu \- Create and manipulate menu widgets +.SH SYNOPSIS +\f5menu\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -borderwidth -foreground +-activeforeground -disabledcolor -relief +-background -font +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -postcommand \fIcommand\fP +If this option is specified then it provides a Tk command to execute +each time the menu is posted. The command is invoked by the \f5post\fR +widget command before posting the menu. +.TP +.B -selectcolor \fIcolour\fP +For menu entries that are check buttons or radio buttons, this option +specifies the colour to display in the indicator when the check button +or radio button is selected. +.SH INTRODUCTION +The \f5menu\fR command creates a new top-level window (given +by the \fIpathName\fR argument) and makes it into a menu widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the menu such as its colours and font. +The \f5menu\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A menu is a widget that displays a collection of one-line entries arranged +in a column. There exist several different types of entries, +each with different properties. Entries of different types may be +combined in a single menu. Menu entries are not the same as +entry widgets. In fact, menu entries are not even distinct widgets; +the entire menu is one widget. +.PP +Menu entries are displayed with up to three separate fields. +The main field is a label in the form of a text string, +a bitmap, or an image, controlled by the \f5-label\fR, +\f5-bitmap\fR, and \f5-image\fR options for the entry. +The second field is a marker for cascade entries, +showing that the entry will post a cascade menu. +It is displayed at the right-hand edge of the entry. +The third field is an \fIindicator\fR. The indicator is present only for +checkbutton or radiobutton entries. It indicates whether the entry +is selected or not, and is displayed to the left of the entry's +string. +.PP +In normal use, an entry becomes active (displays itself differently) +whenever the mouse pointer is over the entry. If a mouse +button is released over the entry then the entry is \fIinvoked\fR. +The effect of invocation is different for each type of entry; +these effects are described below in the sections on individual +entries. +.PP +Entries may be \fIdisabled\fR, which causes their labels +and accelerators to be displayed +with dimmer colours. +The default menu bindings will not allow +a disabled entry to be activated or invoked. +Disabled entries may be re-enabled, at which point it becomes +possible to activate and invoke them again. + +.SH "COMMAND ENTRIES" +The most common kind of menu entry is a command entry, which +behaves much like a button widget. When a command entry is +invoked, a Tk command is executed. The Tk +command is specified with the \f5-command\fR option. + +.SH "SEPARATOR ENTRIES" +A separator is an entry that is displayed as a horizontal dividing +line. A separator may not be activated or invoked, and it has +no behaviour other than its display appearance. + +.SH "CHECKBUTTON ENTRIES" +A checkbutton menu entry behaves much like a checkbutton widget. +When it is invoked it toggles back and forth between the selected +and deselected states. When the entry is selected, the value +``1'' is stored in a particular global variable (as determined by +\f5-variable\fR option for the entry); when +the entry is deselected the value ``0'' is stored in the global variable. +An indicator box is displayed to the left of the label in a checkbutton +entry. If the entry is selected then the indicator's center is displayed +in the colour given by the \f5-selectcolor\fR option for the entry; +otherwise the indicator's center is displayed in the background colour for +the menu. If a \f5-command\fR option is specified for a checkbutton +entry, then its value is evaluated as a Tk command each time the entry +is invoked; this happens after toggling the entry's +selected state. + +.SH "RADIOBUTTON ENTRIES" +A radiobutton menu entry behaves much like a radiobutton widget. +Radiobutton entries are organized in groups of which only one +entry may be selected at a time. Whenever a particular entry +becomes selected it stores a particular value into a particular +global variable (as determined by the \f5-value\fR and +\f5-variable\fR options for the entry). This action +causes any previously-selected entry in the same group +to deselect itself. +Once an entry has become selected, any change to the entry's +associated variable will cause the entry to deselect itself. +Grouping of radiobutton entries is determined by their +associated variables: if two entries have the same associated +variable then they are in the same group. +An indicator diamond is displayed to the left of the label in each +radiobutton entry. If the entry is selected then the indicator's +center is displayed in the colour given by the \f5-selectcolor\fR option +for the entry; +otherwise the indicator's center is displayed in the background colour for +the menu. If a \f5-command\fR option is specified for a radiobutton +entry, then its value is evaluated as a Tk command each time the entry +is invoked; this happens after selecting the entry. + +.SH "CASCADE ENTRIES" +A cascade entry is one with an associated menu (determined +by the \f5-menu\fR option). Cascade entries allow the construction +of cascading menus. +The \f5postcascade\fR widget command can be used to post and unpost +the associated menu just to the right of the cascade entry. +The associated menu must be a child of the menu containing +the cascade entry (this is needed in order for menu traversal to +work correctly). +.PP +A cascade entry posts its associated menu by invoking a +Tk command of the form +.RS +.EX +\fImenu\f5 post \fIx y\fR +.EE +.RE +where \fImenu\fR is the path name of the associated menu, and \fIx\fR +and \fIy\fR are the screen coordinates of the upper-right +corner of the cascade entry. +The lower-level menu is unposted by executing a Tk command with +the form +.RS +.EX +\fImenu\f5 unpost\fR +.EE +.RE +where \fImenu\fR is the name of the associated menu. +.PP +If a \f5-command\fR option is specified for a cascade entry then it is +evaluated as a Tk command whenever the entry is invoked. + +.SH "WIDGET COMMAND" +The \f5menu\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. +.PP +Many of the widget commands for a menu take as one argument an +indicator of which entry of the menu to operate on. These +indicators are called \fIindex\fRes and may be specified in +any of the following forms: +.TP 12 +\fInumber\fR +Specifies the entry numerically, where 0 corresponds +to the top-most entry of the menu, 1 to the entry below it, and +so on. +.TP 12 +\f5active\fR +Indicates the entry that is currently active. If no entry is +active then this form is equivalent to \f5none\fR. This form may +not be abbreviated. +.TP 12 +\f5end\fR +Indicates the bottommost entry in the menu. If there are no +entries in the menu then this form is equivalent to \f5none\fR. +This form may not be abbreviated. +.TP 12 +\f5none\fR +Indicates ``no entry at all''; this is used most commonly with +the \f5activate\fR option to deactivate all the entries in the +menu. In most cases the specification of \f5none\fR causes +nothing to happen in the widget command. +This form may not be abbreviated. +.TP 12 +\f5@\fInumber\fR +In this form, \fInumber\fR is treated as a y-coordinate in the +menu's window; the entry closest to that y-coordinate is used. +For example, ``\f5@0\fR'' indicates the top-most entry in the +window. +.PP +The following widget commands are possible for menu widgets: +.TP +\fIpathName \f5activate \fIindex\fR +Change the state of the entry indicated by \fIindex\fR to \f5active\fR +and redisplay it using its active colours. +Any previously-active entry is deactivated. If \fIindex\fR +is specified as \f5none\fR, or if the specified entry is +disabled, then the menu ends up with no active entry. +Returns an empty string. +.TP +\fIpathName \f5add \fItype \fR?\fIoption value option value ...\fR? +Add a new entry to the bottom of the menu. The new entry's type +is given by \fItype\fR and must be one of \f5cascade\fR, +\f5checkbutton\fR, \f5command\fR, \f5radiobutton\fR, or \f5separator\fR. +If additional arguments +are present, they specify any of the following options: +.RS +.TP +\f5-activebackground \fIvalue\fR +Specifies a background colour to use for displaying this entry when it +is active. +If this option is not specified then the +\f5activebackground\fR option for the overall menu is used. +This option is not available for separator entries. +.TP +\f5-activeforeground \fIvalue\fR +Specifies a foreground colour to use for displaying this entry when it +is active. +If this option is not specified then the +\f5activeforeground\fR option for the overall menu is used. +This option is not available for separator entries. +.TP +\f5-background \fIvalue\fR +Specifies a background colour to use for displaying this entry when it +is in the normal state (neither active nor disabled). +If this option is not specified then the +\f5background\fR option for the overall menu is used. +This option is not available for separator entries. +.TP +\f5-bitmap \fIbitmap\fR +Specifies a bitmap to display in the menu instead of a textual +label. +This option overrides the \f5-label\fR option but may be reset +to an empty string to enable a textual label to be displayed. +If a \f5-image\fR option has been specified, it overrides +\f5-bitmap\fR. +This option is not available for separator entries. +.TP +\f5-command \fIvalue\fR +Specifies a Tk command to execute when the menu entry is invoked. +Not available for separator entries. +.TP +\f5-font \fIvalue\fR +Specifies the font to use when drawing the label or accelerator +string in this entry. +If this option is not specified then +the \f5font\fR option for the overall menu is used. +This option is not available for separator entries. +.TP +\f5-foreground \fIvalue\fR +Specifies a foreground colour to use for displaying this entry when it +is in the normal state (neither active nor disabled). +If this option is not specified then the +\f5foreground\fR option for the overall menu is used. +This option is not available for separator entries. +.TP +\f5-image \fIvalue\fR +Specifies an image to display in the menu instead of a text string +or bitmap +The image must have been created by some previous invocation of +\f5image create\fR. +This option overrides the \f5-label\fR and \f5-bitmap\fR options +but may be reset to an empty string to enable a textual or +bitmap label to be displayed. +This option is not available for separator entries. +.TP +\f5-label \fIvalue\fR +Specifies a string to display as an identifying label in the menu +entry. Not available for separator entries. +.TP +\f5-menu \fIvalue\fR +Available only for cascade entries. Specifies the path name of +the submenu associated with this entry. +The submenu must be a child of the menu. +.TP +\f5-selectcolor \fIvalue\fR +Available only for checkbutton and radiobutton entries. +Specifies the colour to display in the indicator when the entry is +selected. +If this option is not specified then the \f5selectcolor\fR +option for the menu determines the indicator colour. +.TP +\f5-selectimage \fIvalue\fR +Available only for checkbutton and radiobutton entries. +Specifies an image to display in the entry (in place of +the \f5-image\fR option) when it is selected. +\fIValue\fR is the name of an image, which must have been created +by some previous invocation of \f5image create\fR. +This option is ignored unless the \f5-image\fR option has +been specified. +.TP +\f5-state \fIvalue\fR +Specifies one of three states for the entry: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the entry is displayed using the +\f5foreground\fR and \f5background\fR +colours. +The active state is typically used when the pointer is over the entry. +In active state the entry is displayed using the \f5activeforeground\fR +and \f5activebackground\fR colours. +Disabled state means that the entry +should be insensitive: the default bindings will refuse to activate +or invoke the entry. +In this state the entry is displayed according to the +\f5disabledcolor\fR and \f5background\fR colours. +This option is not available for separator entries. +.TP +\f5-underline \fIvalue\fR +Specifies the integer index of a character to underline in the entry. +This option is also queried by the default bindings and used to +implement keyboard traversal. +0 corresponds to the first character of the text displayed in the entry, +1 to the next character, and so on. +If a bitmap or image is displayed in the entry then this option is ignored. +This option is not available for separator entries. +.TP +\f5-value \fIvalue\fR +Available only for radiobutton entries. Specifies the value to +store in the entry's associated variable when the entry is selected. +If an empty string is specified, then the \f5-label\fR option +for the entry as the value to store in the variable. +.TP +\f5-variable \fIvalue\fR +Available only for checkbutton and radiobutton entries. Specifies +the name of a global value to set when the entry is selected. +For checkbutton entries the variable is also set when the entry +is deselected. For radiobutton entries, changing the variable +causes the currently-selected entry to deselect itself. +.LP +The \f5add\fR widget command returns an empty string. +.RE +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5menu\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5menu\fR +command. +.TP +\fIpathName \f5delete \fIindex1\fR ?\fIindex2\fR? +Delete all of the menu entries between \fIindex1\fR and +\fIindex2\fR inclusive. +If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. +.TP +\fIpathName \f5entrycget\fR \fIindex option\fR +Returns the current value of a configuration option for +the entry given by \fIindex\fR. +\fIOption\fR may have any of the values accepted by the \f5add\fR +widget command. +.TP +\fIpathName \f5entryconfigure \fIindex \fR?\fIoptions\fR? +This command is similar to the \f5configure\fR command, except that +it applies to the options for an individual entry, whereas \f5configure\fR +applies to the options for the menu as a whole. +\fIOptions\fR may have any of the values accepted by the \f5add\fR +widget command. If \fIoptions\fR are specified, options are modified +as indicated +in the command and the command returns an empty string. +.TP +\fIpathName \f5index \fIindex\fR +Returns the numerical index corresponding to \fIindex\fR, or +\f5none\fR if \fIindex\fR was specified as \f5none\fR. +.TP +\fIpathName \f5insert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR? +Same as the \f5add\fR widget command except that it inserts the new +entry just before the entry given by \fIindex\fR, instead of appending +to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR +arguments have the same interpretation as for the \f5add\fR widget +command. +.TP +\fIpathName \f5invoke \fIindex\fR +Invoke the action of the menu entry. See the sections on the +individual entries above for details on what happens. If the +menu entry is disabled then nothing happens. If the +entry has a command associated with it then the result of that +command is returned as the result of the \f5invoke\fR widget +command. Otherwise the result is an empty string. Note: invoking +a menu entry does not automatically unpost the menu; the default +bindings normally take care of this before invoking the \f5invoke\fR +widget command. +.TP +\fIpathName \f5post \fIx y\fR +Arrange for the menu to be displayed on the screen at the screen +coordinates given by \fIx\fR and \fIy\fR. These coordinates are +adjusted if necessary to guarantee that the entire menu is visible on +the screen. This command normally returns an empty string. +If the \f5postcommand\fR option has been specified, then its value is +executed as a Tk script before posting the menu and the result of +that script is returned as the result of the \f5post\fR widget +command. +If an error returns while executing the command, then the error is +returned without posting the menu. +.TP +\fIpathName \f5postcascade \fIindex\fR +Posts the submenu associated with the cascade entry given by +\fIindex\fR, and unposts any previously posted submenu. +If \fIindex\fR doesn't correspond to a cascade entry, +or if \fIpathName\fR isn't posted, +the command has no effect except to unpost any currently posted +submenu. +.TP +\fIpathName \f5type \fIindex\fR +Returns the type of the menu entry given by \fIindex\fR. +This is the \fItype\fR argument passed to the \f5add\fR widget +command when the entry was created, such as \f5command\fR +or \f5separator\fR. +.TP +\fIpathName \f5unpost\fR +Unmap the window so that it is no longer displayed. If a +lower-level cascaded menu is posted, unpost that menu. Returns an +empty string. +.TP +\fIpathName \f5yposition \fIindex\fR +Returns a decimal string giving the y-coordinate within the menu +window of the topmost pixel in the entry specified by \fIindex\fR. + +.SH "DEFAULT BINDINGS" +Tk automatically creates bindings for menus that give them +the following default behaviour: +.IP [1] +When the mouse enters a menu, the entry underneath the mouse +cursor activates; as the mouse moves around the menu, the active +entry changes to track the mouse. +.IP [2] +When the mouse leaves a menu all of the entries in the menu +deactivate, except in the special case where the mouse moves from +a menu to a cascaded submenu. +.IP [3] +When a button is released over a menu, the active entry (if any) is invoked. +The menu also unposts unless it is a torn-off menu. +.IP [4] +If any of the entries in a menu have letters underlined with +with \f5-underline\fR option, then pressing one of the underlined +letters (or its upper-case or lower-case equivalent) invokes that +entry and unposts the menu. +.PP +Disabled menu entries are non-responsive: they don't activate and +they ignore mouse button presses and releases. +.PP +The behaviour of menus can be changed by defining new bindings for +individual widgets. +.SH BUGS +The first time any colour option of an entry is configured, +all of the menu colour option values are captured and set in the entry. +Any subsequent changes to the menu's colour options +will not be reflected in the entry. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/menubutton b/man/9/menubutton new file mode 100644 index 00000000..e3683563 --- /dev/null +++ b/man/9/menubutton @@ -0,0 +1,134 @@ +.TH MENUBUTTON 9 +.SH NAME +menubutton \- Create and manipulate menubutton widgets +.SH SYNOPSIS +\f5menubutton\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -disabledcolor -justify +-activeforeground -font -relief +-anchor -foreground -takefocus +-background -highlightcolor -text +-bitmap -highlightthickness -underline +-borderwidth -image +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.BI -height \ state +Specifies a desired height for the menubutton. +If this option is not specified, the menubutton's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.BI -menu \ widgetname +Specifies the path name of the menu associated with this menubutton. +The menu must be a child of the menubutton. +.TP +.BI -state \ state +Specifies one of three states for the menubutton: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the menubutton is displayed using the +\f5foreground\fR and \f5background\fR options. The active state is +typically used when the pointer is over the menubutton. In active state +the menubutton is displayed using the \f5activeforeground\fR and +\f5activebackground\fR options. Disabled state means that the menubutton +should be insensitive: the default bindings will refuse to activate +the widget and will ignore mouse button presses. +In this state the \f5disabledcolor\fR and +\f5background\fR options determine how the button is displayed. +.TP +.BI -width \ dist +Specifies a desired width for the menubutton. +If this option is not specified, the menubutton's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.SH INTRODUCTION +.PP +The \f5menubutton\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a menubutton widget. +Additional +options, described above, may be specified to configure aspects of the +menubutton such as its colors, font, text, and initial relief. +The \f5menubutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A menubutton is a widget that displays a textual string, bitmap, or image +and is associated with a menu widget. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. +In normal usage, pressing +mouse button 1 over the menubutton causes the associated menu to +be posted just underneath the menubutton. +If the mouse button is released over the menubutton then the menu +remains posted; clicking on the menubutton again unposts the menu. +Releasing the mouse button over a menu entry invokes the entry, while +releasing mouse button elsewhere unposts the menu. +.PP +Menubuttons are typically organized into groups called menu bars +that allow scanning: +if the mouse button is pressed over one menubutton (causing it +to post its menu) and the mouse is moved over another menubutton +without releasing the mouse button, then the +menu of the first menubutton is unposted and the menu of the +new menubutton is posted instead. +.SH "WIDGET COMMAND" +.PP +The \f5menubutton\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for menubutton widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5menubutton\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. +If one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5menubutton\fR +command. +.SH "DEFAULT BINDINGS" +Tk automatically creates class bindings for menubuttons that give them +the following default behaviour: +.IP [1] +A menubutton activates whenever the mouse passes over it and deactivates +whenever the mouse leaves it. +.IP [2] +Pressing mouse button 1 over a menubutton posts the menu specified by the +.B -menu +option. +If the menu is already posted then it is unposted. +.IP [3] +Releasing mouse button 1 over the menubutton leaves the menu posted. +Releasing the button over a menu entry, if the menu is posted, invokes that entry. +Releaseing the button anywhere else unposts the menu. +.IP [4] +When a menubutton is posted, its associated menu claims the input +focus to allow keyboard traversal of the menu and its submenus. +See the +.IR menu (9) +manual entry for details on these bindings. +.PP +If the menubutton's state is \f5disabled\fR then none of the above +actions occur: the menubutton is completely non-responsive. +.PP +The behaviour of menubuttons can be changed by defining new bindings for +individual widgets or by redefining the class bindings. +.SH SEE ALSO +.IR menu (9), +.IR options (9), +.IR types (9) diff --git a/man/9/options b/man/9/options new file mode 100644 index 00000000..47abfb41 --- /dev/null +++ b/man/9/options @@ -0,0 +1,244 @@ +.TH OPTIONS 9 +.SH NAME +options \- Standard options supported by widgets +.SH DESCRIPTION +This manual entry describes the common configuration options supported +by widgets in the Tk toolkit. Every widget does not necessarily support +every option (see the manual entries for individual widgets for a list +of the standard options supported by that widget), but if a widget does +support an option with one of the names listed below, then the option +has exactly the effect described below. +For a description of kinds of values that can passed to the various +options, see +.IR types (9). +.PP +In the descriptions below, the name refers to the +switch used in class commands and \f5configure\fR widget commands to +set this value. For example, if an option's command-line switch is set to +\f5-foreground\fR and there exists a widget \f5.a.b.c\fR, then the +command +.RS +.EX +\&.a.b.c configure -foreground black +.EE +.RE +may be used to specify the value \f5black\fR for the option in the +the widget \f5.a.b.c\fR. +.TP +.BI -activebackground " colour" +Specifies background colour to use when drawing active elements. +An element (a widget or portion of a widget) is active if the +mouse cursor is positioned over the element and pressing a mouse button +will cause some action to occur. +.TP +.BI -activeforeground " colour" +Specifies foreground colour to use when drawing active elements. +See above for definition of active elements. +.TP +.BI -actx +Returns the current x position of the widget in screen coordinates. +.TP +.BI -acty +Returns the current y position of the widget in screen coordinates. +.TP +.BI -actwidth +Returns the current allocated width of the widget. +.TP +.BI -actheight +Returns the current allocated height of the widget. +.TP +.BI -anchor " val" +Specifies how the information in a widget (e.g. text or a bitmap) +is to be displayed in the widget. +.I Val +must be one of the values \f5n\fR, \f5ne\fR, \f5e\fR, \f5se\fR, +\f5s\fR, \f5sw\fR, \f5w\fR, \f5nw\fR, or \f5center\fR. +For example, \f5nw\fR means display the information such that its +top-left corner is at the top-left corner of the widget. +.TP +.B -background \fIcolour\fP \fRor\fP -bg \fIcolour\fP +Specifies the normal background colour to use when displaying the +widget. +.TP +.BI -bitmap " bitmap" +Specifies a bitmap to display in the widget. +The exact way in which the bitmap is displayed may be affected by +other options such as \f5anchor\fR or \f5justify\fR. +Typically, if this option is specified then it overrides other +options that specify a textual value to display in the widget; +the \f5bitmap\fR option may be reset to an empty string to re-enable +a text display. +In widgets that support both \f5bitmap\fR and \f5image\fR options, +\f5image\fR will usually override \f5bitmap\fR. +For those widgets that support the \f5foreground\fR option, if the bitmap is +monochrome it is displayed using the foreground colour. +.TP +.B -borderwidth \fIdist\fP \fRor\fP -bd \fIdist\fP +Specifies a non-negative value indicating the width +of the 3-D border to draw around the outside of the widget (if such a +border is being drawn; the \f5relief\fR option typically determines +this). The value may also be used when drawing 3-D effects in the +interior of the widget. +.TP +.B -disabledcolor \fIcolour\fP +Specifies the foreground colour to use when drawing disabled widgets. +Certain widgets can be disabled by use of their +.B -state +option. +.TP +.B -font \fIfont\fP +Specifies the font to use when drawing text inside the widget. +.TP +.B -foreground \fIcolour\fP or -fg \fIcolour\fP +Specifies the normal foreground colour to use when displaying the widget. +.TP +.B -highlightcolor \fIcolour\fP +Specifies the colour to use for the traversal highlight rectangle that is +drawn around the widget when it has the input focus. +.TP +.B -highlightthickness \fIdist\fP +Specifies a non-negative value indicating the width of the highlight +rectangle to draw around the outside of the widget when it has the +input focus. +If the value is zero, no focus highlight is drawn around the widget. +.TP +.B -image \fIimage\fP +Specifies an image to display in the widget, which must have been +created with the \f5image create\fR command. +Typically, if the \f5image\fR option is specified then it overrides other +options that specify a bitmap or textual value to display in the widget; +the \f5image\fR option may be reset to an empty string to re-enable +a bitmap or text display. +For those widgets that support the \f5foreground\fR option, if the image is +monochrome it is displayed using the foreground colour. +.TP +.B -jump \fIboolean\fP +For widgets with a slider that can be dragged to adjust a value, +such as scrollbars, this option determines when +notifications are made about changes in the value. +If the value is false, updates are made continuously as the +slider is dragged. +If the value is true, updates are delayed until the mouse button +is released to end the drag; at that point a single notification +is made (the value ``jumps'' rather than changing smoothly). +.TP +.B -justify \fIval\fP +When there are multiple lines of text displayed in a widget, this +option determines how the lines line up with each other. +.I Val +must be one of \f5left\fR, \f5center\fR, or \f5right\fR. +\f5Left\fR means that the lines' left edges all line up, \f5center\fR +means that the lines' centers are aligned, and \f5right\fR means +that the lines' right edges line up. +.TP +.B -orient \fIorientation\fP +For widgets that can lay themselves out with either a horizontal +or vertical orientation, such as scrollbars, this option specifies +which orientation should be used. +.I Orientation +must be either \f5horizontal\fR +or \f5vertical\fR. +.TP +.B -padx \fIdist\fP +Specifies a non-negative value indicating how much extra space +to request for the widget in the X-direction. +When computing how large a window it needs, the widget will +add this amount to the width it would normally need (as determined +by the width of the things displayed in the widget); if the geometry +manager can satisfy this request, the widget will end up with extra +internal space to the left and/or right of what it displays inside. +Most widgets only use this option for padding text: if they are +displaying a bitmap or image, then they usually ignore padding +options. +.TP +.B -pady \fIdist\fP +Specifies a non-negative value indicating how much extra space +to request for the widget in the Y-direction. +When computing how large a window it needs, the widget will add +this amount to the height it would normally need (as determined by +the height of the things displayed in the widget); if the geometry +manager can satisfy this request, the widget will end up with extra +internal space above and/or below what it displays inside. +Most widgets only use this option for padding text: if they are +displaying a bitmap or image, then they usually ignore padding +options. +.TP +.B -relief \fIval\fP +Specifies the 3-D effect desired for the widget. Acceptable +values for +.I val are \f5raised\fR, \f5sunken\fR, \f5flat\fR, \f5ridge\fR, +and \f5groove\fR. +The value +indicates how the interior of the widget should appear relative +to its exterior; for example, \f5raised\fR means the interior of +the widget should appear to protrude from the screen, relative to +the exterior of the widget. +.TP +.B -selectbackground \fIcolour\fP +Specifies the background colour to use when displaying selected +items. +.TP +.B -selectborderwidth \fIdist\fP +Specifies a non-negative value indicating the width +of the 3-D border to draw around selected items. +.TP +.B -selectforeground \fIcolour\fP +Specifies the foreground colour to use when displaying selected +items. +.TP +.B -takefocus \fIboolean\fP +Determines whether clicking on the widget will automatically +give it the keyboard focus, and also whether the widget +will become part of the keyboard focus list and made accessible +by keyboard navigation. +.TP +.B -text \fIval\fP +Specifies a string, +.IR val , +to be displayed inside the widget. The way in which +the string is displayed depends on the particular widget and may be +determined by other options, such as \f5anchor\fR or \f5justify\fR. +.TP +.B -underline \fIinteger\fP +Specifies the integer index of a character to underline in the widget. +This option is used by the default bindings to implement keyboard +traversal for menu buttons and menu entries. +0 corresponds to the first character of the text displayed in the +widget, 1 to the next character, and so on. +.TP +.B -xscrollcommand \fIcommand\fP +Specifies the prefix for a command used to communicate with horizontal +scrollbars. +When the view in the widget's window changes (or +whenever anything else occurs that could change the display in a +scrollbar, such as a change in the total size of the widget's +contents), the widget will +generate a Tk command by concatenating +.I command +and +two numbers. +Each of the numbers is a fraction between 0 and 1, which indicates +a position in the document. 0 indicates the beginning of the document, +1 indicates the end, .333 indicates a position one third the way through +the document, and so on. +The first fraction indicates the first information in the document +that is visible in the window, and the second fraction indicates +the information just after the last portion that is visible. +The command is +then passed to the Tk interpreter for execution. Typically the +\f5-xscrollcommand\fR option consists of the path name of a scrollbar +widget followed by +.RB `` set '', +e.g. +.RB `` ".x.scrollbar set" '': +this will cause +the scrollbar to be updated whenever the view in the window changes. +If this option is not specified, then no command will be executed. +.TP +.B -yscrollcommand \fIcommand\fP +Specifies the prefix for a command used to communicate with vertical +scrollbars. This option is treated in the same way as the +\f5-xscrollcommand\fR option, except that it is used for vertical +scrollbars and is provided by widgets that support vertical scrolling. +See the description of \f5-xscrollcommand\fR for details +on how this option is used. diff --git a/man/9/pack b/man/9/pack new file mode 100644 index 00000000..4ac3014e --- /dev/null +++ b/man/9/pack @@ -0,0 +1,227 @@ +.TH PACK 9 +.SH NAME +pack \- Geometry manager that packs around edges of cavity +.SH SYNOPSIS +\f5pack \fIoption arg \fR?\fIarg ...\fR? + +.SH DESCRIPTION +The \f5pack\fR command is used to communicate with the packer, +a geometry manager that arranges the children of a parent by +packing them in order around the edges of the parent. +The \f5pack\fR command can have any of several forms, depending +on the \fIoption\fR argument: +.TP +\f5pack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +If the first argument to \f5pack\fR is a window name (any value +starting with ``.''), then the command is processed in the same +way as \f5pack configure\fR. +.TP +\f5pack configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +The arguments consist of the names of one or more slave windows +followed by pairs of arguments that specify how +to manage the slaves. +See ``THE PACKER ALGORITHM'' below for details on how the options +are used by the packer. +The following options are supported: +.RS +.TP +\f5-after \fIother\fR +\fIOther\fR must be the name of another window. +Use its master as the master for the slaves, and insert +the slaves just after \fIother\fR in the packing order. +.TP +\f5-anchor \fIanchor\fR +\fIAnchor\fR must be a valid anchor position such as \f5n\fR +or \f5sw\fR; it specifies where to position each slave in its +parcel. +Defaults to \f5center\fR. +.TP +\f5-before \fIother\fR +\fIOther\fR must be the name of another window. +Use its master as the master for the slaves, and insert +the slaves just before \fIother\fR in the packing order. +.TP +\f5-expand \fIboolean\fR +Specifies whether the slaves should be expanded to consume +extra space in their master. +\fIBoolean\fR may have any proper boolean value, such as \f51\fR +or \f5no\fR. +Defaults to 0. +.TP +\f5-fill \fIstyle\fR +If a slave's parcel is larger than its requested dimensions, this +option may be used to stretch the slave. +\fIStyle\fR must have one of the following values: +.RS +.TP +\f5none\fR +Give the slave its requested dimensions plus any internal padding +requested with \f5-ipadx\fR or \f5-ipady\fR. This is the default. +.TP +\f5x\fR +Stretch the slave horizontally to fill the entire width of its +parcel (except leave external padding as specified by \f5-padx\fR). +.TP +\f5y\fR +Stretch the slave vertically to fill the entire height of its +parcel (except leave external padding as specified by \f5-pady\fR). +.TP +\f5both\fR +Stretch the slave both horizontally and vertically. +.RE +.TP +\f5-in \fIother\fR +Insert the slave(s) at the end of the packing order for the master +window given by \fIother\fR. +.TP +\f5-ipadx \fIdist\fR +\fIDist\fR specifies how much horizontal internal padding to +leave on each side of the slave(s). +\fIDist\fR must be a valid screen distance, such as \f52\fR or \f5.5c\fR. +It defaults to 0. +.TP +\f5-ipady \fIdist\fR +\fIDist\fR specifies how much vertical internal padding to +leave on each side of the slave(s). +\fIDist\fR defaults to 0. +.TP +\f5-padx \fIdist\fR +\fIDist\fR specifies how much horizontal external padding to +leave on each side of the slave(s). +\fIDist\fR defaults to 0. +.TP +\f5-pady \fIdist\fR +\fIDist\fR specifies how much vertical external padding to +leave on each side of the slave(s). +\fIDist\fR defaults to 0. +.TP +\f5-side \fIside\fR +Specifies which side of the master the slave(s) will be packed against. +Must be \f5left\fR, \f5right\fR, \f5top\fR, or \f5bottom\fR. +Defaults to \f5top\fR. +.LP +If no \f5-in\fR, \f5-after\fR or \f5-before\fR option is specified +then each of the slaves will be inserted at the end of the packing list +for its parent unless it is already managed by the packer (in which +case it will be left where it is). +If one of these options is specified then all the slaves will be +inserted at the specified point. +If any of the slaves are already managed by the geometry manager +then any unspecified options for them retain their previous values rather +than receiving default values. +.RE +.TP +\f5pack forget \fIslave \fR?\fIslave ...\fR? +Removes each of the \fIslave\fRs from the packing order for its +master and unmaps their windows. +The slaves will no longer be managed by the packer. +.TP +\f5pack propagate \fImaster\fR ?\fIboolean\fR? +If \fIboolean\fR has a true boolean value such as \f51\fR or \f5on\fR +then propagation is enabled for \fImaster\fR, which must be a window +name (see ``GEOMETRY PROPAGATION'' below). +If \fIboolean\fR has a false boolean value then propagation is +disabled for \fImaster\fR. +In either of these cases an empty string is returned. +If \fIboolean\fR is omitted then the command returns \f50\fR or +\f51\fR to indicate whether propagation is currently enabled +for \fImaster\fR. +Propagation is enabled by default. +.TP +\f5pack slaves \fImaster\fR +Returns a list of all of the slaves in the packing order for \fImaster\fR. +The order of the slaves in the list is the same as their order in +the packing order. +If \fImaster\fR has no slaves then an empty string is returned. + +.SH "THE PACKER ALGORITHM" +For each master the packer maintains an ordered list of slaves +called the \fIpacking list\fR. +The \f5-in\fR, \f5-after\fR, and \f5-before\fR configuration +options are used to specify the master for each slave and the slave's +position in the packing list. +If none of these options is given for a slave then the slave +is added to the end of the packing list for its parent. +.PP +The packer arranges the slaves for a master by scanning the +packing list in order. +At the time it processes each slave, a rectangular area within +the master is still unallocated. +This area is called the \fIcavity\fR; for the first slave it +is the entire area of the master. +.PP +For each slave the packer carries out the following steps: +.IP [1] +The packer allocates a rectangular \fIparcel\fR for the slave +along the side of the cavity given by the slave's \f5-side\fR option. +If the side is top or bottom then the width of the parcel is +the width of the cavity and its height is the requested height +of the slave plus the \f5-ipady\fR and \f5-pady\fR options. +For the left or right side the height of the parcel is +the height of the cavity and the width is the requested width +of the slave plus the \f5-ipadx\fR and \f5-padx\fR options. +The parcel may be enlarged further because of the \f5-expand\fR +option (see ``EXPANSION'' below) +.IP [2] +The packer chooses the dimensions of the slave. +The width will normally be the slave's requested width plus +twice its \f5-ipadx\fR option and the height will normally be +the slave's requested height plus twice its \f5-ipady\fR +option. +However, if the \f5-fill\fR option is \f5x\fR or \f5both\fR +then the width of the slave is expanded to fill the width of the parcel, +minus twice the \f5-padx\fR option. +If the \f5-fill\fR option is \f5y\fR or \f5both\fR +then the height of the slave is expanded to fill the width of the parcel, +minus twice the \f5-pady\fR option. +.IP [3] +The packer positions the slave over its parcel. +If the slave is smaller than the parcel then the \f5-anchor\fR +option determines where in the parcel the slave will be placed. +If \f5-padx\fR or \f5-pady\fR is non-zero, then the given +amount of external padding will always be left between the +slave and the edges of the parcel. +.PP +Once a given slave has been packed, the area of its parcel +is subtracted from the cavity, leaving a smaller rectangular +cavity for the next slave. +If a slave doesn't use all of its parcel, the unused space +in the parcel will not be used by subsequent slaves. +If the cavity should become too small to meet the needs of +a slave then the slave will be given whatever space is +left in the cavity. +If the cavity shrinks to zero size, then all remaining slaves +on the packing list will be unmapped from the screen until +the master window becomes large enough to hold them again. + +.SH EXPANSION +If a master window is so large that there will be extra space +left over after all of its slaves have been packed, then the +extra space is distributed uniformly among all of the slaves +for which the \f5-expand\fR option is set. +Extra horizontal space is distributed among the expandable +slaves whose \f5-side\fR is \f5left\fR or \f5right\fR, +and extra vertical space is distributed among the expandable +slaves whose \f5-side\fR is \f5top\fR or \f5bottom\fR. + +.SH "GEOMETRY PROPAGATION" +The packer normally computes how large a master must be to +just exactly meet the needs of its slaves, and it sets the +requested width and height of the master to these dimensions. +This causes geometry information to propagate up through a +window hierarchy to a top-level window so that the entire +sub-tree sizes itself to fit the needs of the leaf windows. +However, the \f5pack propagate\fR command may be used to +turn off propagation for one or more masters. +If propagation is disabled then the packer will not set +the requested width and height of the packer. +This may be useful if, for example, you wish for a master +window to have a fixed size that you specify. + +.SH "RESTRICTIONS ON MASTER WINDOWS" +The master for each slave must be a frame widget or the top-level window (``.''). +Widgets of other types can be specifed as the master window +but will give rise to unpredictable results. + +.SH SEE ALSO +.IR types (9) diff --git a/man/9/panel b/man/9/panel new file mode 100644 index 00000000..27552f7b --- /dev/null +++ b/man/9/panel @@ -0,0 +1,121 @@ +.TH PANEL 9 +.SH NAME +panel \- embedded graphics +.SH SYNOPSIS +\f5panel\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-anchor -borderwidth -background -relief +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -height \fIdist\fP +Specifies a desired height for the panel. +If this option isn't specified, the panel's desired height is computed +from the image and mask images. If these are replicated, +the default is zero. +.TP +.B -width \fIdist\fP +Specifies a desired width for the panel. +If this option isn't specified, the panel's desired height is computed +from the image and mask images. If these are replicated, +the default is zero. +.SH DESCRIPTION +The \f5panel\fR command creates a new window (given by the \fIpathName\fR +argument) and makes it into a panel widget. +Additional options, described above, may be specified on the +command line +to configure aspects of the panel such as its background colour and 3-D relief. +The \f5panel\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A panel is a widget that displays arbitrary graphics drawn outside +of Tk. An application is free to use any image or mask that it +chooses to create; the panel will display the contents of the image +through the mask (see +.IR draw (2)). +.PP +A panel widget will not display anything until its image has been +set using +.B putimage +(see +.IR tk (2)). + +.SH "WIDGET COMMAND" +The \f5panel\fR command creates a new Tk command whose name +is \fIpathName\fR. This command may be used to invoke various +operations on the widget: It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for panel widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5panel\fR +function. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5panel\fR +function +.TP +\fIpathName \f5dirty\fR ?\fIminx miny maxx maxy\fR? +Mark the area inside the given rectangle +((\fIminx\fP, \fIminy\fP), (\fImaxx\fP, \fImaxy\fP)) +to be flushed to the screen. If the rectangle is not +given, the whole area will be marked. +The coordinates are relative to the image's origin. +.TP +\fIpathName \f5origin\fR ?\fIx y\fR? +Set the point within the image that will be displayed +at the top left of the panel's rectangle. +If the area allocated to the panel is more than +the area drawn by the image, the ``top left'' will +positioned with respect to the value of the +.B -anchor +option. +If the point is not given, the current origin +is returned. +.TP +\fIpathName \f5panelx\fR ?\fIscreenx\fR? +Given a screen x-coordinate, +.IR screenx , +this command returns the image x-coordinate displayed +at that location. +.TP +\fIpathName \f5panely\fR ?\fIscreeny\fR? +Given a screen y-coordinate, +.IR screeny , +this command returns the image y-coordinate displayed +at that location. +.TP +\fIpathName \f5screenx\fR ?\fIpanelx\fR? +Given an image x-coordinate, +.IR panelx , +this command returns the +equivalent screen x-coordinate. +.TP +\fIpathName \f5screeny\fR ?\fIpanely\fR? +Given an image y-coordinate, +.IR panely , +this command returns the +equivalent screen y-coordinate. +.SH BINDINGS +When a new panel is created, it has no default event bindings. +.SH SEE ALSO +.IR draw (2), +.IR tk (2), +.IR options (9), +.IR types (9) diff --git a/man/9/radiobutton b/man/9/radiobutton new file mode 100644 index 00000000..a439e224 --- /dev/null +++ b/man/9/radiobutton @@ -0,0 +1,192 @@ +.TH RADIOBUTTON 9 +.SH NAME +radiobutton \- Create and manipulate radiobutton widgets +.SH SYNOPSIS +\f5radiobutton\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -disabledcolor -justify +-activeforeground -font -relief +-anchor -foreground -takefocus +-background -highlightcolor -text +-bitmap -highlightthickness -underline +-borderwidth -image +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -command \fIcommand\fP +Specifies a Tk command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. The button's global variable (\f5-variable\fR option) will +be updated before the command is invoked. +.TP +.B -height \fIdist\fP +Specifies a desired height for the button. +If this option isn't specified, the button's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.TP +.B -indicatoron \fIboolean\fP +Specifies whether or not the indicator should be drawn. +If false, the \f5relief\fP option is ignored and the widget's +relief is always \f5sunken\fP if the widget is selected +and \f5raised\fP otherwise. +.TP +.B -selectcolor \fIcolour\fP +Specifies a background colour to use when the button is selected. +If \f5indicatoron\fR is true, the colour applies to the indicator. +If \f5indicatoron\fR is false, this colour is used as the background +for the entire widget, in place of \f5background\fR or \f5activebackground\fR, +whenever the widget is selected. +If specified as an empty string, no special colour is used for +displaying when the widget is selected. +.ig +.TP +.B -selectimage \fIimage\fP +Specifies an image to display (in place of the \f5image\fR option) +when the radiobutton is selected. +This option is ignored unless the \f5image\fR option has been +specified. +.. +.TP +.B -state \fIstate\fP +Specifies one of three states for the radiobutton: \f5normal\fR, \f5active\fR, +or \f5disabled\fR. In normal state the radiobutton is displayed using the +\f5foreground\fR and \f5background\fR options. The active state is +typically used when the pointer is over the radiobutton. In active state +the radiobutton is displayed using the \f5activeforeground\fR and +\f5activebackground\fR options. Disabled state means that the radiobutton +should be insensitive: the default bindings will refuse to activate +the widget and will ignore mouse button presses. +In this state the \f5disabledcolor\fR and +\f5background\fR options determine how the radiobutton is displayed. +.TP +.B -value \fIstring\fP +Specifies value to store in the button's associated variable whenever +this button is selected. +.TP +.B -variable \fIstring\fP +Specifies name of global variable to set whenever this button is +selected. Changes in this variable also cause the button to select +or deselect itself. +Defaults to the value \f5selectedButton\fR. +.TP +.B -width \fIdist\fP +Specifies a desired width for the button. +If this option isn't specified, the button's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.SH DESCRIPTION +The \f5radiobutton\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a radiobutton widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the radiobutton such as its colours, font, +text, and initial relief. The \f5radiobutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A radiobutton is a widget that displays a textual string, bitmap or image +and a diamond called an \fIindicator\fR. +If text is displayed, it must all be in a single font, but it +can occupy multiple lines on the screen (if it contains newlines) and +one of the characters may optionally be underlined using the +\f5underline\fR option. A radiobutton has +all of the behaviour of a simple button: it can display itself in either +of three different ways, according to the \f5state\fR option; +it can be made to appear +raised, sunken, or flat; and it invokes +a Tk command whenever mouse button 1 is clicked over the +check button. +.PP +In addition, radiobuttons can be \fIselected\fR. +If a radiobutton is selected, the indicator is normally +drawn with a sunken relief and a special colour, and +a Tk variable associated with the radiobutton is set to a particular +value. +If the radiobutton is not selected, the indicator is drawn with a +raised relief and no special colour. +Typically, several radiobuttons share a single variable and the +value of the variable indicates which radiobutton is to be selected. +When a radiobutton is selected it sets the value of the variable to +indicate that fact; each radiobutton also monitors the value of +the variable and automatically selects and deselects itself when the +variable's value changes. +By default the variable \f5selectedButton\fR +is used; its contents give the name of the button that is +selected, or the empty string if no button associated with that +variable is selected. +The name of the variable for a radiobutton, +plus the variable to be stored into it, may be modified with options +on the command line. +Configuration options may also be used to modify the way the +indicator is displayed (or whether it is displayed at all). +By default a radiobutton is configured to select itself on button clicks. +.SH "WIDGET COMMAND" +The \f5radiobutton\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for radiobutton widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5radiobutton\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5radiobutton\fR +command. +.TP +\fIpathName \f5deselect\fR +Deselects the radiobutton and sets the associated variable to an +empty string. +If this radiobutton was not currently selected, the command has +no effect. +.TP +\fIpathName \f5invoke\fR +Does just what would have happened if the user invoked the radiobutton +with the mouse: selects the button and invokes +its associated Tk command, if there is one. +The return value is the return value from the Tk command, or an +empty string if there is no command associated with the radiobutton. +This command is ignored if the radiobutton's state is \f5disabled\fR. +.TP +\fIpathName \f5select\fR +Selects the radiobutton and sets the associated variable to the +value corresponding to this widget. + +.SH BINDINGS +Tk automatically creates bindings for radiobuttons that give them +the following default behaviour: +.IP [1] +The radiobutton activates whenever the mouse passes over it and deactivates +whenever the mouse leaves the radiobutton. +.IP [2] +When mouse button 1 is pressed over a radiobutton it is invoked (it +becomes selected and the command associated with the button is +invoked, if there is one). +.PP +If the radiobutton's state is \f5disabled\fR then none of the above +actions occur: the radiobutton is completely non-responsive. +.PP +The behaviour of radiobuttons can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR button (9), +.IR checkbutton (9), +.IR choicebutton (9), +.IR options (9), +.IR types (9) diff --git a/man/9/raise b/man/9/raise new file mode 100644 index 00000000..8e9f7951 --- /dev/null +++ b/man/9/raise @@ -0,0 +1,13 @@ +.TH RAISE 9 +.SH NAME +raise \- Change a window's position in the stacking order +.SH SYNOPSIS +\f5raise \fIwindow +.SH DESCRIPTION +.B Raise +raises +\fIwindow\fR so that it is above all of its siblings in the stacking +order (it will not be obscured by any siblings and will obscure +any siblings that overlap it). +.SH "SEE ALSO" +.IR lower (9) diff --git a/man/9/scale b/man/9/scale new file mode 100644 index 00000000..85d2e48d --- /dev/null +++ b/man/9/scale @@ -0,0 +1,198 @@ +.TH SCALE 9 +.SH NAME +scale \- Create and manipulate scale widgets +.SH SYNOPSIS +\f5scale\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -font -orient +-background -foreground -relief +-borderwidth -highlightcolor -takefocus +-disabledcolor -highlightthickness +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -bigincrement \fIdist\fR +Some interactions with the scale cause its value to change by +``large'' increments; this option specifies the size of the +large increments. If specified as 0, the large increments default +to 1/10 the range of the scale. +.TP +.B -command \fIcommand\fR +Specifies the prefix of a Tk command to invoke whenever the scale's +value is changed via a widget command. +The actual command consists +of this option followed by a space and a real number indicating the +new value of the scale. +.TP +.B -from \fIfrac\fR +A real value corresponding to the left or top end of the scale. +.TP +.B -height \fIdist\fP +Specifies a desired height for the scale. +If this option isn't specified, the scale is given a default height. +.TP +.B -label \fIstring\fR +A string to display as a label for the scale. If the option is specified +as an empty string, no label is displayed. +.TP +.B -resolution \fIfrac\fR +A real value specifying the resolution for the scale. +If this value is greater than zero then the scale's value will always be +rounded to an even multiple of this value, as will tick marks and +the endpoints of the scale. If the value is less than zero then no +rounding occurs. Defaults to 1 (i.e., the value will be integral). +.TP +.B -showvalue \fIboolean\fR +Specifies a boolean value indicating whether or not the current +value of the scale is to be displayed. +.TP +.B -sliderlength \fIdist\fR +Specfies the size of the slider along the slider's +long dimension.. +.TP +.B -sliderrelief \fIrelief\fI +Specifies the relief to use when drawing the slider. +.TP +.B -state \fIstate\fR +Specifies one of three states for the scale: \f5normal\fR, +\f5active\fR, or \f5disabled\fR. +If the scale is disabled then the value may not be changed and the scale +won't activate. +If the scale is active, the slider is displayed using the colour +specified by the \f5activebackground\fR option. +.TP +.B -tickinterval \fIfrac\fR +Must be a real value. +Determines the spacing between numerical +tick marks displayed below or to the left of the slider. +If 0, no tick marks will be displayed. +.TP +.B -to \fIfrac\fR +Specifies a real value corresponding +to the right or bottom end of the scale. +This value may be either less than or greater than the \f5from\fR option. +.TP +.B -width \fIdist\fP +Specifies a desired width for the scale. +If this option isn't specified, the scale is given a default width. +.SH DESCRIPTION +The \f5scale\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a scale widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the scale such as its colours, orientation, +and relief. The \f5scale\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR. +.PP +A scale is a widget that displays a rectangular \fItrough\fR and a +small \fIslider\fR. The trough corresponds to a range +of real values (determined by the \f5from\fR, \f5to\fR, and +\f5resolution\fR options), +and the position of the slider selects a particular real value. +The slider's position (and hence the scale's value) may be adjusted +with the mouse or keyboard as described in the BINDINGS +section below. Whenever the scale's value is changed, a Tk +command is invoked (using the \f5command\fR option) to notify +other interested widgets of the change. +.PP +Three annotations may be displayed in a scale widget: a label +appearing at the top right of the widget (top left for horizontal +scales), a number displayed just to the left of the slider +(just above the slider for horizontal scales), and a collection +of numerical tick marks just to the right of the trough +(just below the trough for horizontal scales). Each of these three +annotations may be enabled or disabled using the +configuration options. + +.SH "WIDGET COMMAND" +The \f5scale\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for scale widgets: +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5scale\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5scale\fR +command. +.TP +\fIpathName \f5coords \fR?\fIvalue\fR? +Returns a list whose elements are the x and y coordinates of +the point along the centreline of the trough that corresponds +to \fIvalue\fR. +If \fIvalue\fR is omitted then the scale's current value is used. +.TP +\fIpathName \f5get\fR ?\fIx y\fR? +If \fIx\fR and \fIy\fR are omitted, returns the current value +of the scale. If \fIx\fR and \fIy\fR are specified, they give +pixel coordinates within the widget; the command returns +the scale value corresponding to the given pixel. +Only one of \fIx\fR or \fIy\fR is used: for horizontal scales +\fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. +.TP +\fIpathName \f5identify\fR \fIx y\fR +Returns a string indicating what part of the scale lies under +the coordinates given by \fIx\fR and \fIy\fR. +A return value of \f5slider\fR means that the point is over +the slider; \f5trough1\fR means that the point is over the +portion of the slider above or to the left of the slider; +and \f5trough2\fR means that the point is over the portion +of the slider below or to the right of the slider. +If the point isn't over one of these elements, an empty string +is returned. +.TP +\fIpathName \f5set\fR \fIvalue\fR +This command is invoked to change the current value of the scale, +and hence the position at which the slider is displayed. \fIValue\fR +gives the new value for the scale. +The command has no effect if the scale is disabled. +.SH BINDINGS +Tk automatically creates bindings for scales that give them +the following default behaviour. +Where the behaviour is different for vertical and horizontal scales, +the horizontal behaviour is described in parentheses. +.IP [1] +If button 1 is pressed in the trough, the scale's value will +be incremented or decremented by the value of the \f5bigincrement\fR +option so that the slider moves in the direction of the cursor. +If the button is held down, the action auto-repeats. +.IP [2] +If button 1 is pressed over the slider, the slider can be dragged +with the mouse. +.IP [3] +If the widget receives Up-arrow or Left-arrow key events, the scale's value +will be incremented or decremented so as to adjust the value towards the +.BR from value . +.IP [4] +If the widget receives Down-arrow or Right-arrow key events, the scale's value +will be incremented or decremented so as to adjust the value towards the +.BR to value . +.PP +If the scale is disabled using the \f5state\fR option then +none of the above bindings have any effect. +.PP +The behaviour of scales can be changed by defining new bindings for +individual widgets. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/scrollbar b/man/9/scrollbar new file mode 100644 index 00000000..b7fe9ea4 --- /dev/null +++ b/man/9/scrollbar @@ -0,0 +1,252 @@ +.TH SCROLLBAR 9 +.SH NAME +scrollbar \- Create and manipulate scrollbar widgets +.SH SYNOPSIS +\f5scrollbar\fI pathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-activebackground -borderwidth -orient +-background -jump -relief +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -activerelief \fIrelief\fP +Specifies the relief to use when displaying the element that is +active, if any. +Elements other than the active element are always displayed with +a raised relief. +.TP +.B -command \fIcommand\fP +Specifies the prefix of a Tk command to invoke to change the view +in the widget associated with the scrollbar. When a user requests +a view change by manipulating the scrollbar, a Tk command is +invoked. The actual command consists of this option followed by +additional information as described later. This option almost always has +a value such as \f5.t xview\fR or \f5.t yview\fR, consisting of the +name of a widget and either \f5xview\fR (if the scrollbar is for +horizontal scrolling) or \f5yview\fR (for vertical scrolling). +All scrollable widgets have \f5xview\fR and \f5yview\fR commands +that take exactly the additional arguments appended by the scrollbar +as described in SCROLLING COMMANDS below. +.ig +DEPRECATED +.TP +.B -elementborderwidth \fIdist\fP +Specifies the width of borders drawn around the internal elements +of the scrollbar (the two arrows and the slider). +If this value is less than zero, the value of the \f5borderwidth\fR +option is used in its place. +.. +.TP +.B -height \fIdist\fP +Specifies a desired height for the scrollbar. +If this option isn't specified, a suitable default height is chosen. +.TP +.B -width \fIdist\fP +Specifies a desired width for the scrollbar. +If this option isn't specified, a suitable default width is chosen. +.SH DESCRIPTION +The \f5scrollbar\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a scrollbar widget. +Additional options, described above, may be specified on the command +line to configure aspects of the scrollbar +such as its colours, orientation, and relief. +The \f5scrollbar\fR command returns its \fIpathName\fR argument. +At the time this command is invoked, there must not exist a window +named \fIpathName\fR. +.PP +A scrollbar is a widget that displays two arrows, one at each end of +the scrollbar, and a \fIslider\fR in the middle portion of the +scrollbar. +It provides information about what is visible in an \fIassociated window\fR +that displays a document of some sort (such as a file being edited or +a drawing). +The position and size of the slider indicate which portion of the +document is visible in the associated window. For example, if the +slider in a vertical scrollbar covers the top third of the area +between the two arrows, it means that the associated window displays +the top third of its document. +.PP +Scrollbars can be used to adjust the view in the associated window +by clicking or dragging with the mouse. See the BINDINGS section +below for details. + +.SH ELEMENTS +A scrollbar displays five elements, which are referred to in the +widget commands for the scrollbar: +.TP 12 +\f5arrow1\fR +The top or left arrow in the scrollbar. +.TP 12 +\f5trough1\fR +The region between the slider and \f5arrow1\fR. +.TP 12 +\f5slider\fR +The rectangle that indicates what is visible in the associated widget. +.TP 12 +\f5trough2\fR +The region between the slider and \f5arrow2\fR. +.TP 12 +\f5arrow2\fR +The bottom or right arrow in the scrollbar. + +.SH "WIDGET COMMAND" +The \f5scrollbar\fR command creates a new Tk command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for scrollbar widgets: +.TP +\fIpathName \f5activate \fR?\fIelement\fR? +Marks the element indicated by \fIelement\fR as active, which +causes it to be displayed as specified by the \f5activebackground\fR option. +The only element values understood by this command are \f5arrow1\fR, +\f5slider\fR, or \f5arrow2\fR. +If any other value is specified then no element of the scrollbar +will be active. +If \fIelement\fR is not specified, the command returns +the name of the element that is currently active, or an empty string +if no element is active. +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5scrollbar\fR +command. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5scrollbar\fR +command. +.TP +\fIpathName \f5delta \fIdeltaX deltaY\fR +Returns a real number indicating the fractional change in +the scrollbar setting that corresponds to a given change +in slider position. For example, if the scrollbar is horizontal, +the result indicates how much the scrollbar setting must change +to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is +ignored in this case). +If the scrollbar is vertical, the result indicates how much the +scrollbar setting must change to move the slider \fIdeltaY\fR pixels +down. The arguments and the result may be zero or negative. +.TP +\fIpathName \f5fraction \fIx y\fR +Returns a real number between 0 and 1 indicating where the point +given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. +The value 0 corresponds to the top or left of the trough, the +value 1 corresponds to the bottom or right, 0.5 corresponds to +the middle, and so on. +\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar +widget. +If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest +point in the trough is used. +.TP +\fIpathName \f5get\fR +Returns the scrollbar settings in the form of a list whose +elements are the arguments to the most recent \f5set\fR widget command. +.TP +\fIpathName \f5identify\fR \fIx y\fR +Returns the name of the element under the point given by \fIx\fR and +\fIy\fR (such as \f5arrow1\fR), or an empty string if the point does +not lie in any element of the scrollbar. +\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar +widget. +.TP +\fIpathName \f5set\fR \fIfirst last\fR +This command is invoked by the scrollbar's associated widget to +tell the scrollbar about the current view in the widget. +The command takes two arguments, each of which is a real fraction +between 0 and 1. +The fractions describe the range of the document that is visible in +the associated widget. +For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means +that the first part of the document visible in the window is 20% +of the way through the document, and the last visible part is 40% +of the way through. + +.SH "SCROLLING COMMANDS" +When the user interacts with the scrollbar, for example by dragging +the slider, the scrollbar notifies the associated widget that it +must change its view. +The scrollbar makes the notification by evaluating a Tk command +generated from the scrollbar's \f5-command\fR option. +The command may take any of the following forms. +In each case, \fIprefix\fR is the contents of the +\f5-command\fR option, which usually has a form like \f5.t yview\fR +.TP +\fIprefix \f5moveto \fIfraction\fR +\fIFraction\fR is a real number between 0 and 1. +The widget should adjust its view so that the point given +by \fIfraction\fR appears at the beginning of the widget. +If \fIfraction\fR is 0 it refers to the beginning of the +document. 1.0 refers to the end of the document, 0.333 +refers to a point one-third of the way through the document, +and so on. +.TP +\fIprefix \f5scroll \fInumber \f5unit\fR +The widget should adjust its view by \fInumber\fR units. +The units are defined in whatever way makes sense for the widget, +such as characters or lines in a text widget. +\fINumber\fR is either 1, which means one unit should scroll off +the top or left of the window, or -1, which means that one unit +should scroll off the bottom or right of the window. +.TP +\fIprefix \f5scroll \fInumber \f5page\fR +The widget should adjust its view by \fInumber\fR pages. +It is up to the widget to define the meaning of a page; typically +it is slightly less than what fits in the window, so that there +is a slight overlap between the old and new views. +\fINumber\fR is either 1, which means the next page should +become visible, or -1, which means that the previous page should +become visible. + +.SH BINDINGS +Tk automatically creates bindings for scrollbars that give them +the following default behaviour. +If the behaviour is different for vertical and horizontal scrollbars, +the horizontal behaviour is described in parentheses. + +.IP [1] +Pressing button 1 over \f5arrow1\fR causes the view in the +associated widget to shift up (left) by one unit so that the +document appears to move down (right) one unit. +If the button is held down, the action auto-repeats. +.IP [2] +Pressing button 1 over \f5trough1\fR causes the view in the +associated widget to shift up (left) by one screenful so that the +document appears to move down (right) one screenful. +.IP [3] +Pressing button 1 over the slider and dragging causes the view +to drag with the slider. +If the \f5jump\fR option is true, then the view doesn't drag along +with the slider; it changes only when the mouse button is released. +.IP [4] +Pressing button 1 over \f5trough2\fR causes the view in the +associated widget to shift down (right) by one screenful so that the +document appears to move up (left) one screenful. +.IP [5] +Pressing button 1 over \f5arrow2\fR causes the view in the +associated widget to shift down (right) by one unit so that the +document appears to move up (left) one unit. +If the button is held down, the action auto-repeats. +.IP [6] +If button 2 is pressed over the trough or the slider, it sets +the view to correspond to the mouse position; dragging the +mouse with button 2 down causes the view to drag with the mouse. +If button 2 is pressed over one of the arrows, it causes the +same behaviour as pressing button 1. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/see b/man/9/see new file mode 100644 index 00000000..cd849073 --- /dev/null +++ b/man/9/see @@ -0,0 +1,37 @@ +.TH SEE 9 +.SH NAME +see \- Make a portion of a widget visible. +.SH SYNOPSIS +\f5see \fIoption\fP ?\fIpathName\fR? +.SH DESCRIPTION +\f5See\fP makes sure that a portion of a widget +is visible in its containing view; for instance, it will +scroll a canvas or text widget to ensure that the +specified portion is in view. The following options +are supported: +.TP +\f5-rectangle\fP \fIlist\fP +Specifies a list with four \fIdist\fP coordinates describing the left, top, +right, and bottom coordinates of the rectangular region, +in coordinates relative to the widget origin, of the area +that should be made visible. +.TP +\f5-point\fP \fIlist\P +Specifies a list with two \fIdist\fP coordinates describing +a point within the widget that should be made visible +by preference if the entirety of the above-specified +rectangle cannot be shown. Defaults to the top left of +the specified rectangle. +.TP +\f5-where\fP +If this option is given, \f5see\fP returns a list containing +the left, top, right and bottom coordinates of +the currently visible portion of +.IR pathName . +.PP +If neither the \f5-rectangle\fP or the \f5-point\fP +options are given, then the entire area of \fIpathName\fP +will be made visible. +.SH SEE ALSO +.IR options (9), +.IR types (9) diff --git a/man/9/send b/man/9/send new file mode 100644 index 00000000..2f1cee9a --- /dev/null +++ b/man/9/send @@ -0,0 +1,38 @@ +.TH SEND 9 +.SH NAME +send \- send a value down a Tk channel +.SH SYNOPSIS +\f5send \fIchan\fP \fIstring\fP +.SH DESCRIPTION +.B Send +is the gateway from the Tk world into the Limbo world. +It sends +.I string +down +.IR chan , +which should previously have been named with a call to +.B namechan +(see +.IR tk (2)). +Tk channels are non blocking, so the call will return immediately, +whether the message has been sent or not. If too many messages +have been queued on the +.IR chan , +then the message will be +discarded, and a warning printed on the console. +.I String +is not subject to interpretation by the usual Tk quoting rules. +.SH BUGS +.I String +is not subject to interpretation by the usual Tk quoting rules. +This means, for example that: +.EX + radiobutton .x -text X -variable x -value x + radiobutton .y -text Y -variable y -value y + button .z -text Submit {send chan submit [variable X]} +.EE +will not work as expected. Instead, one must interrogate values +directly in Limbo. +.PP +The specialised queued channels will be replaced by buffered channels in Limbo in +a future edition of Inferno. diff --git a/man/9/text b/man/9/text new file mode 100644 index 00000000..f530e358 --- /dev/null +++ b/man/9/text @@ -0,0 +1,1188 @@ +.TH TEXT 9 +.SH NAME +text \- Create and manipulate text widgets +.SH SYNOPSIS +\f5text\fI \fIpathName \fR?\fIoptions\fR? +.SH STANDARD OPTIONS +.EX +-background -pady -takefocus +-borderwidth -relief -xscrollcommand +-font -selectbackground -yscrollcommand +-foreground -selectborderwidth +-padx -selectforeground +.EE +.SH "WIDGET-SPECIFIC OPTIONS" +.TP +.B -height \fIdist\fP +Specifies the desired height for the window. +.TP +.B -spacing1 \fIdist\fP +Requests additional space above each text line in the widget, +using any of the standard forms for screen distances. +If a line wraps, this option only applies to the first line +on the display. +This option may be overriden with \f5-spacing1\fR options in +tags. +.TP +.B -spacing2 \fIdist\fP +For lines that wrap (so that they cover more than one line on the +display) this option specifies additional space to provide between +the display lines that represent a single line of text. +The value may have any of the standard forms for screen distances. +This option may be overriden with \f5-spacing2\fR options in +tags. +.TP +.B -spacing3 \fIdist\fP +Requests additional space below each text line in the widget, +using any of the standard forms for screen distances. +If a line wraps, this option only applies to the last line +on the display. +This option may be overriden with \f5-spacing3\fR options in +tags. +.TP +.B -state \fPstate\fP +Specifies one of two states for the text: \f5normal\fR or \f5disabled\fR. +If the text is disabled then characters may not be inserted or deleted +and no insertion cursor will be displayed, even if the input focus is +in the widget. +.TP +.B -tabs \fIdist\fP +Specifies a set of tab stops for the window. The option's value consists +of a list of \fIdist\fP values giving the positions of the tab stops. Each +\fIdist\fP may optionally be followed in the next list element +by one of the keywords \f5left\fR, \f5right\fR, \f5center\fR, +or \f5numeric\fR, which specifies how to justify +text relative to the tab stop. \f5Left\fR is the default; it causes +the text following the tab character to be positioned with its left edge +at the tab position. \f5Right\fR means that the right edge of the text +following the tab character is positioned at the tab position, and +\f5center\fR means that the text is centered at the tab position. +\f5Numeric\fR means that the decimal point in the text is positioned +at the tab position; if there is no decimal point then the least +significant digit of the number is positioned just to the left of the +tab position; if there is no number in the text then the text is +right-justified at the tab position. +For example, \f5-tabs {2c left 4c 6c center}\fR creates three +tab stops at two-centimeter intervals; the first two use left +justification and the third uses center justification. +If the list of tab stops does not have enough elements to cover all +of the tabs in a text line, then Tk extrapolates new tab stops using +the spacing and alignment from the last tab stop in the list. +The value of the \f5tabs\fR option may be overridden by \f5-tabs\fR +options in tags. +If no \f5-tabs\fR option is specified, or if it is specified as +an empty list, then Tk uses default tabs spaced every eight +(average size) characters. +.TP +.B -width \fIdist\fP +Specifies the desired width for the window. +.TP +.B -wrap \fIval\fP +Specifies how to handle lines in the text that are too long to be +displayed in a single line of the text's window. +The value must be \f5none\fR or \f5char\fR or \f5word\fR. +A wrap mode of \f5none\fR means that each line of text appears as +exactly one line on the screen; extra characters that don't fit +on the screen are not displayed. +In the other modes each line of text will be broken up into several +screen lines if necessary to keep all the characters visible. +In \f5char\fR mode a screen line break may occur after any character; +in \f5word\fR mode a line break will only be made at word boundaries. + +.SH DESCRIPTION +The \f5text\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a text widget. +Additional +options, described above, may be specified on the command line +to configure aspects of the text such as its default background colour +and relief. The \f5text\fR command returns the +path name of the new window. +.PP +A text widget displays one or more lines of text and allows that +text to be edited. +Text widgets support three different kinds of annotations on the +text, called tags, marks, and embedded windows. +Tags allow different portions of the text +to be displayed with different fonts and colours. +In addition, Tk commands can be associated with tags so +that scripts are invoked when particular actions such as keystrokes +and mouse button presses occur in particular ranges of the text. +See TAGS below for more details. +.PP +The second form of annotation consists of marks, which are floating +markers in the text. +Marks are used to keep track of various interesting positions in the +text as it is edited. +See MARKS below for more details. +.PP +The third form of annotation allows arbitrary windows to be +embedded in a text widget. +See EMBEDDED WINDOWS below for more details. + +.SH INDICES +Many of the widget commands for texts take one or more indices +as arguments. +An index is a string used to indicate a particular place within +a text, such as a place to insert characters or one endpoint of a +range of characters to delete. +Indices have the syntax +.RS +.EX +\fIbase modifier modifier modifier ...\fR +.EE +.RE +Where \fIbase\fR gives a starting point and the \fImodifier\fRs +adjust the index from the starting point (e.g. move forward or +backward one character). Every index must contain a \fIbase\fR, +but the \fImodifier\fRs are optional. +.PP +The \fIbase\fR for an index must have one of the following forms: +.TP 12 +\fIline\f5.\fIchar\fR +Indicates \fIchar\fR'th character on line \fIline\fR. +Lines are numbered from 1 for consistency with other UNIX programs +that use this numbering scheme. +Within a line, characters are numbered from 0. +If \fIchar\fR is \f5end\fR then it refers to the newline character +that ends the line. +.TP 12 +\f5@\fIx\f5,\fIy\fR +Indicates the character that covers the pixel whose x and y coordinates +within the text's window are \fIx\fR and \fIy\fR. +.TP 12 +\f5end\fR +Indicates the end of the text (the character just after the last +newline). +.TP 12 +\fImark\fR +Indicates the character just after the mark whose name is \fImark\fR. +.TP 12 +\fItag\f5.first\fR +Indicates the first character in the text that has been tagged with +\fItag\fR. +This form generates an error if no characters are currently tagged +with \fItag\fR. +.TP 12 +\fItag\f5.last\fR +Indicates the character just after the last one in the text that has +been tagged with \fItag\fR. +This form generates an error if no characters are currently tagged +with \fItag\fR. +.TP 12 +\fIpathName\fR +Indicates the position of the embedded window whose name is +\fIpathName\fR. +This form generates an error if there is no embedded window +by the given name. +.PP +If modifiers follow the base index, each one of them must have one +of the forms listed below. +.TP +\f5+ \fIcount\f5 chars\fR +Adjust the index forward by \fIcount\fR characters, moving to later +lines in the text if necessary. If there are fewer than \fIcount\fR +characters in the text after the current index, then set the index +to the last character in the text. +Spaces on either side of \fIcount\fR are optional. +.TP +\f5\- \fIcount\f5 chars\fR +Adjust the index backward by \fIcount\fR characters, moving to earlier +lines in the text if necessary. If there are fewer than \fIcount\fR +characters in the text before the current index, then set the index +to the first character in the text. +Spaces on either side of \fIcount\fR are optional. +.TP +\f5+ \fIcount\f5 lines\fR +Adjust the index forward by \fIcount\fR lines, retaining the same +character position within the line. If there are fewer than \fIcount\fR +lines after the line containing the current index, then set the index +to refer to the same character position on the last line of the text. +Then, if the line is not long enough to contain a character at the indicated +character position, adjust the character position to refer to the last +character of the line (the newline). +Spaces on either side of \fIcount\fR are optional. +.TP +\f5\- \fIcount\f5 lines\fR +Adjust the index backward by \fIcount\fR lines, retaining the same +character position within the line. If there are fewer than \fIcount\fR +lines before the line containing the current index, then set the index +to refer to the same character position on the first line of the text. +Then, if the line is not long enough to contain a character at the indicated +character position, adjust the character position to refer to the last +character of the line (the newline). +Spaces on either side of \fIcount\fR are optional. +.TP +\f5linestart\fR +Adjust the index to refer to the first character on the line. +.TP +\f5lineend\fR +Adjust the index to refer to the last character on the line (the newline). +.TP +\f5wordstart\fR +Adjust the index to refer to the first character of the word containing +the current index. A word consists of any number of adjacent characters +that are letters, digits, or underscores, or a single character that +is not one of these. +.TP +\f5wordend\fR +Adjust the index to refer to the character just after the last one of the +word containing the current index. If the current index refers to the last +character of the text then it is not modified. +.PP +If more than one modifier is present then they are applied in +left-to-right order. For example, the index ``\f5end \- 1 chars\fR'' +refers to the next-to-last character in the text and the index +``\f5insert wordstart \- 1 c\fR'' refers to the character just before +the first one in the word containing the insertion cursor. + +.SH TAGS +The first form of annotation in text widgets is a tag. +A tag is a textual string that is associated with some of the characters +in a text. +Tags may contain arbitrary characters, but it is probably best to +avoid using the the characters `` '' (space), \f5+\fR, or \f5-\fR: +these characters have special meaning in indices, so tags containing +them can't be used as indices. The tag name may not begin with a digit. +There may be any number of tags associated with characters in a +text. +Each tag may refer to a single character, a range of characters, or +several ranges of characters. +An individual character may have any number of tags associated with it. +.PP +A priority order is defined among tags, and this order is used in +implementing some of the tag-related functions described below. +When a tag is defined (by associating it with characters or setting +its display options or binding commands to it), it is given +a priority higher than any existing tag. +The priority order of tags may be redefined using the +``\fIpathName \f5tag raise\fR'' and ``\fIpathName \f5tag lower\fR'' +widget commands. +.PP +Tags serve three purposes in text widgets. +First, they control the way information is displayed on the screen. +By default, characters are displayed as determined by the +\f5background\fR, \f5font\fR, and \f5foreground\fR options for the +text widget. +However, display options may be associated with individual tags +using the ``\fIpathName \f5tag configure\fR'' widget command. +If a character has been tagged, then the display options associated +with the tag override the default display style. +The following options are currently supported for tags: +.TP +\f5-background \fIcolour\fR +\fIColor\fR specifies the background colour to use for characters +associated with the tag. +.TP +\f5-borderwidth \fIdist\fR +\fIDist\fR specifies the width of a 3-D border to draw around +the background. +This option is used in conjunction with the \f5-relief\fR +option to give a 3-D appearance to the background for characters; +it is ignored unless the \f5-background\fR option +has been set for the tag. +.TP +\f5-font \fIfont\fR +\fIFont\fR is the name of a font to use for drawing characters. +.TP +\f5-foreground \fIcolour\fR +\fIColor\fR specifies the colour to use when drawing text and other +foreground information such as underlines. +.TP +\f5-justify \fIjustify\fR +If the first character of a display line has a tag for which this +option has been specified, then \fIjustify\fR determines how to +justify the line. +It must be one of \f5left\fR, \f5right\fR, or \f5center\fR. +If a line wraps, then the justification for each line on the +display is determined by the first character of that display line. +.TP +\f5-lmargin1 \fIdist\fR +If the first character of a text line has a tag for which this +option has been specified, then \fIdist\fR specifies how +much the line should be indented from the left edge of the +window. +\fIDist\fR may have any of the standard forms for screen +distances. +If a line of text wraps, this option only applies to the +first line on the display; the \f5-lmargin2\fR option controls +the indentation for subsequent lines. +.TP +\f5-lmargin2 \fIdist\fR +If the first character of a display line has a tag for which this +option has been specified, and if the display line is not the +first for its text line (i.e., the text line has wrapped), then +\fIdist\fR specifies how much the line should be indented from +the left edge of the window. +\fIDist\fR may have any of the standard forms for screen +distances. +This option is only used when wrapping is enabled, and it only +applies to the second and later display lines for a text line. +.TP +\f5-offset \fIdist\fR +\fIDist\fR specifies an amount by which the text's baseline +should be offset vertically from the baseline of the overall +line, in pixels. +For example, a positive offset can be used for superscripts +and a negative offset can be used for subscripts. +\fIDist\fR may have any of the standard forms for screen +distances. +.TP +\f5-overstrike \fIboolean\fR +Specifies whether or not to draw a horizontal rule through +the middle of characters. +.TP +\f5-relief \fIrelief\fR +\fIRelief\fR specifies the 3-D relief to use for drawing backgrounds. +This option is used in conjunction with the \f5-borderwidth\fR +option to give a 3-D appearance to the background for characters; +it is ignored unless the \f5-background\fR option +has been set for the tag. +.TP +\f5-rmargin \fIdist\fR +If the first character of a display line has a tag for which this +option has been specified, then \fIdist\fR specifies how wide +a margin to leave between the end of the line and the right +edge of the window. +This option is only used when wrapping is enabled. +If a text line wraps, the right margin for each line on the +display is determined by the first character of that display +line. +.TP +\f5-spacing1 \fIdist\fR +\fIDist\fR specifies how much additional space should be +left above each text line, using any of the standard forms for +screen distances. +If a line wraps, this option only applies to the first +line on the display. +.TP +\f5-spacing2 \fIdist\fR +For lines that wrap, this option specifies how much additional +space to leave between the display lines for a single text line. +\fIDist\fR may have any of the standard forms for screen +distances. +.TP +\f5-spacing3 \fIdist\fR +\fIDist\fR specifies how much additional space should be +left below each text line, using any of the standard forms for +screen distances. +If a line wraps, this option only applies to the last +line on the display. +.TP +\f5-tabs \fItabList\fR +\fITabList\fR specifies a set of tab stops in the same form +as for the \f5-tabs\fR option for the text widget. This +option only applies to a display line if it applies to the +first character on that display line. +If this option is specified as an empty string, it cancels +the option, leaving it unspecified for the tag (the default). +If the option is specified as a non-empty string that is +an empty list, such as \f5-tags\0{\0}\fR, then it requests +default 8-character tabs as described for the \f5tabs\fR +widget option. +.TP +\f5-underline \fIboolean\fR +\fIBoolean\fR specifies whether or not to draw an underline underneath +characters. +.TP +\f5-wrap \fImode\fR +\fIMode\fR specifies how to handle lines that are wider than the +text's window. +It has the same legal values as the \f5-wrap\fR option +for the text widget: \f5none\fR, \f5char\fR, or \f5word\fR. +If this tag option is specified, it overrides the \f5-wrap\fR option +for the text widget. +.PP +If a character has several tags associated with it, and if their +display options conflict, then the options of the highest priority +tag are used. +If a particular display option hasn't been specified for a +particular tag, or if it is specified as an empty string, then +that option will never be used; the next-highest-priority +tag's option will be used instead. +If no tag specifies a particular display option, then the default +style for the widget will be used. +.PP +The second purpose for tags is event bindings. +You can associate bindings with a tag in much the same way you can +associate bindings with a widget class: whenever particular +events occur on characters with the given tag, a given +Tk command will be executed. +Tag bindings can be used to give behaviours to ranges of characters; +among other things, this allows hypertext-like +features to be implemented. +For details, see the description of the \f5tag bind\fR widget +command below. +.PP +The third use for tags is in managing the selection. +See THE SELECTION below. + +.SH MARKS +The second form of annotation in text widgets is a mark. +Marks are used for remembering particular places in a text. +They are something like tags, in that they have names and +they refer to places in the file, but a mark isn't associated +with particular characters. +Instead, a mark is associated with the gap between two characters. +Only a single position may be associated with a mark at any given +time. +If the characters around a mark are deleted the mark will still +remain; it will just have new neighbour characters. +In contrast, if the characters containing a tag are deleted then +the tag will no longer have an association with characters in +the file. +Marks may be manipulated with the ``\fIpathName \f5mark\fR'' widget +command, and their current locations may be determined by using the +mark name as an index in widget commands. +.PP +Each mark also has a \fIgravity\fR, which is either \f5left\fR or +\f5right\fR. +The gravity for a mark specifies what happens to the mark when +text is inserted at the point of the mark. +If a mark has left gravity, then the mark is treated as if it +were attached to the character on its left, so the mark will +remain to the left of any text inserted at the mark position. +If the mark has right gravity, new text inserted at the mark +position will appear to the right of the mark. The gravity +for a mark defaults to \f5right\fR. +.PP +The name space for marks is different from that for tags: the +same name may be used for both a mark and a tag, but they will refer +to different things. +.PP +Two marks have special significance. +First, the mark \f5insert\fR is associated with the insertion cursor, +as described under THE INSERTION CURSOR below. +Second, the mark \f5current\fR is associated with the character +closest to the mouse and is adjusted automatically to track the +mouse position and any changes to the text in the widget (one +exception: \f5current\fR is not updated in response to mouse +motions if a mouse button is down; the update will be deferred +until all mouse buttons have been released). +Neither of these special marks may be deleted. + +.SH EMBEDDED WINDOWS +The third form of annotation in text widgets is an embedded window. +Each embedded window annotation causes a window to be displayed +at a particular point in the text. +There may be any number of embedded windows in a text widget, +and any widget may be used as an embedded window. +The embedded window's position on the screen will be updated as the +text is modified or scrolled. +Each embedded window occupies one character's worth of index space +in the text widget, and it may be referred to either by the name +of its embedded window or by its position in the widget's +index space. +If the range of text containing the embedded window is deleted and the +window is a child of the text widget then the window is destroyed. +.PP +When an embedded window is added to a text widget with the +\f5window create\fR widget command, several configuration +options may be associated with it. +These options may be modified later with the \f5window configure\fR +widget command. +The following options are currently supported: +.TP +\f5-align \fIwhere\fR +If the window is not as tall as the line in which it is displayed, +this option determines where the window is displayed in the line. +\fIWhere\fR must have one of the values \f5top\fR (align the top of the window +with the top of the line), \f5center\fR (center the window +within the range of the line), \f5bottom\fR (align the bottom of the +window with the bottom of the line's area), +or \f5baseline\fR (align the bottom of the window with the baseline +of the line). +.TP +\f5-padx \fIdist\fR +\fIDist\fR specifies the amount of extra space to leave on +each side of the embedded window. +It may have any of the usual forms defined for a screen distance. +.TP +\f5-pady \fIdist\fR +\fIDist\fR specifies the amount of extra space to leave on +the top and on the bottom of the embedded window. +It may have any of the usual forms defined for a screen distance. +.TP +\f5-stretch \fIboolean\fR +If the requested height of the embedded window is less than the +height of the line in which it is displayed, this option can be +used to specify whether the window should be stretched vertically +to fill its line. +If the \f5-pady\fR option has been specified as well, then the +requested padding will be retained even if the window is +stretched. +.TP +\f5-window \fIpathName\fR +Specifies the name of a window to display in the annotation. + +.SH THE SELECTION +Selection support is implemented via tags. +The \f5sel\fR tag is automatically defined when a text widget is +created, and it may not be deleted with the ``\fIpathName \f5tag delete\fR'' +widget command. Furthermore, the \f5selectbackground\fR, +\f5selectborderwidth\fR, and \f5selectforeground\fR options for +the text widget are tied to the \f5background\fR, +\f5borderwidth\fR, and \f5foreground\fR options for the \f5sel\fR +tag: changes in either will automatically be reflected in the +other. + +.SH THE INSERTION CURSOR +The mark named \f5insert\fR has special significance in text widgets. +It is defined automatically when a text widget is created and it +may not be unset with the ``\fIpathName \f5mark unset\fR'' widget +command. +The \f5insert\fR mark represents the position of the insertion +cursor, and the insertion cursor will automatically be drawn at +this point whenever the text widget has the input focus. + +.SH "WIDGET COMMAND" +The \f5text\fR command creates a new Tk command whose +name is the same as the path name of the text's window. This +command may be used to invoke various +operations on the widget. It has the following general form: +.RS +.EX +\fIpathName option \fR?\fIarg arg ...\fR? +.EE +.RE +\fIPathName\fR is the name of the command, which is the same as +the text widget's path name. \fIOption\fR and the \fIarg\fRs +determine the exact behaviour of the command. The following +commands are possible for text widgets: +.TP +\fIpathName \f5bbox \fIindex\fR +Returns a list of four elements describing the screen area +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 area occupied by the +character, and the last two elements give the width and height +of the area. +If the character is only partially visible on the screen, then +the return value reflects just the visible part. +If the character is not visible on the screen then the return +value is an empty list. +.TP +\fIpathName \f5cget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \f5text\fR +command. +.TP +\fIpathName \f5compare\fR \fIindex1 op index2\fR +Compares the indices given by \fIindex1\fR and \fIindex2\fR according +to the relational operator given by \fIop\fR, and returns 1 if +the relationship is satisfied and 0 if it isn't. +\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. +If \fIop\fR is == then 1 is returned if the two indices refer to +the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR +refers to an earlier character in the text than \fIindex2\fR, and +so on. +.TP +\fIpathName \f5configure\fR ?\fIoption\fR? \fI?value option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list of all of +the available options for \fIpathName\fR. If +one or more \fIoption-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \f5text\fR +command. +.TP +\fIpathName \f5debug \fR?\fIboolean\fR? +If the value is a true one then internal consistency checks will be +turned on in the code associated with text widgets. +If \fIboolean\fR has a false value then the debugging checks will +be turned off. +In either case the command returns an empty string. +If \fIboolean\fR is not specified then the command returns \f5on\fR +or \f5off\fR to indicate whether or not debugging is turned on. +There is a single debugging switch shared by all text widgets: turning +debugging on or off in any widget turns it on or off for all widgets. +For widgets with large amounts of text, the consistency checks may +cause a noticeable slow-down. +.TP +\fIpathName \f5delete \fIindex1 \fR?\fIindex2\fR? +Delete a range of characters from the text. +If both \fIindex1\fR and \fIindex2\fR are specified, then delete +all the characters starting with the one given by \fIindex1\fR +and stopping just before \fIindex2\fR (i.e. the character at +\fIindex2\fR is not deleted). +If \fIindex2\fR doesn't specify a position later in the text +than \fIindex1\fR then no characters are deleted. +If \fIindex2\fR isn't specified then the single character at +\fIindex1\fR is deleted. +It is not allowable to delete characters in a way that would leave +the text without a newline as the last character. +The command returns an empty string. +.TP +\fIpathName \f5dlineinfo \fIindex\fR +Returns a list with five elements describing the area occupied +by the display line containing \fIindex\fR. +The first two elements of the list give the x and y coordinates +of the upper-left corner of the area occupied by the +line, the third and fourth elements give the width and height +of the area, and the fifth element gives the position of the baseline +for the line, measured down from the top of the area. +All of this information is measured in pixels. +If the current wrap mode is \f5none\fR and the line extends beyond +the boundaries of the window, +the area returned reflects the entire area of the line, including the +portions that are out of the window. +If the line is shorter than the full width of the window then the +area returned reflects just the portion of the line that is occupied +by characters and embedded windows. +If the display line containing \fIindex\fR is not visible on +the screen then the return value is an empty list. +.TP +\fIpathName \f5get \fIindex1 \fR?\fIindex2\fR? +Return a range of characters from the text. +The return value will be all the characters in the text starting +with the one whose index is \fIindex1\fR and ending just before +the one whose index is \fIindex2\fR (the character at \fIindex2\fR +will not be returned). +If \fIindex2\fR is omitted then the single character at \fIindex1\fR +is returned. +If there are no characters in the specified range (e.g. \fIindex1\fR +is past the end of the file or \fIindex2\fR is less than or equal +to \fIindex1\fR) then an empty string is returned. +If the specified range contains embedded windows, no information +about them is included in the returned string. +.TP +\fIpathName \f5index \fIindex\fR +Returns the position corresponding to \fIindex\fR in the form +\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR +is the character number. +\fIIndex\fR may have any of the forms described under INDICES above. +.TP +\fIpathName \f5insert \fIindex chars \fR?\fItagList chars tagList ...\fR? +Inserts all of the \fIchars\fR arguments just before the character at +\fIindex\fR. +If \fIindex\fR refers to the end of the text (the character after +the last newline) then the new text is inserted just before the +last newline instead. +If there is a single \fIchars\fR argument and no \fItagList\fR, then +the new text will receive any tags that are present on both the +character before and the character after the insertion point; if a tag +is present on only one of these characters then it will not be +applied to the new text. +If \fItagList\fR is specified then it consists of a list of +tag names; the new characters will receive all of the tags in +this list and no others, regardless of the tags present around +the insertion point. +If multiple \fIchars\fR-\fItagList\fR argument pairs are present, +they produce the same effect as if a separate \f5insert\fR widget +command had been issued for each pair, in order. +The last \fItagList\fR argument may be omitted. +.TP +\fIpathName \f5mark \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate marks. The exact behaviour of +the command depends on the \fIoption\fR argument that follows +the \f5mark\fR argument. The following forms of the command +are currently supported: +.RS +.TP +\fIpathName \f5mark gravity \fImarkName\fR ?\fIdirection\fR? +If \fIdirection\fR is not specified, returns \f5left\fR or \f5right\fR +to indicate which of its adjacent characters \fImarkName\fR is attached +to. +If \fIdirection\fR is specified, it must be \f5left\fR or \f5right\fR; +the gravity of \fImarkName\fR is set to the given value. +.TP +\fIpathName \f5mark names\fR +Returns a list whose elements are the names of all the marks that +are currently set. +.TP +\fIpathName \f5mark next \fIindex\fR +Returns the name of the next mark at or after \fIindex\fR. +If \fIindex\fR is specified in numerical form, then the search for +the next mark begins at that index. +If \fIindex\fR is the name of a mark, then the search for +the next mark begins immediately after that mark. +This can still return a mark at the same position if +there are multiple marks at the same index. +If a mark has been set to the special \f5end\fP index, +then it appears to be \fIafter\fP \f5end\fP with respect to the \f5mark next\fP operation. +An empty string is returned if there are no marks after \fIindex\fP. +.TP +\fIpathName \f5mark previous \fIindex\fR +Returns the name of the mark at or before \fIindex\fR. +If \fIindex\fR is specified in numerical form, then the search for +the previous mark begins with the character just before that index. +If \fIindex\fR is the name of a mark, then the search for +the next mark begins immediately before that mark. +This can still return a mark at the same position if +there are multiple marks at the same index. +An empty string is returned if there are no marks before \fIindex\fR. +.TP +\fIpathName \f5mark set \fImarkName index\fR +Sets the mark named \fImarkName\fR to a position just before the +character at \fIindex\fR. +If \fImarkName\fR already exists, it is moved from its old position; +if it doesn't exist, a new mark is created. +This command returns an empty string. +.TP +\fIpathName \f5mark unset \fImarkName \fR?\fImarkName markName ...\fR? +Remove the mark corresponding to each of the \fImarkName\fR arguments. +The removed marks will not be usable in indices and will not be +returned by future calls to ``\fIpathName \f5mark names\fR''. +This command returns an empty string. +.RE +.TP +\fIpathName \f5scan\fR \fIoption args\fR +This command is used to implement scanning on texts. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \f5scan mark \fIx y\fR +Records \fIx\fR and \fIy\fR and the current view in the text window, +for use in conjunction with later \f5scan dragto\fR commands. +Typically this command is associated with a mouse button press in +the widget. It returns an empty string. +.TP +\fIpathName \f5scan dragto \fIx y\fR +This command computes the difference between its \fIx\fR and \fIy\fR +arguments and the \fIx\fR and \fIy\fR arguments to the last +\f5scan mark\fR command for the widget. +It then adjusts the view by 10 times the difference in coordinates. +This command is typically associated +with mouse motion events in the widget, to produce the effect of +dragging the text at high speed through the window. The return +value is an empty string. +.RE +.TP +\fIpathName \f5search \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? +Searches the text in \fIpathName\fR starting at \fIindex\fR for a range +of characters that matches \fIpattern\fR. +If a match is found, the index of the first character in the match is +returned as result; otherwise an empty string is returned. +One or more of the following switches +may be specified to control the search: +.RS +.TP +\f5-backwards\fR +The search will proceed backward through the text, finding the +matching range closest to \fIindex\fR whose first character +is before \fIindex\fR. +.TP +\f5-nocase\fR +Ignore case differences between the pattern and the text. +.TP +\f5-\|-\fR +This switch has no effect except to terminate the list of switches: +the next argument will be treated as \fIpattern\fR even if it starts +with \f5-\fR. +.LP +The matching range must be entirely within a single line of text. +If \fIstopIndex\fR is specified, the search stops at that index: +for forward searches, no match at or after \fIstopIndex\fR will +be considered; for backward searches, no match earlier in the +text than \fIstopIndex\fR will be considered. +If \fIstopIndex\fR is omitted, the entire text will be searched: +when the beginning or end of the text is reached, the search +continues at the other end until the starting location is reached +again; if \fIstopIndex\fR is specified, no wrap-around will occur. +.RE +.TP +\fIpathName \f5see \fIindex\fR +Adjusts the view in the window so that the character given by \fIindex\fR +is completely visible. +If \fIindex\fR is already visible then the command does nothing. +If \fIindex\fR is a short distance out of view, the command +adjusts the view just enough to make \fIindex\fR visible at the +edge of the window. +If \fIindex\fR is far out of view, then the command centers +\fIindex\fR in the window. +.TP +\fIpathName \f5tag \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate tags. The exact behaviour of the +command depends on the \fIoption\fR argument that follows the +\f5tag\fR argument. The following forms of the command are currently +supported: +.RS +.TP +\fIpathName \f5tag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? +Associate the tag \fItagName\fR with all of the characters starting +with \fIindex1\fR and ending just before +\fIindex2\fR (the character at \fIindex2\fR isn't tagged). +A single command may contain any number of \fIindex1\fR-\fIindex2\fR +pairs. +If the last \fIindex2\fR is omitted then the single character at +\fIindex1\fR is tagged. +If there are no characters in the specified range (e.g. \fIindex1\fR +is past the end of the file or \fIindex2\fR is less than or equal +to \fIindex1\fR) then the command has no effect. +.TP +\fIpathName \f5tag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? +This command associates \fIscript\fR with the tag given by +\fItagName\fR. +Whenever the event sequence given by \fIsequence\fR occurs for a +character that has been tagged with \fItagName\fR, +the script will be invoked. +This widget command is similar to the \f5bind\fR command except that +it operates on characters in a text rather than entire widgets. +See the \f5bind\fR manual entry for complete details +on the syntax of \fIsequence\fR and the substitutions performed +on \fIscript\fR before invoking it. +If all arguments are specified then a new binding is created, replacing +any existing binding for the same \fIsequence\fR and \fItagName\fR +(if the first character of \fIscript\fR is ``+'' then \fIscript\fR +augments an existing binding rather than replacing it). +In this case the return value is an empty string. +.RS +.PP +The only events for which bindings may be specified are those related +to the mouse and keyboard, such as \f5Enter\fR, \f5Leave\fR, +\f5ButtonPress\fR, \f5Motion\fR, and \f5KeyPress\fR. +Event bindings for a text widget use the \f5current\fR mark +described under MARKS above. +An \f5Enter\fR event triggers for a tag when the tag first +becomes present on the current character, and a \f5Leave\fR +event triggers for a tag when it ceases to be present on +the current character. +\f5Enter\fR and \f5Leave\fR events can happen either because the +\f5current\fR mark moved or because the character at that +position changed. +Note that these events are different than \f5Enter\fR and \f5Leave\fR +events for windows. +Mouse and keyboard events are directed to the current character. +.PP +It is possible for the current character to have multiple tags, +and for each of them to have a binding for a particular event +sequence. +When this occurs, one binding is invoked for each tag, in order +from lowest-priority to highest priority. +If there are multiple matching bindings for a single tag, then +the most specific binding is chosen (see the manual entry for +the \f5bind\fR command for details). +.PP +If bindings are created for the widget as a whole using the +\f5bind\fR command, then those bindings will supplement the +tag bindings. +The tag bindings will be invoked first, followed by bindings +for the window as a whole. +.RE +.TP +\fIpathName \f5tag cget\fR \fItagName option\fR +This command returns the current value of the option named \fIoption\fR +associated with the tag given by \fItagName\fR. +\fIOption\fR may have any of the values accepted by the \f5tag configure\fR +widget command. +.TP +\fIpathName \f5tag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \f5configure\fR widget command except +that it modifies options associated with the tag given by \fItagName\fR +instead of modifying options for the overall text widget. +If one or more \fIoption-value\fR pairs are specified, then the command +modifies the given option(s) to have the given value(s) in \fItagName\fR. +See TAGS above for details on the options available for tags. +.TP +\fIpathName \f5tag delete \fItagName \fR?\fItagName ...\fR? +Deletes all tag information for each of the \fItagName\fR +arguments. +The command removes the tags from all characters in the file +and also deletes any other information associated with the tags, +such as bindings and display information. +The command returns an empty string. +.TP +\fIpathName\f5 tag lower \fItagName \fR?\fIbelowThis\fR? +Changes the priority of tag \fItagName\fR so that it is just lower +in priority than the tag whose name is \fIbelowThis\fR. +If \fIbelowThis\fR is omitted, then \fItagName\fR's priority +is changed to make it lowest priority of all tags. +.TP +\fIpathName \f5tag names \fR?\fIindex\fR? +Returns a list whose elements are the names of all the tags that +are active at the character position given by \fIindex\fR. +If \fIindex\fR is omitted, then the return value will describe +all of the tags that exist for the text (this includes all tags +that have been named in a ``\fIpathName \f5tag\fR'' widget +command but haven't been deleted by a ``\fIpathName \f5tag delete\fR'' +widget command, even if no characters are currently marked with +the tag). +The list will be sorted in order from highest priority to lowest +priority. +.TP +\fIpathName \f5tag nextrange \fItagName index1 \fR?\fIindex2\fR? +This command searches the text for a range of characters tagged +with \fItagName\fR where the first character of the range is +no earlier than the character at \fIindex1\fR and no later than +the character just before \fIindex2\fR (a range starting at +\fIindex2\fR will not be considered). +If several matching ranges exist, the first one is chosen. +The command's return value is a list containing +two elements, which are the index of the first character of the +range and the index of the character just after the last one in +the range. +If no matching range is found then the return value is an +empty string. +If \fIindex2\fR is not given then it defaults to the end of the text. +.TP +\fIpathName \f5tag prevrange \fItagName index1 \fR?\fIindex2\fR? +This command searches the text for a range of characters tagged +with \fItagName\fR where the first character of the range is +before the character at \fIindex1\fR and no earlier than +the character at \fIindex2\fR (a range starting at +\fIindex2\fR will be considered). +If several matching ranges exist, the one closest to \fIindex1\fR is chosen. +The command's return value is a list containing +two elements, which are the index of the first character of the +range and the index of the character just after the last one in +the range. +If no matching range is found then the return value is an +empty string. +If \fIindex2\fR is not given then it defaults to the beginning of the text. +.TP +\fIpathName\f5 tag raise \fItagName \fR?\fIaboveThis\fR? +Changes the priority of tag \fItagName\fR so that it is just higher +in priority than the tag whose name is \fIaboveThis\fR. +If \fIaboveThis\fR is omitted, then \fItagName\fR's priority +is changed to make it highest priority of all tags. +.TP +\fIpathName \f5tag ranges \fItagName\fR +Returns a list describing all of the ranges of text that have been +tagged with \fItagName\fR. +The first two elements of the list describe the first tagged range +in the text, the next two elements describe the second range, and +so on. +The first element of each pair contains the index of the first +character of the range, and the second element of the pair contains +the index of the character just after the last one in the +range. +If there are no characters tagged with \fItag\fR then an +empty string is returned. +.TP +\fIpathName \f5tag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? +Remove the tag \fItagName\fR from all of the characters starting +at \fIindex1\fR and ending just before +\fIindex2\fR (the character at \fIindex2\fR isn't affected). +A single command may contain any number of \fIindex1\fR-\fIindex2\fR +pairs. +If the last \fIindex2\fR is omitted then the single character at +\fIindex1\fR is tagged. +If there are no characters in the specified range (e.g. \fIindex1\fR +is past the end of the file or \fIindex2\fR is less than or equal +to \fIindex1\fR) then the command has no effect. +This command returns an empty string. +.RE +.TP +\fIpathName \f5window \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate embedded windows. +The behaviour of the command depends on the \fIoption\fR argument +that follows the \f5window\fR argument. +The following forms of the command are currently supported: +.RS +.TP +\fIpathName \f5window cget\fR \fIindex option\fR +Returns the value of a configuration option for an embedded window. +\fIIndex\fR identifies the embedded window, and \fIoption\fR +specifies a particular configuration option, which must be one of +the ones listed in the section EMBEDDED WINDOWS. +.TP +\fIpathName \f5window configure \fIindex\fR ?\fIoption value ...\fR? +Query or modify the configuration options for an embedded window. +If one or more \fIoption-value\fR pairs are specified, then the command +modifies the given option(s) to have the given value(s). +See EMBEDDED WINDOWS for information on the options that +are supported. +.TP +\fIpathName \f5window create \fIindex\fR ?\fIoption value ...\fR? +This command creates a new window annotation, which will appear +in the text at the position given by \fIindex\fR. +Any number of \fIoption-value\fR pairs may be specified to +configure the annotation. +See EMBEDDED WINDOWS for information on the options that +are supported. +Returns an empty string. +.TP +\fIpathName \f5window names\fR +Returns a list whose elements are the names of all windows currently +embedded in \fIwindow\fR. +.RE +.TP +\fIpathName \f5xview \fIoption args\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 \f5xview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the portion of the document's 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 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. +The fractions refer only to the lines that are actually visible in the +window: if the lines in the window are all very short, so that they +are entirely visible, the returned fractions will be 0 and 1, +even if there are other lines in the text that are +much wider than the window. +These are the same values passed to scrollbars via the \f5-xscrollcommand\fR +option. +.TP +\fIpathName \f5xview moveto\fI fraction\fR +Adjusts the view in the window so that \fIfraction\fR of the horizontal +span of the text is off-screen to the left. +\fIFraction\fR is a fraction between 0 and 1. +.TP +\fIpathName \f5xview 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 \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\f5pages\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 +.TP +\fIpathName \f5yview \fI?args\fR? +This command is used to query and change the vertical position of the +text in the widget's window. +It can take any of the following forms: +.RS +.TP +\fIpathName \f5yview\fR +Returns a list containing two elements, both of which are real fractions +between 0 and 1. +The first element gives the position of the first character in the +top line in the window, relative to the text as a whole (0.5 means +it is halfway through the text, for example). +The second element gives the position of the character just after +the last one in the bottom line of the window, +relative to the text as a whole. +These are the same values passed to scrollbars via the \f5-yscrollcommand\fR +option. +.TP +\fIpathName \f5yview moveto\fI fraction\fR +Adjusts the view in the window so that the character given by \fIfraction\fR +appears on the top line of the window. +\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first +character in the text, 0.33 indicates the character one-third the +way through the text, and so on. +.TP +\fIpathName \f5yview scroll \fInumber what\fR +This command adjust the view in the window up or down according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \f5units\fR or \f5pages\fR. +If \fIwhat\fR is \f5units\fR, the view adjusts up or down by +\fInumber\fR lines on the display; if it is \f5pages\fR then +the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then earlier positions in the text +become visible; if it is positive then later positions in the text +become visible. +.TP +\fIpathName \f5yview \fR?\f5-pickplace\fR? \fIindex\fR +Changes the view in the widget's window to make \fIindex\fR visible. +If the \f5-pickplace\fR option isn't specified then \fIindex\fR will +appear at the top of the window. +If \f5-pickplace\fR is specified then the widget chooses where +\fIindex\fR appears in the window: +.RS +.IP [1] +If \fIindex\fR is already visible somewhere in the window then the +command does nothing. +.IP [2] +If \fIindex\fR is only a few lines off-screen above the window then +it will be positioned at the top of the window. +.IP [3] +If \fIindex\fR is only a few lines off-screen below the window then +it will be positioned at the bottom of the window. +.IP [4] +Otherwise, \fIindex\fR will be centered in the window. +.LP +The \f5-pickplace\fR option has been made obsolete by the \f5see\fR widget +command (\f5see\fR handles both x- and y-motion to make a location +visible, whereas \f5-pickplace\fR only handles motion in y). +.RE +.RE + +.SH BINDINGS +Tk automatically creates bindings for texts that give them +the following default behaviour. +In the descriptions below, ``word'' refers to a contiguous group +of letters, digits, or ``_'' characters, or any single character +other than these. +.IP [1] +Clicking mouse button 1 positions the insertion 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 strokes out a selection between +the insertion cursor and the character under the mouse. +.IP [2] +Double-clicking with mouse button 1 selects the word under the mouse +and positions the insertion cursor at the beginning of the word. +Dragging after a double click is ignored. +.IP [3] +If any normal printing characters are typed, they are +inserted at the point of the insertion cursor, replacing the +current selection. +.IP [4] +If the mouse is dragged out of the widget +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 [5] +The Left and Right keys move the insertion cursor one character to the +left or right; they also clear any selection in the text. +Control-b and Control-f behave the same as Left and Right, respectively. +.IP [6] +The Up and Down keys move the insertion cursor one line up or +down and clear any selection in the text. +Control-p and Control-n behave the same as Up and Down, respectively. +.IP [7] +The Page-up and Page-down keys move the view up or down +one screenful without moving the insertion cursor or adjusting the selection. +IControl-v behaves the same as Page-down. +.IP [8] +Home, Control-a and Control-< move the insertion cursor to the +beginning of its line and clear any selection in the widget. +.IP [9] +End, Control-e and Control-> move the insertion cursor to the +end of the line and clear any selection in the widget. +.IP [10] +The Delete key deletes the selection, if there is one in the widget. +If there is no selection, it deletes the character to the right of +the insertion cursor. +.IP [11] +Backspace and Control-h delete the selection, if there is one +in the widget. +If there is no selection, they delete the character to the left of +the insertion cursor. +.IP [12] +Control-d deletes the character to the right of the insertion cursor. +.IP [13] +Control-k deletes from the insertion cursor to the end of its line; +if the insertion cursor is already at the end of a line, then +Control-k deletes all of the next line. +.IP [14] +Control-o opens a new line by inserting a newline character in +front of the insertion cursor without moving the insertion cursor. +.IP [15] +Control-u deletes from the insertion cursor to the start of its line; +if the insertion cursor is already at the start of the line, then +the current line is joined with the previous one. +.IP [16] +Control-w deletes from the insertion cursor to the start of the word +that contains it; +if the insertion cursor is at the start of the line, then +the current line is joined with the previous one. +.PP +If the widget is disabled using the \f5-state\fR option, then its +view can still be adjusted and text can still be selected, +but no insertion cursor will be displayed and no text modifications will +take place. +.PP +The behaviour of texts can be changed by defining new bindings for +individual widgets. +.SH BUGS +Tab alignment doesn't work correctly. +.PP +The \f5-stretch\fR option on embedded windows is not implemented. +.SH SEE ALSO +.IR entry (9), +.IR options (9), +.IR types (9) diff --git a/man/9/types b/man/9/types new file mode 100644 index 00000000..33346c15 --- /dev/null +++ b/man/9/types @@ -0,0 +1,147 @@ +.TH TYPES 9 +.SH NAME +types \- Standard types required by widget options. +.SH DESCRIPTION +This manual entry describes the the standard types +that can be given as arguments to Inferno Tk widget +options. When an option is documented, the type +of argument that it accepts is either documented +there, or the name of the argument refers to one of the +names documented below. +.TP +.I anchorPos +One of the values \f5n\fR, \f5ne\fR, \f5e\fR, \f5se\fR, +\f5s\fR, \f5sw\fR, \f5w\fR, \f5nw\fR, or \f5center\fR. +See +.B -anchor +in +.IR options (9). +.TP +.I boolean +A true or false value, one of the following: +\f50\fP, \f5no\fP, \f5off\fP, +\f5false\fP (false), +\f51\fP, \f5yes\fP, \f5on\fP, +\f5true\fP (true). +.TP +.I bitmap +Identifies an image which can be drawn, or used as a mask +through which something else is drawn. If +.I bitmap +begins with a +.RB ` @ ', +the remaining characters must be the path name of +an Inferno image file. If +.I bitmap +begins with the character +.RB ` < ', +the remaining characters must be a decimal integer +giving the file descriptor number of an open file (see +.IR sys-open (2)) +from which the bitmap can be loaded. Otherwise, +.I bitmap +should be the name of a bitmap file in the directory +.BR /icons/tk . +.TP +.I color +A +.I color +parameter can be a colour name or an RGB (red, green and blue +luminance) value. The colour names recognized are: +.EX + aqua yellow red teal white + fuchsia black blue darkblue transparent + maroon gray green lime + purple navy olive orange +.EE +For RGB values, either +.BI # rgb +or +.BI # rrggbb +can be used, where +.IR r , +.IR rr , +etc. are hexadecimal values for the corresponding colour +components. +The notation +.BI #rrggbbaa +can be used to describe a colour with alpha (transparency) component +.IR aa ; +the +.IR rr , +.IR gg , +and +.IR bb +values should be pre-multiplied appropriately. This is the +canonical form for colour values. Alternatively, transparency +can be applied to any other colour using a suffix +.BI * alpha +where +.I alpha +is either +.BI #aa +(two hex digits representing an alpha value between 0 and 255) +or +.I f +(a decimal fixed point number between 0 and 1). +For example, +.B red*0.5 +gives half transparent red; +.B #007f007f*#7f +gives 0.75 transparent green (canonically +.B #003f003f). +.TP +.I dist +.I Dist +specifies a distance on the screen, in the following form: +an optional minus sign +.RB ( - ), +then one or more decimal digits (with possible +embedded decimal point), then an optional units +specifier. The unit specifiers are the following: +.RS +.TP +.B c +centimetres +.TP +.B m +millimetres +.TP +.B i +inches +.TP +.B p +points (1/72th inch) +.TP +.B h +height of widget's font (only applicable if the widget +has an associated font, and if the font has previously been set). +.TP +.B w +width of the zero +.RB ( 0 ) +character in widget's font. (see above). +.TP +Measurements are converted into pixels assuming 100 dots +per inch on an average CRT display. +.RE +.TP +.I font +A +.I font +parameter gives the full path name of an Inferno font file; +for example, +.BR /fonts/pelm/unicode.9.font . +.TP +.I frac +A numeric, possibly fractional, value. +.TP +.I relief +One of \f5raised\fR, \f5sunken\fR, \f5flat\fR, \f5ridge\fR, +or \f5groove\fR. See +.B -relief +in +.IR options (9). +.SH SEE ALSO +.IR intro (9), +.IR options (9) diff --git a/man/9/update b/man/9/update new file mode 100644 index 00000000..7428e60c --- /dev/null +++ b/man/9/update @@ -0,0 +1,24 @@ +.TH UPDATE 9 +.SH NAME +update \- flush graphics +.SH SYNOPSIS +\f5update\fP ?\fIoptions\fP? +.SH DESCRIPTION +Changes made via Tk commands do not become +visible until a call to +.BR update . +.B Update +flushes any pending changes to the screen. +The following options are supported: +.TP +\f5-disable\fP +If this option is given, all updates are disabled. +This is useful to enable a program to +stop mouse movement causing +automatic updates while it is making changes to the window. +.TP +\f5-enable\fP +This reverses a previous \f5update -enable\fP invocation. +.PP +.SH BUGS +Changes that affect window sizes are visible immediately. diff --git a/man/9/variable b/man/9/variable new file mode 100644 index 00000000..b1bcc141 --- /dev/null +++ b/man/9/variable @@ -0,0 +1,25 @@ +.TH VARIABLE 9 +.SH NAME +variable \- interrogate a button variable +.SH SYNOPSIS +\f5variable \fIvar\fR ?\fIvalue\fR? +.SH DESCRIPTION +.B Variable +queries or sets the value of a Tk radiobutton, checkbutton or choicebutton variable. +An error diagnostic will be returned if +the variable is of the wrong type (if for instance +it is the name of a named channel). +.PP +If \fIvalue\fR is given, the value of the variable is set +to that value, and any associated buttons +will subsequently reflect this in their appearance. +Omitting the \fIvalue\fR argument returns the current value of the variable. +.PP +The special variable +.B lasterror +holds the text of the last Tk error encountered. +It resets when queried. +.SH SEE ALSO +.IR checkbutton (9) +.IR choicebutton (9) +.IR radiobutton (9), |