diff options
| author | rjohnson <rjohnson> | 1998-04-01 09:37:39 (GMT) |
|---|---|---|
| committer | rjohnson <rjohnson> | 1998-04-01 09:37:39 (GMT) |
| commit | 13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22 (patch) | |
| tree | 3100714738a7941b590efee466a774862f9671c3 | |
| parent | e4ab1102029f9ac557ff190bfb9d34408340f345 (diff) | |
| download | tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.zip tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.tar.gz tk-13242623d2ff3ea02ab6a62bfb48a7dbb5c27e22.tar.bz2 | |
Initial revision
143 files changed, 29992 insertions, 0 deletions
@@ -0,0 +1,381 @@ +The Tk Toolkit + +SCCS: @(#) README 1.47 97/11/20 12:48:16 + +1. Introduction +--------------- + +This directory and its descendants contain the sources and documentation +for Tk, an X11 toolkit implemented with the Tcl scripting language. The +information here corresponds to Tk 8.0p2, which is the second patch update +for Tk 8.0. This release is designed to work with Tcl 8.0p2 and may not +work with any other version of Tcl. + +Tk 8.0 is a major release with significant new features such as native +look and feel on Macintoshes and PCs, a new font mechanism, application +embedding, and proper support for Safe-Tcl. See below for details. +There should be no backward incompatibilities in Tk 8.0 that affect +scripts. This patch release fixes various bugs in Tk 8.0; there are no +feature changes relative to Tk 8.0. + +Note: with Tk 8.0 the Tk version number skipped from 4.2 to 8.0. The +jump was made in order to synchronize the Tcl and Tk version numbers. + +2. Documentation +---------------- + +The best way to get started with Tk is to read one of the introductory +books on Tcl and Tk: + + Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch, + Prentice-Hall, 1997, ISBN 0-13-616830-2 + + Tcl and the Tk Toolkit, by John Ousterhout, + Addison-Wesley, 1994, ISBN 0-201-63337-X + + Exploring Expect, by Don Libes, + O'Reilly and Associates, 1995, ISBN 1-56592-090-2 + +The "doc" subdirectory in this release contains a complete set of +reference manual entries for Tk. Files with extension ".1" are for +programs such as wish; files with extension ".3" are for C library +procedures; and files with extension ".n" describe Tcl commands. To +print any of the manual entries, cd to the "doc" directory and invoke +your favorite variant of troff using the normal -man macros, for example + + ditroff -man wish.1 + +to print wish.1. If Tk has been installed correctly and your "man" +program supports it, you should be able to access the Tcl manual entries +using the normal "man" mechanisms, such as + + man wish + +If you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may +find the Postscript file doc/tk4.0.ps useful. It is a porting guide +that summarizes the new features and discusses how to deal with the +changes in Tk 4.0 that are not backwards compatible. + +There is also an official home for Tcl and Tk on the Web: + http://www.smli.com/research/tcl +These Web pages include release updates, reports on bug fixes and porting +issues, HTML versions of the manual pages, and pointers to many other +Tcl/Tk Web pages at other sites. Check them out! + +3. Compiling and installing Tk +------------------------------ + +This release contains everything you should need to compile and run +Tk under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95, +or Win 3.1 with Win32s). + +Before trying to compile Tk you should do the following things: + + (a) Check for a binary release. Pre-compiled binary releases are + available now for PCs and Macintoshes, and several flavors of + UNIX. Binary releases are much easier to install than source + releases. To find out whether a binary release is available for + your platform, check the home page for the Sun Tcl/Tk project + (http://www.sunlabs.com/research/tcl) and also check in the FTP + directory from which you retrieved the base distribution. + + (b) Make sure you have the most recent patch release. Look in the + FTP directory from which you retrieved this distribution to see + if it has been updated with patches. Patch releases fix bugs + without changing any features, so you should normally use the + latest patch release for the version of Tk that you want. + Patch releases are available in two forms. A file like + tk8.0p1.tar.Z is a complete release for patch level 1 of Tk + version 8.0. If there is a file with a higher patch level than + this release, just fetch the file with the highest patch level + and use it. + + Patches are also available in the form of patch files that just + contain the changes from one patch level to another. These + files have names like tk8.0p1.patch, tk8.0p2.patch, etc. They + may also have .gz or .Z extensions to indicate compression. To + use one of these files, you apply it to an existing release with + the "patch" program. Patches must be applied in order: + tk8.0p1.patch must be applied to an unpatched Tk 8.0 release + to produce a Tk 8.0p1 release; tk8.0p2.patch can then be + applied to Tk 8.0p1 to produce Tk 8.0p2, and so on. To apply an + uncompressed patch file such as tk8.0p1.patch, invoke a shell + command like the following from the directory containing this + file: + patch -p < tk8.0p1.patch + If the patch file has a .gz extension, it was compressed with + gzip. To apply it, invoke a command like the following: + gunzip -c tk8.0p1.patch.gz | patch -p + If the patch file has a .Z extension, it was compressed with + compress. To apply it, invoke a command like the following: + zcat tk8.0p1.patch.Z | patch -p + If you're applying a patch to a release that has already been + compiled, then before applying the patch you should cd to the + "unix" subdirectory and type "make distclean" to restore the + directory to a pristine state. + +Once you've done this, change to the "unix" subdirectory if you're +compiling under UNIX, "win" if you're compiling under Windows, or +"mac" if you're compiling on a Macintosh. Then follow the instructions +in the README file in that directory for compiling Tk, installing it, +and running the test suite. + +4. Getting started +------------------ + +The best way to get started with Tk is by reading one of the introductory +books. + +The subdirectory library/demos contains a number of pre-canned scripts +that demonstrate various features of Tk. See the README file in the +directory for a description of what's available. The file +library/demos/widget is a script that you can use to invoke many individual +demonstrations of Tk's facilities, see the code that produced the demos, +and modify the code to try out alternatives. + +5. Summary of changes in Tk 8.0 +------------------------------- + +Here is a list of the most important new features in Tk 8.0. The +release also includes several smaller feature changes and bug fixes. +See the "changes" file for a complete list of all changes. + + 1. Native look and feel. The widgets have been rewritten to provide + (nearly?) native look and feel on the Macintosh and PC. Many + widgets, including scrollbars, menus, and the button family, are + implemented with native platform widgets. Others, such as entries + and texts, have been modified to emulate native look and feel. + These changes are backwards compatible except that (a) some + configuration options are now ignored on some platforms and (b) you + must use the new menu mechanism described below to native look and + feel for menus. + + 2. There is a new interface for creating menus, where a menubar is + implemented as a menu widget instead of a frame containing menubuttons. + The -menu option for a toplevel is used to specify the name of the + menubar; the menu will be displayed *outside* the toplevel using + different mechanisms on each platform (e.g. on the Macintosh the menu + will appear at the top of the screen). See the menu demos in the + widget demo for examples. The old style of menu still works, but + does not provide native look and feel. Menus have several new + features: + - New "-columnbreak" and "-hideMargin" options make it possible + to create multi-column menus. + - It is now possible to manipulate the Apple and Help menus on + the Macintosh, and the system menu on Windows. It is also + possible to have a right justified Help menu on Unix. + - Menus now issue the virtual event <<MenuSelect>> whenever the + current item changes. Applications can use this to generate + help messages. + - There is a new "-direction" option for menubuttons, which + controls where the menu pops up revenues to the button. + + 3. The font mechanism in Tk has been completely reworked: + - Font names need not be nasty X LFDs: more intuitive names + like {Times 12 Bold} can also be used. See the manual entry + font.n for details. + - Font requests always succeed now. If the requested font is + not available, Tk finds the closest available font and uses + that one. + - Tk now supports named fonts whose precise attributes can be + changed dynamically. If a named font is changed, any widget + using that font updates itself to reflect the change. + - There is a new command "font" for creating named fonts and + querying various information about fonts. + - There are now officially supported C APIs for measuring and + displaying text. If you use these APIs now, your code will + automatically handle international text when internationalization + is added to Tk in a future release. See the manual entries + MeasureChar.3, TextLayout.3, and FontId.3. + - The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct, + and Tk_FreeFontStruct have been replaced with more portable + procedures Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont. + + 4. Application embedding. It is now possible to embedded one Tcl/Tk + application inside another, using the -container option on frame + widgets and the -use option for toplevel widgets or on the command + line for wish. Embedding should be fully functional under Unix, + but the implementation is incomplete on the Macintosh and PC. + + 5. Tk now works correctly with Safe-Tcl: it can be loaded into + safe interpreters using safe::loadTk. + + 6. Text widgets now allow images to be embedded directly in the + text without using embedded windows. This is more efficient and + provides smoother scrolling. + + 7. Buttons have a new -default option for drawing default rings in + a platform-specific manner. + + 8. There is a new "gray75" bitmap, and the "gray25" bitmap is now + really 25% on (due to an ancient mistake, it had been only 12% on). + The Macintosh now supports native bitmaps, including new builtin + bitmaps "stop", "caution", and "note", plus the ability to use + bitmaps in the application's resource fork. + + 9. The "destroy" command now ignores windows that don't exist + instead of generating an error. + +Tk 8.0 introduces the following incompatibilities that may affect Tcl/Tk +scripts that worked under Tk 4.2 and earlier releases: + + 1. Font specifications such as "Times 12" now interpret the size + as points, whereas it used to be pixels (this was actually a bug, + since the behavior was documented as points). To get pixels now, + use a negative size such as "Times -12". + + 2. The -transient option for menus is no longer supported. You can + achieve the same effect with the -type field. + + 3. In the canvas "coords" command, polygons now return only the + points that were explicitly specified when the polygon was created + (they used to return an extra point if the polygon wasn't originally + closed). Internally, polygons are still closed automatically for + purposes of display and hit detection; the extra point just isn't + returned by the "coords" command. + + 4. The photo image mechanism now uses Tcl_Channels instead of FILEs, + in order to make it portable. FILEs are no longer used anywhere + in Tk. The procedure Tk_FindPhoto now requires an extra "interp" + argument in order to fix a bug where images in different interpreters + with the same name could get confused. + + 5. The procedures Tk_GetFontStruct, Tk_NameOfFontStruct, + and Tk_FreeFontStruct have been removed. + +Note: the new compiler in Tcl 8.0 may also affect Tcl/Tk scripts; check +the Tcl documentation for information on incompatibilities introduced by +Tcl 8.0. + +6. Tcl/Tk newsgroup +------------------- + +There is a network news group "comp.lang.tcl" intended for the exchange +of information about Tcl, Tk, and related applications. Feel free to use +this newsgroup both for general information questions and for bug reports. +We read the newsgroup and will attempt to fix bugs and problems reported +to it. + +When using comp.lang.tcl, please be sure that your e-mail return address +is correctly set in your postings. This allows people to respond directly +to you, rather than the entire newsgroup, for answers that are not of +general interest. A bad e-mail return address may prevent you from +getting answers to your questions. You may have to reconfigure your news +reading software to ensure that it is supplying valid e-mail addresses. + +7. Mailing lists +---------------- + +A couple of Mailing List have been set up to discuss Macintosh or +Windows related Tcl issues. In order to use these Mailing Lists you +must have access to the internet. If you have access to the WWW the +home pages for these mailing lists are located at the following URLs: + + http://www.sunlabs.com/research/tcl/lists/mactcl-list.html + + -and- + + http://www.sunlabs.com/research/tcl/lists/wintcl-list.html + +The home pages contain information about the lists and an HTML archive +of all the past messages on the list. To subscribe send a message to: + + listserv@sunlabs.sun.com + +In the body of the message (the subject will be ignored) put: + + subscribe mactcl Joe Blow + +Replacing Joe Blow with your real name, of course. (Use wintcl +instead of mactcl if your interested in the Windows list.) If you +would just like to receive more information about the list without +subscribing but the line: + + information mactcl + +in the body instead (or wintcl). + +8. Tcl/Tk contributed archive +-------------------------- + +Many people have created exciting packages and applications based on Tcl +and/or Tk and made them freely available to the Tcl community. An archive +of these contributions is kept on the machine ftp.neosoft.com. You +can access the archive using anonymous FTP; the Tcl contributed archive is +in the directory "/pub/tcl". The archive also contains several FAQ +("frequently asked questions") documents that provide solutions to problems +that are commonly encountered by TCL newcomers. + +9. Support and bug fixes +------------------------ + +We're very interested in receiving bug reports and suggestions for +improvements. We prefer that you send this information to the +comp.lang.tcl newsgroup rather than to any of us at Sun. We'll see +anything on comp.lang.tcl, and in addition someone else who reads +comp.lang.tcl may be able to offer a solution. The normal turn-around +time for bugs is 3-6 weeks. Enhancements may take longer and may not +happen at all unless there is widespread support for them (we're +trying to slow the rate at which Tk turns into a kitchen sink). It's +very difficult to make incompatible changes to Tcl at this point, due +to the size of the installed base. + +When reporting bugs, please provide a short wish script that we can +use to reproduce the bug. Make sure that the script runs with a +bare-bones wish and doesn't depend on any extensions or other +programs, particularly those that exist only at your site. Also, +please include three additional pieces of information with the +script: + (a) how do we use the script to make the problem happen (e.g. + what things do we click on, in what order)? + (b) what happens when you do these things (presumably this is + undesirable)? + (c) what did you expect to happen instead? + +The Tcl/Tk community is too large for us to provide much individual +support for users. If you need help we suggest that you post questions +to comp.lang.tcl. We read the newsgroup and will attempt to answer +esoteric questions for which no-one else is likely to know the answer. +In addition, Tcl/Tk support and training are available commercially from +NeoSoft (info@neosoft.com), Computerized Processes Unlimited +(gwl@cpu.com), and Data Kinetics (education@dkl.com). + +10. Release organization +------------------------ + +Each Tk release is identified by two numbers separated by a dot, e.g. +3.2 or 3.3. If a new release contains changes that are likely to break +existing C code or Tcl scripts then the major release number increments +and the minor number resets to zero: 3.0, 4.0, etc. If a new release +contains only bug fixes and compatible changes, then the minor number +increments without changing the major number, e.g. 3.1, 3.2, etc. If +you have C code or Tcl scripts that work with release X.Y, then they +should also work with any release X.Z as long as Z > Y. + +Alpha and beta releases have an additional suffix of the form a2 or b1. +For example, Tk 3.3b1 is the first beta release of Tk version 3.3, +Tk 3.3b2 is the second beta release, and so on. A beta release is an +initial version of a new release, used to fix bugs and bad features +before declaring the release stable. An alpha release is like a beta +release, except it's likely to need even more work before it's "ready +for prime time". New releases are normally preceded by one or more +alpha and beta releases. We hope that lots of people will try out +the alpha and beta releases and report problems. We'll make new alpha/ +beta releases to fix the problems, until eventually there is a beta +release that appears to be stable. Once this occurs we'll make the +final release. + +We can't promise to maintain compatibility among alpha and beta releases. +For example, release 4.1b2 may not be backward compatible with 4.1b1, even +though the final 4.1 release will be backward compatible with 4.0. This +allows us to change new features as we find problems during beta testing. +We'll try to minimize incompatibilities between beta releases, but if a +major problem turns up then we'll fix it even if it introduces an +incompatibility. Once the official release is made then there won't +be any more incompatibilities until the next release with a new major +version number. + +Patch releases have a suffix such as p1 or p2. These releases contain +bug fixes only. A patch release (e.g Tk 4.1p2) should be completely +compatible with the base release from which it is derived (e.g. Tk +4.1), and you should normally use the highest available patch release. diff --git a/bitmaps/error.bmp b/bitmaps/error.bmp new file mode 100644 index 0000000..5a1331f --- /dev/null +++ b/bitmaps/error.bmp @@ -0,0 +1,8 @@ +#define error_width 17 +#define error_height 17 +static unsigned char error_bits[] = { + 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x16, 0x50, 0x00, + 0x2b, 0xa0, 0x00, 0x55, 0x40, 0x01, 0xa3, 0xc0, 0x00, 0x45, 0x41, 0x01, + 0x83, 0xc2, 0x00, 0x05, 0x45, 0x01, 0x03, 0xca, 0x00, 0x05, 0x74, 0x01, + 0x0a, 0xa8, 0x00, 0x14, 0x58, 0x00, 0xe8, 0x2f, 0x00, 0x50, 0x15, 0x00, + 0xa0, 0x0a, 0x00}; diff --git a/bitmaps/gray12.bmp b/bitmaps/gray12.bmp new file mode 100644 index 0000000..a0eafa1 --- /dev/null +++ b/bitmaps/gray12.bmp @@ -0,0 +1,6 @@ +#define gray12_width 16 +#define gray12_height 16 +static unsigned char gray12_bits[] = { + 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, + 0x00, 0x00, 0x88, 0x88, 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88, + 0x00, 0x00, 0x22, 0x22, 0x00, 0x00, 0x88, 0x88}; diff --git a/bitmaps/gray25.bmp b/bitmaps/gray25.bmp new file mode 100644 index 0000000..fdaef49 --- /dev/null +++ b/bitmaps/gray25.bmp @@ -0,0 +1,6 @@ +#define gray25_width 16 +#define gray25_height 16 +static unsigned char gray25_bits[] = { + 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, + 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22, + 0x88, 0x88, 0x22, 0x22, 0x88, 0x88, 0x22, 0x22}; diff --git a/bitmaps/gray50.bmp b/bitmaps/gray50.bmp new file mode 100644 index 0000000..1f9fbc0 --- /dev/null +++ b/bitmaps/gray50.bmp @@ -0,0 +1,6 @@ +#define gray50_width 16 +#define gray50_height 16 +static unsigned char gray50_bits[] = { + 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, + 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, + 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa}; diff --git a/bitmaps/gray75.bmp b/bitmaps/gray75.bmp new file mode 100644 index 0000000..f700b2c --- /dev/null +++ b/bitmaps/gray75.bmp @@ -0,0 +1,6 @@ +#define gray75_width 16 +#define gray75_height 16 +static unsigned char gray75_bits[] = { + 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, + 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd, + 0x77, 0x77, 0xdd, 0xdd, 0x77, 0x77, 0xdd, 0xdd}; diff --git a/bitmaps/hourglass.bmp b/bitmaps/hourglass.bmp new file mode 100644 index 0000000..bb1d8ad --- /dev/null +++ b/bitmaps/hourglass.bmp @@ -0,0 +1,9 @@ +#define hourglass_width 19 +#define hourglass_height 21 +static unsigned char hourglass_bits[] = { + 0xff, 0xff, 0x07, 0x55, 0x55, 0x05, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, + 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xc2, 0x0a, 0x03, 0x46, 0x05, 0x01, + 0x82, 0x0a, 0x03, 0x06, 0x05, 0x01, 0x02, 0x03, 0x03, 0x86, 0x05, 0x01, + 0xc2, 0x0a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, + 0xa2, 0x2a, 0x03, 0x66, 0x15, 0x01, 0xa2, 0x2a, 0x03, 0xff, 0xff, 0x07, + 0xab, 0xaa, 0x02}; diff --git a/bitmaps/info.bmp b/bitmaps/info.bmp new file mode 100644 index 0000000..801476e --- /dev/null +++ b/bitmaps/info.bmp @@ -0,0 +1,5 @@ +#define info_width 8 +#define info_height 21 +static unsigned char info_bits[] = { + 0x3c, 0x2a, 0x16, 0x2a, 0x14, 0x00, 0x00, 0x3f, 0x15, 0x2e, 0x14, 0x2c, + 0x14, 0x2c, 0x14, 0x2c, 0x14, 0x2c, 0xd7, 0xab, 0x55}; diff --git a/bitmaps/questhead.bmp b/bitmaps/questhead.bmp new file mode 100644 index 0000000..17b2929 --- /dev/null +++ b/bitmaps/questhead.bmp @@ -0,0 +1,9 @@ +#define questhead_width 20 +#define questhead_height 22 +static unsigned char questhead_bits[] = { + 0xf8, 0x1f, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, 0xeb, 0xaf, 0x00, + 0xf5, 0x5f, 0x01, 0xfb, 0xbf, 0x00, 0x75, 0x5d, 0x01, 0xfb, 0xbe, 0x02, + 0x75, 0x5d, 0x05, 0xab, 0xbe, 0x0a, 0x55, 0x5f, 0x07, 0xab, 0xaf, 0x00, + 0xd6, 0x57, 0x01, 0xac, 0xab, 0x00, 0xd8, 0x57, 0x00, 0xb0, 0xaa, 0x00, + 0x50, 0x55, 0x00, 0xb0, 0x0b, 0x00, 0xd0, 0x17, 0x00, 0xb0, 0x0b, 0x00, + 0x58, 0x15, 0x00, 0xa8, 0x2a, 0x00}; diff --git a/bitmaps/question.bmp b/bitmaps/question.bmp new file mode 100644 index 0000000..ceba2ab --- /dev/null +++ b/bitmaps/question.bmp @@ -0,0 +1,10 @@ +#define question_width 17 +#define question_height 27 +static unsigned char question_bits[] = { + 0xf0, 0x0f, 0x00, 0x58, 0x15, 0x00, 0xac, 0x2a, 0x00, 0x56, 0x55, 0x00, + 0x2b, 0xa8, 0x00, 0x15, 0x50, 0x01, 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, + 0x0b, 0xa0, 0x00, 0x05, 0x60, 0x01, 0x0b, 0xb0, 0x00, 0x00, 0x58, 0x01, + 0x00, 0xaf, 0x00, 0x80, 0x55, 0x00, 0xc0, 0x2a, 0x00, 0x40, 0x15, 0x00, + 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x40, 0x01, 0x00, + 0xc0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x80, 0x01, 0x00, 0xc0, 0x02, 0x00, + 0x40, 0x01, 0x00, 0xc0, 0x02, 0x00, 0x00, 0x01, 0x00}; diff --git a/bitmaps/warning.bmp b/bitmaps/warning.bmp new file mode 100644 index 0000000..7925440 --- /dev/null +++ b/bitmaps/warning.bmp @@ -0,0 +1,5 @@ +#define warning_width 6 +#define warning_height 19 +static unsigned char warning_bits[] = { + 0x0c, 0x16, 0x2b, 0x15, 0x2b, 0x15, 0x2b, 0x16, 0x0a, 0x16, 0x0a, 0x16, + 0x0a, 0x00, 0x00, 0x1e, 0x0a, 0x16, 0x0a}; @@ -0,0 +1,4129 @@ +This file summarizes all changes made to Tk since version 1.0 was +released on March 13, 1991. Changes that aren't backward compatible +are marked specially. + +SCCS: @(#) changes 1.252 97/11/25 08:31:19 + +3/16/91 (bug fix) Modified tkWindow.c to remove Tk's Tcl commands from +the interpreter when the main window is deleted (otherwise there will +be dangling pointers to the non-existent window). + +3/16/91 (bug fix) Modified tkColor.c not to free black or white colors: +some X servers get upset at this. + +3/18/91 (bug fix) Modified tkShare.c to fix bug causing "DeleteGroup +couldn't find group on shareList" panic. + +3/18/91 (bug fix) Several changes to tkListbox.c and tkScrollbar.c to +handle listboxes (and scrollbars) with zero total entries in them. + +3/22/91 (bug fix) Fixed a few ='s in tkListbox.c that should be ==. + +3/22/91 (bug fix) Fixed error in main.c that caused BadWindow errors +in some cases where wish scripts invoke "destroy .". + +3/23/91 (new feature) Added Tk_CancelIdleCall to remove Tk_DoWhenIdle +handler. + +3/23/91 (bug fix and new feature) Added -name option to main.c, made +it more clever about choosing name (was always using the name "wish" +on most Unix systems). + +3/23/91 (new feature) Added TK_CONFIG_STRING option to Tk_ConfigureWidget, +used it to malloc strings for various widget options that used to be +Tk_Uid's (e.g. button text, message strings, etc.). Eliminates core +leaks when values change in continuous non-repeating fashion. + +3/29/91 (new feature) Added Tk_Preserve, Tk_Release, and +Tk_EventuallyFree procedures to help manage widget records and avoid +premature memory free-ing. + +4/4/91 (bug fix) Fixed problem in tkWm.c where top-level window geometry +wasn't tracking correctly when wm-induced size change also changed window +position (e.g. menus wouldn't be displayed at the right places). + +4/5/91 (new feature) Added "invoke" option to widget command for buttons, +check buttons, and radio buttons. + +4/5/91 (new feature) Added "unpack" option to "pack" command. + +4/5/91 (bug fix) Changed tkPack.c to use new Tk_Preserve code and be +more careful about window deletions that occur while repacking is in +progress. + +4/6/91 (bug fix) Major overhaul of deletion code in all widgets to use +Tk_Preserve and Tk_Release. Should fix many problems. + +4/6/91 (bug fix) Changed "winfo children" to generate correct lists +when child names have embedded spaces. + +4/6/91 (new feature) Added "screenheight" and "screenwidth" options to +"winfo". + +4/18/91 (bug fix) Binding mechanism didn't correctly handle very long +%-substitutions in commands (e.g. long path names) and caused memory +to be overwritten. Modified tkBind.c to fix. + +---------------------- Release 1.1, 4/18/91 ------------------------- + +4/19/91 (bug fix) Inconsistent ICCCM handling of coordinates of reparented +windows causes windows to gradually walk south when moved or resized. +Fixed tkWm.c to patch around the problem. + +---------------------- Release 1.2, 4/24/91 ------------------------- + +4/26/91 (new feature) Added -geometry and -display switches to wish. +Also wrote wish manual entry. + +5/3/91 (bug fix) Fixed bug in tkListbox.c that caused garbage to appear +at right edge of window when strings were to large to fit in window. + +5/3/91 (bug fix) Fixed bug in tkListbox.c where topIndex wasn't getting +updated when elements were deleted: tended to cause errors in +communication with scrollbars. + +5/16/91 (bug fix) Fixed bug in tk3d.c, which caused core dumps when +consecutive points in a polygon were the same (happened with some +configurations of radio buttons, for example). + +5/16/91 (bug fix) Fixed main.c to allow stdin to be redirected. + +6/1/91 (bug fix) Make sure that pointers are never used after being +freed. + +6/15/91 (bug fix) Fixed bug in tkBind.c that caused current binding +values to not always be printed correctly. + +6/15/91 (bug fix) Make sure that interpreters are always unregistered +when their main windows are deleted, and make wish delete the main +window before exiting. + +8/21/91 (misfeature correction) Automatically set source of window +position to "user" in "wm geometry" command, unless it has been +explicitly set to "program". + +9/5/91 (bug fix) Modified option code to accept '#' as a comment +character in .Xdefaults files, in addition to '!'. + +9/10/91 (misfeature correction) Changed binding mechanism so that +numeric %-sequences are output in decimal instead of hex. + +9/19/91 (bug fix) Fixed bug in Tk_DoOneEvent(1) where it wasn't +checking files and X connections properly so it missed events. + +10/6/91 (new feature) Reorganized tkBind.c to provide generic "binding +table" structure, which can be used to create bindings on items in +canvases as well as windows. + +10/6/91 (new feature) Upgraded buttons and menus to use new tracing +code in Tcl 6.0. Allows radio buttons and check buttons to both set +and clear themselves when associated variable changes. + +10/17/91 (bug fix) Fixed 2 bugs in listboxes: accidentally advanced the +selection when new entries were inserted in the listbox after the location +of the selected item(s), and goofed up on redisplay if selected item +was deleted and then selection was immediately lost. + +10/27/91 (bug fix) "pack unpack" wasn't telling Tk that it no longer +manages window; this led to core dumps in some situations. + +10/31/91 (reorganization) Renamed manual entries so that they are no +more than 14 characters in length. + +10/31/91 (reorganization) Changed tk.h and tkInt.h so that tkInt.h +doesn't needed to be included by tk.h. + +11/3/91 (portability improvement) Eliminated use of "class" as a variable +name, since it's a reserved word in C++. + +11/7/91 (reorganization) Many changes to upgrade for Tcl 6.1 including +use of Tcl hash tables instead of separate "Hash_" module. The "lib" +subdirectory is no longer needed in Tk. + +---------------------- Release 1.3, 11/7/91 ------------------------- + +11/24/91 (bug fix) Fixed bug causing occasional errors if existing bindings +are modified (FindSequence in tkBind.c forget to set *maskPtr). + +11/24/91 (bug fix) Used wrong hash table in Tk_GetColorByValue. Could +cause new entries to get created unnecessarily. + +12/2/91 (bug fix) Changed "bind" code to put backslashes in front of +special characters (e.g. [ or \) that appear in %-replacements, so that +they can be parsed cleanly. + +12/10/91 (bug fix) Manual entries had first lines that caused "man" program +to try weird preprocessor. Added blank comment lines to fix problem. + +1/2/92 (documentation cleanup) Changed manual entries for Tk_GetBitmap +and the like to make it more clear that the argument must be a Tk_Uid +and not a string. + +1/2/92 (bug fix) Fixed problem where scrollbars that were very short or +very narrow (too small to hold both arrows) could cause negative values +in calls to XClearArea, which crashed some servers. + +1/2/92 (bug fix) Fixed bug in TkMeasureChars occurring when maxChars +is 0. Occasionally affected things like message window geometry. + +1/3/92 (new feature) Added procedures Tk_GetJustify, Tk_GetAnchor, +Tk_GetCapStyle, and Tk_GetJoinStyle, plus support for these things +in Tk_ConfigureWidget. + +---------------------- Release 1.4, 1/10/92 ------------------------- + +1/12/92 (bug fix) TkMenubutton.c wasn't cleaning up mbPtr->varName +properly during menubutton cleanup if an error occurred during +menubutton creation. + +1/19/92 (bug fix) Fixed off-by-one bug in tkListbox.c that caused +scrollbars to display a slider that was too large. + +2/10/92 (bug fix) Tk_CreateFileHandler didn't correctly handle case +where new mask was specified for existing handler. + +2/13/92 (bug fix) Tk_DeleteAllBindings wasn't correctly removing +bindings from the pattern table: only did the removal for the +first pattern in a pattern list. + +2/15/92 (new feature) Added procedures Tk_DefineBitmap and +Tk_SizeOfBitmap. Tk_GetBitmapFromData is now considered obsolete +and probably shouldn't be used anymore. Tk_GetBitmapFromData +is now implemented by calling Tk_DefineBitmap and Tk_GetBitmap. + +2/15/92 (new feature) Added "curselection" and "select clear" options +to widget command for listboxes. + +2/15/92 (new feature) Added Tk_3DBorderColor procedure. + +2/17/92 (relaxed limitations) Changed scrollbars so they no longer limit +the slider position to lie within the object's range: can scroll off the +end of an object, if the object permits it. Changed listboxes and +entries to explicitly prevent viewing off the ends. Also relaxed +listbox index checks so that out-of-range indices are automatically +adjust to fit within the listbox range. + +2/19/92 (bug fix) tkWindow.c tended to leave half-created windows around +if a new window's name was found to be in use already. Fixed to clean +them up. + +2/22/92 (new feature) Added -anchor, -bitmap, -height, -textvariable, +-width options to labels, buttons, check buttons, menu buttons, and radio +buttons. This means that (a) size can be controlled better, (b) bitmaps +can be displayed in any buttons, (c) the position of the text within the +button can be controlled, and (d) a button can be made to display the value +of a variable, continuously updating itself. Also changed -selector option +so that if it's specified as an empty string then no selector is drawn +for the button. + +2/22/92 (new feature) Changed menus to support bitmaps in menu entries: +added new -bitmap option for entries. + +2/26/92 (bug fix) "after" command, when invoked with just one argument, +called Tk_Sleep rather than registering a timer handler and looping on +Tk_DoOneEvent. As a result, it caused the application to become non- +responsive to X events during the sleep. Changed to use a Tk_DoOneEvent +loop so that it is responsive. + +2/26/92 (bug fix) Tk's main program didn't map the main window until +after the startup script returned. Changed to map the window as a +do-when-idle handler, so that scripts can cause the window to be +mapped immediately with a call to "update" or "after". + +2/28/92 (bug fix) "wm withdraw" wasn't working if invoked before window +was originally mapped: window got mapped anyway. Fixed so that the +window doesn't get mapped as long as it's withdrawn. + +2/29/92 (new feature) Can use "focus none" to clear input focus. + +2/29/92 (bug fix) Fixed tkEvent.c to generate SubstructureNotify events +properly. These weren't being generated previously. + +2/29/92 (bug fix) Fixed entries so that newline characters can be properly +displayed (as `\x0a'). Had to change interface to TkDisplayChars in order +to do this (added flags argument). + +2/29/92 (bug fix) Change Tk not to update size and position of top-level +windows directly during calls like Tk_ResizeWindow. Instead, wait until +actual event is received. This makes updates happen at same time as +callbacks. + +3/6/92 (bug fix) TkMenubutton.c was dumping core when a menubutton was +pressed at a time when there was no associated menu for the button. + +3/6/92 (new feature) Added Tk script library directory with official +Tk initialization file "tk.tcl". Other procedures used by Tk are in +other files. Tk procedures and variables all have names starting +with "tk_". Also added Wish startup script "wish.tcl", which sources +both the Tk and Tcl startup scripts. This means that things like +auto-loading and abbreviation expansion are now available in wish. +Added new variables tk_library, tk_priv, and tk_version. + +3/6/92 (new feature) It's now possible to set bindings for whole +classes by using the class name in the bind command. For example, +"bind Button <Enter> {puts stdout Hi!}" will cause a message to be +printed whenever any mouse button is entered. Can also use "all" +to set bindings for all widgets. Widget-specific bindings override +class bindings which override "all" bindings. + +3/6/92 (reorganization) Changed buttons (all flavors) and listboxes to +eliminate all hard-wired behavior. Instead, default behavior is set +by class bindings in tk.tcl. Also set up class bindings for menus, +menubuttons, and entries, which previously had no default behavior at +all. Scrollbars and scales still have hard-wired behavior that can't +be overridden. + +3/7/92 (look-and-feel change) Changed listboxes and entries and menus +to use button 2 for scanning instead of button 3. This is more consistent +with the official Motif use of button 2 for dragging. + +3/10/92 (new features) Added more options to "winfo" command: screencells, +screendepth, screenmmheight, screenmmwidth, and screenvisual. + +3/13/92 (bug fix) Event sharing mechanism (tkShare.c) wasn't checking +to see whether window was mapped before sharing events with it. + +3/16/92 (bug fix) Tk_SetInternalBorderWidth was passing wrong window to +geometry-management procedures, causing core-dumps when menu buttons +had their border widths changed. + +3/16/92 (bug fix) Menus were setting their geometry directory rather +than using Tk_GeometryRequest mechanism. + +3/17/92 (new feature) Added -cursor option to all widgets to set the +active cursor for the widget. Also added TK_CONFIG_ACTIVE_CURSOR +configure type. + +3/18/92 (new feature) Implemented generalized screen coordinates to +allow resolution-independent specification in many cases (but pixel- +based coordinates are still OK). Added Tk_GetScreenMM(), +Tk_GetPixels(), new configure types TK_CONFIG_SCREEN_MM and +TK_CONFIG_PIXELS. Changed widgets to use this new configure types +wherever possible (a few of the more complex cases still haven't +been taken care of yet). Added "pixels" and "fpixels" options to +"winfo" command. + +3/18/92 (new feature) First cut at canvas widgets is done and part of +the official Tk now. Canvases display text and structured graphics, +and allow you to bind commands to events related to the text and +graphics. + +3/21/92 (new feature) Added new "place" command. It implements a +new geometry manager that provides fixed placement, rubber-sheet +placement, and combinations of the two. Eliminated the commands +"move", "resize", and "map" that were provided by main.c but never +officially supported; the placer provides all of this functionality. + +3/23/92 (bug fix) Fixed bug in tkWm.c where top-level windows were +occasionally not being given the right size. The problem occurred +when a string of resizes happened all in a row (such as deleting all +the windows in an application and then recreating them). + +3/23/92 (new feature) Added Tk_CoordsToWindow procedure and +"winfo containing" command. These may be used to locate the window +containing a given point. + +3/28/92 (new feature) Added "-exportselection" option to listboxes, +so that listbox selection need not necessarily be the X selection. + +4/12/92 (bug fix) Changed menu buttons to store name of menubutton +in the associated variable, rather than the name of the menu. This +is necessary in order to allow several menu buttons to share the +same menu. +*** POTENTIAL INCOMPATIBILITY *** + +4/12/92 (bug fix) Fixed core dump that occurred in tkError.c when +removing the first error record from the error list. + +4/15/92 (bug fix) Fixed bug in tkBind.c that prevented <KeyPress-1> +event specifications from being processed correctly: the "1" was +treated as a button name rather than a keysym. + +4/18/92 (new feature) Added Tk_DefineCursor and Tk_UndefineCursor +procedures. + +4/18/92 (new feature) Major revision to listboxes. Can now scroll and +scan in both x and y, plus -exportselection option allows selection not +to be exported. The "view" widget command has been replaced by "xview" +and "yview", and the "scan" widget command has a new syntax. +*** POTENTIAL INCOMPATIBILITY *** + +4/18/92 (new feature) Added -exportselection option to entries, so you +can select whether you want the entry selection to be the X selection +or not. + +4/24/92 (new features) Added TK_CONFIG_CUSTOM type to Tk_ConfigureWidget, +plus added new flags TK_CONFIG_NULL_OK, TK_CONFIG_DONT_SET_DEFAULT, +and TK_CONFIG_OPTION_SPECIFIED. Several other new types, such as +TK_CONFIG_CAP_STYLE, were also added as part of implementing canvases. + +4/29/92 (bug fix) Changed "-selector" default for menus to have separate +values for mono and color. + +4/30/92 (bug fix) Fixed bug in tkListbox.c where it occasionally generated +bogus scroll commands (last index less than first). + +4/30/92 (reorganization) Moved demos directory to "library/demos". + +---------------------- Release 2.0, 5/1/92 ------------------------- + +5/2/92 (bug fix) Fixed problem in tkListbox.c where it was doing too many +redisplays after repeated insertions. Also reduced number of invocations +of scrollbar commands. + +5/7/92 (portability improvement) Changed main.c not to use TK_EXCEPTION +flag; it isn't needed and it causes problems on some systems. + +5/9/92 (bug fix) Plugged core leaks in tkListbox.c and tkBind.c + +5/9/92 (bug fix) TkBind.c was accidentally deleting bindings during +attempts to print non-existent bindings. + +5/11/92 (bug fix) Maximum name length for applications (name used in +"send" commands) was too short (only 20); increased to 1000. Also +fixed bug related to over-long names that caused core dumps. + +5/13/92 (bug fix) tkShare.c was using a dangling pointer if a share +group was deleted as a side-effect of a shared event. + +5/13/92 (bug fix) Various initialization and core leak problems in +tkGC.c, tkSend.c, tkMenu.c, tkEvent.c, tkCanvas.c, tkCanvPoly.c, +tkCanvLine.c, tkListbox.c, tkEntry.c. + +5/13/92 (bug fix) Empty entries could be scanned off the left edge, +displaying a garbage character. + +5/13/92 (bug fix) Fixed a few problems with window manager interactions, +such as tendency for windows to spontaneously shrink in size. By no +means are all of the problems fixed, though. + +5/13/92 (performance optimization) Changed Tk_GeometryRequest not to +invoke geometry manager unless requested size has changed. + +---------------------- Release 2.1, 5/14/92 ------------------------- + +5/1/92 (new features) Added flags like TK_IDLE_EVENTS to Tk_DoWhenIdle, +plus added "idletasks" option to "update" command. Tk_DoWhenIdle arguments +look different now, but the change should be upward-compatible. + +5/17/92 (new feature/bug fix) Added support for VisibilityNotify events +to the "bind" command. For some reason they weren't supported previously. + +5/17/92 (new feature) Added "tkwait" command. + +5/17/92 (new feature) Added "grab" command. + +5/17/92 (new feature) Added "-width" option to messages. Also changed +messages to use the computed (i.e. desired) line length when displaying, +not the actual width of the window. + +5/17/92 (bug fixes) Did some more fiddling with tkWm.c in the hopes +of improving window manager interactions. Now there won't be more than +one configure request outstanding to the wm at a time. + +5/17/92 (bug fix) Arrowheads on canvas lines weren't being translated +or scaled correctly. + +5/20/92 (bug fix) Page-mode scrolling didn't work correctly for canvases +(wrong windowUnits was passed to scrollbars). + +5/20/92 (bug fix) Changed scrollbars not to lose highlight when pointer +leaves window with button down. Also changed redisplay to double-buffer +for smoother redraws. + +5/21/92 (new feature) Added "gray50" and "gray25" as predefined bitmaps. + +5/22/92 (new feature) Buttons can now be disabled using the "-state" and +"-disabledforeground configuration options. The "activate" and "deactivate" +widget commands for buttons are now obsolete and will go away soon. +Please change Tcl scripts not to use them. + +5/23/92 (new feature) Entries can now be disabled using the "-state" +config option. Also improved class bindings for entries to keep the +cursor visible in the window when operations occur. Also made slight +improvements in the way redisplay is done. + +5/23/92 (new feature) Added "-textvariable" option to entries so that +the text in an entry can be tied to the value of a global variable in +a fashion similar to buttons. + +5/27/92 (new feature) Added "-textvariable" and "-anchor" options to +messages. + +5/28/92 (new feature) Added "-padx" and "-pady" and "-underline" options +to menubuttons. + +5/28/92 (feature change) Changed "-width" and "-height" options on +all flavors of buttons and menubuttons so that they are orthogonal +to "-padx" and "-pady". It used to be that -width overrode -padx +(no padding). Now they accumulate. + +5/29/92 (new feature) Added "-disabledforeground" option to menus and +all flavors of buttons (can specify color for disabled things rather +than just using stipple to gray out). + +5/29/92 (new features) Added many new options to menu entries: +-activebackground, -background, -font, -state, -underline. The +"disable" and "enable" widget commands for menus are now obsolete +and will go away soon. Please change Tcl scripts not to use them. + +5/29/92 (new features) Added "atom" and "atomname" options to "winfo" +command. + +5/29/92 (new feature) Wrote tk_listboxSingleSelect procedure, which +can be used to change listbox behavior so that only a single item is +selected at once. + +6/1/92 (new feature) Added new modifier names "Meta" and "Alt" for +"bind" command. + +6/3/92 (new feature) Added "winfo toplevel" command. + +6/3/92 (new feature) Made several changes for greater Motif compliance, +including: + - menu retention if you click and release in the menu button, + - keyboard traversal of menus (see traversal.man) + - no widget flashing if you set $tk_strictMotif to 1 + +6/15/92 (bug fix) Fixed problem in tkBind.c where command string for a +binding could get reallocated while the command was being executed (e.g. +bindings that delete or change themselves). + +6/15/92 (bug fix) Don't allow "tabWidth" field to become zero in tkFont.c: +can cause core dumps for fonts that don't enough information to compute +tab widths. + +6/19/92 (bug fix) Fixed bug in binding mechanism that caused structure- +related events to be reported both to the correct window and its parent. + +7/14/92 (bug fix) Changed tkColor.c not to free colors for visual types +StaticGray or StaticColor. + +7/15/92 (new feature) Text widgets now exist. They display any number of +lines of text with a variety of display formats, and include hypertext +facilities. See the manual page for details. + +7/20/92 (bug fix) If a top-level window was put in the iconic state to +begin with, it could be deiconified with "wm deiconify .foo" until it had +first been deiconified by hand from the window manager. Tk was getting +confused and thought the window was mapped when it wasn't. + +7/29/92 (bug fix) Don't permit rectangles or ovals to have zero-sized +dimensions. Round up to at least one pixel. + +7/29/92 (new features) Major upgrade to canvases: + - new item types: arc, window, bitmap + - added Bezier spline support for lines and polygons + - rectangles and ovals now center their outlines on the shape, + rather than drawing them entirely inside the shape + - new "coords" and "bbox" widget commands + - new "-tags" option for all item types. + - new "-confine" option to prevent scrolling off edge of canvas. + +8/6/92 (new feature) Added "-width" and "-height" options to frames. +The "-geometry" option is now obsolete and should be removed from Tcl +scripts: it may go away in the future. + +8/7/92 (bug fix) Error messages in Tk_ParseArgv were sometimes including +the option name where they should have included its value. + +---------------------- Release 2.2, 8/7/92 ------------------------- + +8/7/92 (bug fix) Changed tkCanvas.c to be more conservative in the area +it passes to XCopyArea. + +8/8/92 (bug fix) Fixed bug in tkTextDisp.c that sometimes caused core +dumps when text views changed (e.g. typing return on last line of screen). + +8/8/92 (bug fix) Fixed bug in menu.tcl that caused errors when using +keyboard to traverse over separator menu entries. + +8/10/92 (bug fix) Changed to use OPEN_MAX instead of MAX_FD to compute +maximum # of open files. + +8/10/92 (bug fix) Canvases weren't updating scrollbars on window size +changes. They also weren't recentering canvases on window size changes. + +8/10/92 (bug fix) There were still a few places where commands were being +invoked at local level instead of global level (e.g. commands associated +with buttons and menu entries). + +8/10/92 (bug fix) TkBind.c used to ignore explicit shift modifiers for +all keys (i.e. <Shift-Tab> was treated the same as <Tab>). Modified to +allow explicit request for shift modifier, like <Shift-Tab>. + +8/13/92 (feature change) Changed default fonts to request "Adobe" fonts +explicitly. + +8/16/92 (bug fixes) Modified tkCanvArc.c and tkTrig.c to increase slightly +the bounding boxes for arcs, in order to make sure that proper redisplay +occurs when arcs are moved (little turds were getting left behind). + +8/16/92 (bug fix) Modified tkCanvas.c not to redraw at all if the redisplay +area is off the screen. Also, only do a background clear for the portion +of the redraw area that is on-screen. Also, reduced size of off-screen +pixmaps used for redisplaying, which speeds up redisplay in some cases. + +8/19/92 (bug fix) Canvases that were taller than wide were not being +redisplayed properly. + +8/20/92 (new feature) Added Tk_CreateGenericHandler procedure for trapping +all X events (useful for tracing, watching non-Tk windows, etc.). + +8/21/92 (bug fix) Widgets weren't always being notified when they got +the focus back again (the problem had to do with grabs and menus in +particular). + +8/21/92 (new feature) Added "-state" option to scale widgets. + +8/22/92 (new feature) Changed tkBitmap.c to allow tilde-substitution +to occur in bitmap file names. + +---------------------- Release 2.3, 8/24/92 ------------------------- + +8/27/92 (bug fix) Changes to -activebackground and -activeforeground options +for menubuttons were being lost. + +8/27/92 (bug fix) Entries were selecting last character when a B1-drag +occurred past the right edge of the text. + +8/28/92 (bug fix) Fixed bug in canvases where a grab during a button +press caused the canvas state to lock up so that it didn't select a +new current item. + +9/7/92 (bug fix) Changed tkMenu.c to accept numerical menu indices that +are out of range; now it just rounds them off to the nearest existing +entry. + +9/7/92 (bug fix) Fixed bug in tkTextDisp.c that caused core dumps when +invoking "yview -pickplace" widget command on texts that are too small +to hold any lines at all. + +9/11/92 (bug fix) Fixed bug in tkTextDisp.c that caused core dumps +when adding tags to non-existent lines. + +9/11/92 (bug fix) Line items in canvases didn't permit an empty fill +color (i.e. couldn't make them transparent). + +9/14/92 (reorganization) Changed manual entries to use .1, .3, and .n +extensions. Added "install" target to Makefile to suggest how Tk should +be installed. + +9/16/92 (bug fix) Changed tkSend.c to always specify the root window of +screen 0 rather than using DefaultRootWindow. DefaultRootWindow doesn't +always go to screen 0 on displays with multiple screens, which can result +in send's not being possible between the screens. + +9/18/92 (new feature) Added three new options to "wm" command: "protocol", +"client", and "command". These provide support for window manager protocols +such as WM_DELETE_WINDOW and WM_TAKE_FOCUS, plus support for the +WM_CLIENT_MACHINE and WM_COMMAND properties. + +9/30/92 (new feature) Implemented color model support, including +"tk colormodel" command and Tk_GetColorModel and Tk_SetColorModel +procedures. These allow you to force mono operation even on a color +display. Also changed color allocation not to give errors when colors +run out, but just to switch to a mono color model. + +10/1/92 (bug fixes) Fixed two bugs in tkTextBTree.c that caused core dumps +during text deletion. + +10/5/92 (bug work-around) Changed tkColor.c to ignore errors when freeing +colors. This is needed to work around improper reference count management +for colormap entries under X11/NeWS. + +10/7/92 (new feature) Added support for different visual types, including +procedures Tk_SetWindowVisual and Tk_SetWindowColormap, plus macros +Tk_Visual, Tk_Depth, and Tk_Colormap. The code for this was contributed +by Paul Mackerras. + +10/7/92 (new feature) Added Tk_IsTopLevel macro. + +10/12/92 (bug fix) Fixed bug in tk.tcl that caused torn-off menus with +cascaded children not to track mouse motion correctly (the cascade +switched in response to mouse motions within the cascaded child). + +10/12/92 (new feature) Major changes to focus handling: +(a) Tk watches FocusIn and FocusOut events for focus changes, not Enter + and Leave, so it will work better with explicit-focus-model window + managers (e.g. mwm in default mode). +(b) Tk generates FocusIn and FocusOut events for the focus window now. + The old procedural interface (via Tk_CreateFocusHandler) is obsolete + and is no longer used inside Tk. It is still supported for + compatibility, but won't be for long. You should change your code + to use FocusIn and FocusOut events instead. +(c) The model for FocusIn and FocusOut events is different than the + one described in Xlib documentation. See the "focus" manual entry + for details. +(d) If there is no input focus then keyboard events are discarded. They + used to be directed to the mouse pointer window, although this wasn't + documented. The focus now defaults to the root window. +*** POTENTIAL INCOMPATIBILITY *** + +10/15/92 (bug fix) Fixed text items in canvases where they didn't +display the insertion cursor if the item had no characters in it. + +10/26/92 (bug fix) Fixed bug in tkSelect.c that occasionally caused +BadWindow X protocol errors when retrieving the selection. Tk wasn't +making sure that a window existed before using it to retrieve the +selection. + +10/30/92 (feature change) Changed canvases so that if the scroll region +is smaller than the window and -confine is on, the scroll region isn't +forced to be centered in the window; it can be anywhere that meets the +confinement restrictions. + +11/2/92 (new feature) Added "winfo exists" command. + +11/5/92 (new feature) Changed DoWhenIdle handlers so that if a new +when-idle handler is created as a side-effect of another when-idle +handler, the new handler isn't invoked until Tk has first checked +for other events to process. + +11/6/92 (bug fixes, new features) Major overhaul of window manager +interface: +(a) Tk should now work with virtual-root window managers; +(b) windows will now place more accurately on the screen and stay where + they're supposed to; +(c) size changes handled more reliably; +(d) code now works robustly in the face of withdrawals followed + immediately by deiconifications. +(e) Added new procedure Tk_GetVRootInfo and new options to "winfo" command: + vrootx, vrooty, vrootwidth, vrootheight. +(f) Added "overrideredirect" option to "wm". +(g) Fixed bug where change in width-only via "wm geom" didn't always work + (min and max window sizes weren't being set properly for the wm). + +11/6/92 (bug fixes) Modified menus so that they work correctly with +virtual root window managers. Also fixed bug where menus didn't move +along with their associated windows, so that the menu popped up at +the old location of the window rather than its new location. + +11/9/92 (new constraint) Made it illegal to give windows names that +start with upper-case letters, since such names will goof up the +option database by appearing to be classes rather than names. +*** POTENTIAL INCOMPATIBILITY *** + +11/10/92 (new feature) Added Postscript output to canvases. + +11/13/92 (bug fix) Changed default for maximum size passed to window +manager from 1000000 (which causes some wm's to make windows too large +when "maximized") to the size of the display. + +11/14/92 (feature change) Major overhaul of menubuttons and pull-down +menus. Removed event-sharing code, including Tk_ShareEvents and +Tk_UnshareEvents. The -variable option for menubuttons has been +removed,and the "post" and "unpost" widget commands for menubuttons +no longer exist. The "post" widget command for menus no longer +allows a group option. The procedure tk_menus has been replaced +with a new procedure, tk_menuBar, which has a slightly different +interface. +*** POTENTIAL INCOMPATIBILITY *** + +11/20/92 (new features, feature changes) Major overhaul of grab +mechanism to produce more correct event streams. Also changed Tcl +commands to require explicit window for grab releases (makes it +possible for grabs to work on multiple displays simultaneously). +The old "grab none" command no longer exists, but new options +have been added: "current", "release", "set", and "status". +*** POTENTIAL INCOMPATIBILITY *** + +11/20/92 (new feature) Use TK_LIBRARY environment variable to set library +directory location, if it is defined. Otherwise fall back on usual +compiled-in value. + +11/25/92 (bug fix) "wm grid" command was using wrong window. + +11/29/92 (bug fix) Fixed core dump that occurred when trying to use +placer on top-level windows: return error instead. + +11/29/92 (bug fix) Selection retrieval wasn't making sure that the window +on whose behalf selection is being retrieved actually exists. + +12/3/92 (new feature) Added support for Mode_switch key to support the +full ISO character set. Also added event handlers for MappingNotify +events so that Tk updates itself in response to keycode and modifier +changes. + +12/6/92 (bug fix) Ignore recursive attempts to destroy window. + +12/9/92 (new demos) Added "tcolor" and "rmt" demos. + +12/10/92 (new features) Added "yposition" widget command for menus, +changed "delete" widget command to take an optional second index, +and changed -command option for cascade entries so that it is +invoked when the entry is activated rather than when it is invoked. +*** POTENTIAL INCOMPATIBILITY *** + +12/12/92 (implementation change) Changed the procedures Tk_FreeBitmap, +Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeCursor, Tk_NameOfCursor, and +Tk_FreeGC to require an addition Display argument. This is needed for +Tk to function correctly when an application has windows on multiple +displays. +*** POTENTIAL INCOMPATIBILITY *** + +12/12/92 (new feature) Started creating a test suite. Right now it +only has a few tests. + +12/12/92 (new feature) Modified the packer so that a window can be +packed in descendants of its parent (used to be restricted to the +parent alone). This makes it possible to hide extra windows used +for geometry management. Also, can use generalized screen distances +in the "pack" command. + +12/16/92 (feature change) Boolean options such as -exportselection now +print as 0/1 rather than true/false (both the default and current values +print this way). This makes it easier to use these values in expressions. +*** POTENTIAL INCOMPATIBILITY *** + +12/16/92 (name change) The classes "RadioButton" and "CheckButton" have +been renamed "Radiobutton" and "Checkbutton" for consistency. From now +on widget class names will have exactly one capital letter. +*** POTENTIAL INCOMPATIBILITY *** + +12/16/92 (new feature) Added -setgrid option to listboxes. + +12/16/92 (new feature) The "destroy" command, and the "delete" widget +command for canvases, now accept any number of arguments, including +zero. + +12/16/92 (new feature) Changed internal TkBindError procedure to +Tk_BackgroundError and exported it to Tk clients. + +12/16/92 (option name change) Changed the place command's "dependents" +option to "slaves" for better consistency with documentation. +*** POTENTIAL INCOMPATIBILITY *** + +12/16/92 (name changes) Renamed the "cursor*" options in entries and +canvases to "insert*". Also renamed the "cursor" index to "insert" and +the "cursor" widget command to "icursor". This was done to avoid +confusion between the mouse cursor and the insertion cursor. +*** POTENTIAL INCOMPATIBILITY *** + +---------------------- Release 3.0, 12/17/92 ------------------------- + +12/17/92 (bug fix) Fixed dangling-pointer bug in canvases that occurred +if a <LeaveNotify> binding deleted the current item. + +12/18/92 (bug fix) Core dump occurred if "wm" invoked with no arguments. +Also, tkWm.c wasn't properly setting WM_CLASS property on application +startup. + +12/18/92 (incorrect documentation) Updated manual entries for Tk_FreeGC, +Tk_FreeCursor, and Tk_FreeBitmap to reflect new interface that requires +"display" argument. + +12/18/92 (missing documentation) Added documentation for the canvas +"postscript" command, which was missing in the 3.0 release. + +12/21/92 (bug fixes) There were lots of problems with the new installation +targets in the Makefiles, such as using "cp -f" and not installing +prolog.ps. Made several other miscellaneous improvements to Makefile. + +12/21/92 (bug fix) Arrowheads on canvas line items weren't moving properly +after coordinate changes made with the "coords" widget command. + +12/21/92 (bug fix) If top-level window was initially withdrawn, couldn't +ever deiconify it again. + +12/21/92 (bug fix) Double-button event sequences didn't always trigger +properly when grabs were in effect. + +12/22/92 (bug fix) The packer didn't display any top or bottom windows +after a left or right expanded window, and vice versa. Also made the +distribution of space among expanded windows more even. + +12/28/92 (new features) Several improvements to selection: +(a) Added procedures Tk_ClearSelection and Tk_DeleteSelHandler. +(b) Added "clear" and "own" options to "selection" command, extended + "handle" option to delete handlers. +(c) Error returns from "selection handle" scripts are now turned into + selection retrieval errors ("no such selection") rather than an + empty selection. +(d) Tk responds automatically for targets APPLICATION (name of application, + so you can "send" to it) and WINDOW_NAME (name of window within + application. +(e) Added test file "select.test" to test suite. + +12/28/92 (bug fix) Fixed problem with flashing menus that occurred +because menu.tcl was willing to unpost and then immediately repost +the same menu. + +1/6/93 (bug fix) Test for UnmapNotify events in tkPack.c used = instead +of ==. + +1/21/93 (bug fix) Changed many widgets to eliminate use of +DefaultVisualofScreen, DefaultColormap, etc. and use the visuals +and colormaps for the actual windows instead. Also changed to +inherit colormaps and windows from parent by default. + +1/21/93 (new features) Added new winfo options "cells", "depth", and +"visual". + +1/23/93 (bug fix) Fixed problem with text display that could result +in negative XCopyArea heights being sent to X server. This causes some +servers (e.g. some versions of OpenWindows) to crash. + +1/25/93 (new feature) Added -postcommand option to menus, so that menus +can be reconfigured before each posting. + +1/29/93 (feature change) Changed %X and %Y in bindings so that they +refer to the virtual root rather than the true root. Although +potentially incompatible, this change should almost always "do the +right thing". +*** POTENTIAL INCOMPATIBILITY *** + +1/31/93 (bug fix) Changed "send" code to grab server while updating +the registry property (before this fix, two programs could allocate +the same interpreter name if they started up simultaneously). In +order to make this fix I had to change the code for reclaiming +names of dead interpreters in a way that sometimes allows dead +interpreters to persist in the registry. + +2/1/93 (feature change) Changed entries to allow leftmost "visible" +character to be the end of the text (i.e. no characters actually visible). +This is needed so that the cursor can be displayed even if the last +actual character is too wide to fit in the window. + +2/3/93 (bug fix) Fixed two bugs in tkFocus.c: (a) FocusIn events +were getting lost in some cases because the focus window hadn't been +created yet (e.g. new top-level window pops up underneath the mouse); +(b) Tk was accidentally triggering FocusOut events when the mouse +moved from a top-level window to one of its children. + +2/4/93 (new feature) Added "visibility" option to "tkwait" command to make +it easier to wait for a new window to appear on the screen. + +---------------------- Release 3.1, 2/5/93 ------------------------- + +2/10/93 (installation improvements) Makefile improvements: added RANLIB +variable for easier Sys-V installation, changed to use INCLUDE_DIR +properly, and added SHELL variable for SGI systems. + +---------------------- Release 3.2, 2/11/93 ------------------------- + +2/11/93 (new feature) Added "wm state" command, and improved wm so that +the right thing will happen if you invoke "wm iconify" when a window is +withdrawn. + +2/14/93 (bug fix) When -colormap option was used in generating Postscript +for canvases, Tk didn't add an extra space after the color command. + +2/14/93 (new feature) Changed "extern" declarations in tk.h to "EXTERN", +which will use the definition of EXTERN from tcl.h and work correctly +in C++ programs. + +2/18/93 (bug fix) Item-specific bindings weren't getting deleted from +canvas items when the items were deleted. As a result, they could +suddenly re-appear for new items if the new items were allocated a +record at the same addresses as the old ones. + +2/18/93 (feature reversal) Changed "after" back again, so that it sleeps +*without* responding to events when it is invoked with just one argument; +can always use tkwait plus after with additional arguments to achieve +the effect of responding to events. +*** POTENTIAL INCOMPATIBILITY *** + +2/20/93 (bug fix) Fixed bug in tkWindow.c where colormaps weren't being +set correctly for new top-level windows on different screens than their +parents (the bug results in X protocol errors: "invalid Colormap +parameter"). + +2/22/93 (bug fix) Changed "#!/usr/local/wish" in demo scripts to +"#!/usr/local/bin/wish" to reflect new location of binary. + +2/22/93 (new feature) Added new reliefs "groove" and "ridge". + +2/25/93 (new feature) Added new built-in bitmaps: "error", "hourglass", +"info", "question", "questhead", and "warning". Also added new demo in +"widget" to display all of these (under the Miscellaneous menu). + +2/25/93 (improved implementation) Changed DrawText procedure in +prolog for outputting Postscript from canvases to use stringwidth +instead of charpath+pathbbox: avoids limitcheck problems with long +strings, and also properly includes space characters in calculation. + +2/25/93 (bug fix) Fixed several bugs in library/menu.tcl that caused +menu traversal to mis-behave when menu had no entries. + +2/26/93 (new feature) Added "wm frame" command. + +3/6/93 (bug fix) Mwm in click-to-focus mode was goofing up grabs so that +pull-down menus were sometimes unresponsive. Modified tk.tcl to ignore +the spurious B1-Enter events generated by mwm, plus modified tkGrab.c to +release simulated button grabs correctly. + +3/8/93 (bug fix) Tk had wrong interpretation of "lbearing" font metric, +which caused text to be displayed at the wrong horizontal position in +several places (labels/buttons, listboxes, canvas text, scales). This +change will cause slight changes in the way certain widgets are +displayed. + +3/12/93 (bug fix) Fixed core dumps that occurred in tkEntry.c because of +zero values in entryPtr->avgWidth. + +3/12/93 (bug fix) Tk_CoordsToWindow was using root coordinates always. +Changed to use virtual-root coordinates when a virtual-root window +manager is being used. Before this fix, "winfo containing" didn't +return the correct window under virtual-root window managers. + +3/18/93 (bug fix) Modified tkWm.c so that Tk doesn't fight with window +manager over position of window; it just takes what the window manager +gives it. + +3/21/93 (new feature) Changed menus to display cascade entries with +standard Motif arrows at right side.a + +3/22/93 (bug fix) Fixed bug in tkPack.c that was causing memory to +get trashed with the integer value 1. + +3/22/93 (bug fix) Canvas text didn't print correctly if it contained +an open paren (or other special character) immediately followed by +an octal digit. + +3/22/93 (bug fix) Text widgets didn't redisplay properly in cases +where two or more groups of lines both got taller at the same time +(e.g. from tag changes), causing two separate bit copies where the +first bit copy's target area overlapped the source area for +the second bit copy. + +4/1/93 (bug fix) Changed canvases to use ISO Latin-1 font encoding +if that's supported by the Postscript interpreter. Also added workaround +for bug in NeWSprint related to stipple fills. + +4/1/93 (bug fixes) Made various changes to focusing and grabs to +eliminate extraneous focus events and generally improve behavior. + +4/2/93 (bug fix) Modified tkWm.c not to wait indefinitely for the window +manager to map or reconfigure a window: this led to deadlock in some +situations, such as creating a new top-level window with a grab held. + +4/19/93 (bug fix) Fixed another bug in tkWm.c that caused windows to walk +across the screen in some situations. Also fixed problem where rapid +posting and unposting of cascaded submenus (or menus?) could cause Tk +to become confused about whether or not a window is mapped (added +TkWmUnmapWindow procedure to make top-level unmaps synchronous). + +4/24/93 (feature change) Changed the "after" command to allow times +less than or equal to 0, and to use 0 whenever they occur. + +4/26/93 (new feature) Implemented security check for "send" as proposed +by Bennett Todd: incoming sends are now rejected unless (a) xhost-style +access control is enabled and (b) the list of authorized hosts is +empty. In other words, you have to use xauth to use send. This feature +can be disabled by setting the TK_NO_SECURITY flag at compile-time. + +5/15/93 (improvement) Switched to use Tcl_PrintDouble whenever returning +real values as Tcl results. This potentially allows higher precision. +Switched to use %.15g whenever printing reals in Postscript files. +However, the change Tcl_PrintDouble causes incompatibilities. For +now, it's disabled with a macro in tclInt.h that redefines Tcl_PrintDouble. +Tk 4.0 will delete the macro, and you can also delete it now if you +want the better (but incompatible) behavior. + +5/19/93 (bug fix) Fixed divide-by-zero problem that could occur in +closeness calculations for canvas oval items. + +5/30/93 (bug fix) PROP and CONFIG were accidentally #defined to the same +value in tkBind.c, which could cause incorrect %-substitutions in event +bindings in a few exotic cases. + +6/4/93 (improvement) Changed to use GNU autoconfig for configuration. +Makefile format changed, and Tcl is no longer automatically included +in Tk releases. + +6/7/93 (bug fix) Fixed off-by-one error in rounding negative coordinates +during redisplay of canvases. + +6/9/93 (feature improvement) Modified default bindings for entries to +keep one character visible to the left of the cursor during backspaces. + +6/18/93 (feature improvement) Added patchlevel.h, for use in coordinating +future patch releases, and also added tk_patchLevel variable to make the +patch level available in scripts. + +6/26/93 (bug fix) Fixed numeric problems in scales that occurred with +very large scale values. + +6/26/93 (bug fix) Polygon items in canvases could cause core dumps if +the "coords" widget command was used to add one new coordinate. + +6/26/93 (bug fix) Changed canvases to handle large stipple patterns +gracefully (stipples used to jump around during redisplay and lose +coherency). + +7/1/93 (syntax change, new feature) Implemented the new packer syntax +as described in the book. For now the old syntax will continue to be +supported too. Converting over is straightforward except (a) use +"-anchor" instead of "frame", and (b) padding is different (separate +internal and external padding, plus pad amounts are *on each side* +instead of total). Also added "pack propagate" command for keeping +the packer from setting the master's requested size. + +7/1/93 Changed copyright notices. The effect is the same as with the +old notices, but the new notices more clearly disclaim liability. + +7/7/93 (new feature) Added support for window stacking order. Windows +will now stack in the order created (most recent on top), plus "raise" +and "lower" commands may be used to restack (Tk_RestackWindow procedure +is available from C level). + +7/7/93 (reorganization) Moved main.c to tkMain.c, reorganized it to +call Tcl_AppInit just like tclsh does, and added argv0 variable to contain +application name, and added default Tcl_AppInit procedure for wish. +Also added tkTest.c to hold C code for testing. + +7/7/93 (new feature) Added new Tk-specific "exit" command, which cleans +up properly before exiting. It replaces the Tcl "exit" command, and +can be used in place of "destroy .". + +7/9/93 (new features) Added tk_dialog library procedure that creates +dialogs with a bitmap, message, and any number of buttons. Also changed +default tkerror procedure to use tk_dialog plus offer the user a chance +to see a Tcl stack trace. + +-------------------- Release 3.3 Beta 1, 7/9/93 ------------------------- + +7/12/93 (configuration changes) Eliminated leading blank line in +configure script; provided separate targets in Makefile for installing +binary and non-binary information; fixed -lnsl and -lsocket handling +in configure; added autoconf support for fd_set type; check for various +typedefs like mode_t and size_t, and provide substitutes if they +don't exist; don't include tkAppInit.o in libtk.a; try to locate the +X includes and library in all of the standard places for various systems. + +7/14/93 (new feature) Modified tkMain.c so that it stores the value +of the -display command-line option into the DISPLAY environment +variable, if it is specified. + +7/15/93 (feature removal) Removed auto-initialization feature from +Tk_ConfigureWidget, so that you must once again initialize all fields +of a widget record before calling Tk_ConfigureWidget. This restores +the behavior back to what it was in Tk 3.2. + +7/16/93 (bug fix) Modified tkBind.c to ignore the Caps Lock modifier +unless it is explicitly requested in a binding. Without this fix, +buttons and menus and other things didn't work if the Caps Lock key +was active. + +-------------------- Release 3.3 Beta 2, 7/21/93 ------------------------- + +7/21/93 (new feature) Change "make install" so that it will modify the +#! lines on demo scripts to reflect the place where the wish binary +is installed. + +7/23/93 (new feature) Added Tk_MainWindow procedure that returns the +main window associated with a Tcl interpreter. This is intended for +use by Tcl_AppInit and other initialization procedures. + +7/24/93 (configuration improvements) Changed configure script not to +omplain about "fd_set" missing if it's defined in <sys/select.h>. + +7/28/93 (bug fix) "Bad Match - parameter mismatch" errors were +sometimes occurring when several top-level windows got created +at the same time, due to wrong choice of sibling when stacking +windows. + +8/14/93 (new feature) Added support for tcl_prompt1 and tcl_prompt2 +to wish main program: makes prompts user-settable. + +8/19/93 (bug fix) Bindings to event sequences like "aD" never matched +because the Shift key has to be pressed before D. Modified Tk to +ignore extraneous keypresses if they are for modifier keys. + +8/26/93 (configuration changes) Added Tk_Init, modified Tcl_AppInit +procedures to use it and Tcl_Init. Added support for .wishrc file. + +8/28/93 (new feature) The main window is now a legitimate toplevel +widget. + +-------------------- Release 3.3 Beta 3, 8/30/93 ------------------------- + +9/2/93 (bug fix) The packer wasn't always relaying out a master after +changes to some of the configuration options of its slaves. + +9/2/93 (bug fix) The binding mechanism made it impossible for patterns +like <Double-ButtonRelease-1> to ever match. + +9/2/93 (bug fix) Fixed core dump that occurred for bitmap canvas items +if Postscript is generated but no -bitmap option has been specified. + +9/4/93 (enhancement) Slight improvements to menu traversal: set menu +traversal bindings for menubar window in tk_menuBar, plus trigger +traversal on <Any-Alt-Keypress> instead of <Alt-Keypress>. + +9/9/93 (bug fix) Changed tkBind.c so that the Num_Lock key doesn't +prevent events from triggering bindings. + +9/9/93 (bug fix) Changed tkOption.c to always fetch RESOURCE_MANAGER +property from root window of screen 0, rather than using default +screen. + +9/9/93 (bug fix) Entry widgets weren't allocating quite enough width +for themselves. Fixed this and changed the size computation to match +what's done for buttons and texts. + +9/16/93 (bug fix) Changed tkMain.c not to call exit C procedure directly; +instead always invoke "exit" Tcl command so that application can redefine +the command to do additional cleanup. + +-------------------- Release 3.3, 9/29/93 ------------------------- + +9/30/93 (bug fix) Packer wasn't unmapping slaves when master got deleted. + +9/30/93 (bug fix) Binding event sequences such as <Right> were being +misprinted as ASCII characters such as "S". + +10/6/93 (bug fix) Canvases weren't unmapping window items when the canvas +got unmapped, which caused problems for window items whose windows weren't +descendants of the canvas (they got left on the screen). + +10/7/93 (feature change) NULL proc arguments to Tk_CreateFileHandler used +to have a special undocumented meaning (fd was display); eliminated this +special interpretation. + +10/7/93 (configuration change) Eliminated dependency of tkMain.c on +tkInt.h and tkConfig.h, so that it's easier for people to copy the file +out of the source directory to make modified versions. + +10/8/93 (bug fix) 3.0 introduced a bug where the class of the application +wasn't being set properly, so options based on the application class +weren't triggering. Fixed by adding new argument to Tk_CreateMainWindow. + +10/11/93 (bug fix) Fixed bug in tkTextBTree.c where some deletions would +cause core dumps due to halfwayLinePtr not getting set correctly. + +10/18/93 (bug fix) Fixed a couple of bugs that made it hard to actually +display N characters in an entry with "-width N" (tended to scroll the +entry so that only N-1 characters were visible at once). + +10/22/93 (bug fix) During configuration, XINCLUDE_DIR and XLIBRARY_DIR +weren't overriding xmkmf like they were supposed to. + +10/23/93 (new feature) Allow negative scale factors in canvas "scale" +widget command. + +10/23/93 (bug fix) Grabs weren't being cleaned up right if the grab +window was deleted, causing core-dumps in some cases. + +10/23/93 (bug fix) tk_TextSelectTo wasn't checking to be sure that +the "anchor" mark exists. + +10/27/93 (bug fix) Fixed core dump that could occur in a text widget if +the scroll command modifies the text. + +11/1/93 (bug fix) Change texts so that the -yscrollcommand option is +invoked at display time, not when the window is re-layed out. This +eliminated various core dumps that could occur if -yscrollcommand modified +the text. + +-------------------- Release 3.4, 11/04/93 ------------------------- + +Note: there is no 3.5 release. It was flawed and was thus withdrawn +shortly after it was released. + +11/12/93 (bug fix) TkMain.c didn't compile on some systems because of +R_OK in call to "access". Changed to eliminate call to "access". + +-------------------- Release 3.6, 11/26/93 ------------------------- + +11/10/93 (bug fix) Packer and placer didn't always reposition a window +correctly if it was managed inside a neice or lower descendant (using +"-in" option) and the neice's parent moved. + +11/24/93 (bug fix) Fixed time problem in selection (retrievals could +fail if retriever hasn't received any X events since selection was +made, so that time of retrieval appears to be older than time of +selection). Selection code is now much less picky about times, both +on retrieving and supplying sides. + +12/2/93 (new feature) Changed arrow-head drawing code for canvas +lines to draw a 0-width outline in addition to filling the area: +this produces much nicer, more symmetrical displays. + +12/2/93 (bug fix) When colors ran out, Tk was invoking "tkerror" +when its state was internally inconsistent, which could cause +core dumps in some situations (e.g. if tkerror used the same color +that caused colors to run out). Changed notification to occur +as a when-idle handler. + +12/3/93 (bug fix) During a global grab, Tk wasn't including PointerMotion +in the list of grabbed events, so pointer motion couldn't be tracked +outside the grabbing application. + +12/3/93 (bug fix) Canvases didn't handle smoothed lines correctly +when they only contained two points. + +12/3/93 (bug fix) Fixed bug in tkWindow.c where certain kinds of +errors during window creation could cause Destroy events to be generated +for a window that was never completely initialized. + +12/13/93 (bug fix) Fixed bug in tkTextDisp.c that resulted in core +dumps at line 1467 under exmh. The exact situation is that a text +widget was being redisplayed at a time when it had a -yscrollcommand +option but hadn't yet been mapped onto the screen. + +12/17/93 (bug fix) Fixed bug in tkWindow.c whereby new top-level windows +with non-default visuals still inherited border pixmap from parent (root), +which could cause visual clash and X error. + +12/17/93 (bug fix) Fixed bug in tkTextDisp.c that caused round-off +error in the information passed to scroll commands. + +12/18/93 (bug fix) Fixed bug in tkPack.c that caused core dumps in +some situations if a master with siblings packed "-in" it was deleted. + +12/18/93 (bug fix) Added "compat" directory to distribution, since it's +referenced by tkConfig.h on some systems. + +12/18/93 (performance improvement) Improved performance of appending to +a listbox, so that inserting N items doesn't take N**2 time. + +12/20/93 (bug fix) Fixed bug in canvas ovals that caused the fill color +for the oval to stick out past the outline. + +1/2/94 (fixed Xlib bug) Added code to reuse X resource identifiers so +that they won't run out in long running applications. There are three +new library procedures: Tk_FreeXId, Tk_GetPixmap, and Tk_FreePixmap. +Modified all Tk code to use these procedures, so wish applications should +now be able to run forever without running out of identifiers. + +1/10/94 (bug fix) tkCursor wasn't freeing pixmaps used to create +cursors, which caused memory leaks in programs that changed cursors +frequently. + +1/21/94 (bug fix) Fixed bug in scales that caused them to loop +infinitely drawing tick-marks when -from and -to were the same. + +2/2/94 (bug fix) Fixed problem where messages that contained tabs +didn't always compute the correct size, so that text spilled off +the right edge. The fix adds an extra "tabOrigin" parameter to +the internal procedures TkMeasureChars, TkDisplayChars, and +TkUnderlineChars. + +2/4/94 (bug fix) Fixed off-by-one problem in tkBind.c that caused +it to read past the initialized part of dispPtr->modKeyCodes. + +2/7/94 (bug fix) Text widgets didn't handle grabs correctly, such +that the "current" character got stuck if a grab occurred while a +mouse button was down. It would get unstuck until after the +next button press and release. + +2/19/94 (bug fix) Fixed prolog.ps (prolog for Postscript printing from +canvases) so that it correctly prints all of the characters in the +ISO Latin-1 character set. + +2/19/94 (bug fix) Modified tkBind.c to save and restore the interpreter's +result across the execution of binding scripts. Otherwise if an event +triggers in the middle of some other script (e.g. a destroy event during +window creation, because there was an error in the creation command), +the intepreter's result gets lost. + +2/19/94 (bug fix) Fixed bug in dealing with results of sent command +that could cause them to get lost in some situations. + +2/21/94 (bug fix) Don't let user close a dialog window created by +tk_dialog, since this would cause tk_dialog to hang: force the user +to select one of the dialog's buttons. + +2/21/94 (bug fix) Fixed bug in canvas polygons whereby they didn't +correctly handle changes in the number of points (via "coords" +widget command). + +2/23/94 (bug fix) Large bitmaps in canvases didn't print correctly +because they overflowed the 64-KB limit on strings in Postscript. +Changed canvas printing to split up large bitmaps into mutliple +smaller ones for printing. + +2/25/94 (bug fix) The "." window was being set up with -width +and -height options, which interfered with geometry management (any +configuration change on "." causes the window to change size to +200x200, then change back again). + +2/26/94 (bug fix) Fixed several bugs that occurred when a Destroy +event handler for a window deleted the window's parent. + +3/3/94 (new features) Changes to binding mechanism: + - The modifiers for "Alt", "Meta", and "M" are now computed by + examining the modifier map, rather than being hardwired to + M2, M1, and M1. + - When processing events, one script is invoked for each object + in the list passed to Tk_BindEvent, rather than stopping as + soon as a script is invoked for some object. The "break" and + "continue" commands can be used within a script to abort all + scripts for the event or the current one. + *** POTENTIAL INCOMPATIBILITY *** + - Added "bindtags" command so that new binding groups can be + defined for widgets and the evaluation order can be changed. + - When matching events to bindings, extra modifiers are now ignored, + as if "Any" were specified for every event. The "Any" modifier + is still recognized, but it is ignored and is deprecated. + *** POTENTIAL INCOMPATIBILITY *** + - In % sequences that print window identifiers (e.g. %a and %S), print + in hexadecimal rather than decimal, for consistence with "winfo id". + *** POTENTIAL INCOMPATIBILITY *** + - The "bind" command no longer supports the event types CirculateRequest, + ConfigureRequest, MapRequest, or ResizeRequest. These event types + are somewhat dangerous, and they never worked anyway. + +3/13/94 (bug fix) Fixed numerous problems with the "wm iconwindow" command. +It appears that this command never really worked at all, but it should +work OK now. + +3/14/94 (feature changes) Removed several obsolete features: + - Eliminated "enable" and "disable" widget commands for menus. + *** POTENTIAL INCOMPATIBILITY *** + - Eliminated "activate" and "deactivate" widget commands for buttons, + checkbuttons, radiobuttons, and menubuttons. + *** POTENTIAL INCOMPATIBILITY *** + - Removed -geometry option for frames and toplevels: it causes + problems when .Xdefaults files contain entries like + "*geometry: +0+0". Must use -width and -height instead. + *** POTENTIAL INCOMPATIBILITY *** + - Desupported "tkVersion" variable: use "tk_version" instead. + *** POTENTIAL INCOMPATIBILITY *** + +3/16/94 (feature changes) Changes to listboxes: + - Eliminated -geometry option (it causes problems when .Xdefaults + files contain entries like "*geometry: +0+0"). Added -width + and -height options to use instead. + *** POTENTIAL INCOMPATIBILITY *** + +3/21/94 (bug fix) Fixed bug in tkOption.c where the option cache wasn't +properly cleaned up after window deletion; this could cause the wrong +value from the option database to be used under some conditions. + +3/25/94 (new features) Changes to geometry management: + - Added Tk_MaintainGeometry and Tk_UnmaintainGeometry procedures + to solve problems with -in windows. Modified the packer, the + placer, and canvases to use them. + - Changed 2nd argument to Tk_ManageGeometry from Tk_GeometryProc * + to a pointer to a structure with additional information about + the geometry manager, such as name and procedure to call when + slaves are stolen. + *** POTENTIAL INCOMPATIBILITY *** + +3/28/94 (new feature) Overhauled event management: + - Added "cancel" option to the "after" command so that you can + cancel previously-scheduled commands. + - Separated X-specific stuff from generic event management. The + file tkEvent.c can now be used stand-alone without the rest of Tk. + See the manual entry for Tk_EventInit for information on which + procedures are available this way. + - Added Tk_CreateFileHandler2 procedure, which provides a lower-level + and more powerful form of file event handler. + - Fixed bug in Tk_DoOneEvent where an infinite loop could occur if + the TK_FILE_EVENT and TK_DONT_WAIT flags were set simultaneously + (there were bugs with several other combinations too; all should + be fixed now). + +3/28/94 (new feature) Added "fileevent" command, which allows event- +driven I/O in the style of Mark Diekhans' "addinput" command. + +4/11/94 (new feature) Better support for colormaps and visuals: + - Added new -colormap and -visual options to toplevels and frames. + - Added "winfo visualsavailable" command. + - Added "wm colormapwindows" command, plus support for WM_COLORMAP_WINDOWS + to Tk_SetWindowColormap. + - Added new library procedures Tk_GetVisual, Tk_GetColormap, + and Tk_FreeColormap. + +4/11/94 (bug fix) Fixed core dump that used to occur when specifying +an iconwindow ("wm iconwindow") for a toplevel on a different screen +than the main window. + +4/23/94 (new feature) Added support for images, including the following: + - New "image" command for creating images. + - Built-in image type: bitmap. + - New "image" item type in canvases. + - Labels, buttons, checkbuttons, radiobuttons, menubuttons, and + menu entries now support a -image option for displaying images. + - Tk_CreateImageType and Tk_ImageChanged procedures, for defining + new types of images in C. + - Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, and Tk_SizeOfImage + procedures, for using images in widgets. + +5/1/94 (new features) Added new procedures Tk_3DVerticalBevel and +Tk_3DHorizontalBevel. + +5/11/94 (new features) Major overhaul of text widgets: + - Implemented embedded windows and "window" widget command. + - Added new configuration options for tags: -justify, -lmargin1, + -lmargin2, -rmargin, -offset, -spacing1, -spacing2, and -spacing3. + See the "Display styles" widget demo for examples. + - Added new configuration options for texts: -spacing1, -spacing2, + and -spacing3. + - Added "tagList" option to "insert" widget command to control + tags on new text. Made tagged regions so they aren't sticky on + either side: new characters get a tag only if the old chars. on + both sides had it. + *** POTENTIAL INCOMPATIBILITY *** + - Added gravity for marks, and "mark gravity" widget command. + - Added horizontal scrolling, "xview" widget command, -xscrollcommand + option. Changed "scan" widget commands to support horizontal + scrolling. + *** POTENTIAL INCOMPATIBILITY *** + - Added "search" widget command for searching (either exact matches + or regular expressions). + - New widget commands: bbox, dlineinfo, and see. + - Changed implementation of bindings so that Enter and Leave + events are not generated unless the tag has just become present + (or just ceased to be present) on the current character. Also + changed bindings to process separately for each tag, rather than + having high-priority tags override low-priority ones. + - The "end" index now refers to the character after the last newline + rather than the newline itself. You can now tag the final newline + and set a mark after the final newline. + - Deletions of the "sel" tag and the "insert" and "current" marks + are now ignored silently, rather than generating errors. This means + you can do things like "eval .t tag delete [.t tag names]". + +5/19/94 (bug fix) Canvases didn't generate proper Postscript for stippled +text. + +5/20/94 (new feature) Added "bell" command to ring the display's bell. + +5/20/94 (new feature) Incorporated "square" demonstration widget into +tktest application. + +5/20/94 (new features) Changed wish application (tkMain.c): + - wish no longer processes the -help option. + *** POTENTIAL INCOMPATIBILITY *** + - The wish main program is now called Tk_Main; tkAppInit.c has a + "main" procedure that calls Tk_Main. This makes it easier to use + Tk with C++ programs, which need their own main programs, and it + also allows an application to prefilter the argument list before + calling Tk_Main. + *** POTENTIAL INCOMPATIBILITY *** + - The application's class is now the same as its name (except the + first letter is capitalized), instead of "Tk". + *** POTENTIAL INCOMPATIBILITY *** + - The -file keyword is no longer required: the script file name can + be provided as the first argument without being preceded by "-file", + as in tclsh. For backward compatibility the "-file" keyword is + ignored if it is the first argument, but it is deprecated. + +5/26/94 (feature removed) Removed support for "fill" justify mode from +Tk_GetJustify and from the TK_CONFIG_JUSTIFY configuration option. None +of the built-in widgets ever supported this mode anyway. +*** POTENTIAL INCOMPATIBILITY *** + +5/27/94 (feature change) Changed Tk to use Tk_PrintDouble everywhere +that it converts reals to strings. This means that floating-point +values will be generated in some cases where integer-like values were +generated before. +*** POTENTIAL INCOMPATIBILITY *** + +6/1/94 (feature change) Renamed "pack newinfo" command to "pack info". +The old "pack info" command is no longer available. +*** POTENTIAL INCOMPATIBILITY *** + +6/20/94 (feature changes) Overhaul of entry widgets: + - Added "-justify" option. + - Added "-show" option to make entries easier to use for passwords. + - Added "cget" widget command. + - Added "selection range" and "selection present" widget commands. + - Added "anchor" symbolic index. + - Changed "-scrollcommand" option to "-xscrollcommand", "view" + widget command to "xview", for compatibility with other widgets. + *** POTENTIAL INCOMPATIBILITY *** + - Changed sel.last to refer to character just *after* last one + selected, again for compatibility with other widgets. + *** POTENTIAL INCOMPATIBILITY *** + - For "delete" widget command, second index now refers to character + just *after* last one to delete. + *** POTENTIAL INCOMPATIBILITY *** + - Overhauled bindings to be more Motif-compatible and to include + common Emacs bindings for editing. + - Changed -width option: if specified as 0, widget sizes to fit + its current text. + +6/11/94 (new features) Improved Motif compatibility: + - Added "-highlightwidth" and "-highlightcolor" options to all widgets. + +6/27/94 (bug fix) Postscript generation for text items in canvases was +not justifying the text properly when a -width was specified that was +longer than the longest line. + +6/27/94 (bug fix) "winfo exists" used to report a window as existing +if it was in the process of being destroyed (i.e., a destroy handler +is in the middle of execution). Changed to report it as non-existent +under these conditions. +*** POTENTIAL INCOMPATIBILITY *** + +7/11/94 (bug fix) Selections claimed via "selection own" weren't always +being cleared properly when the selection was claimed away. Also fixed +bug where Tk wasn't properly claiming the selection, if there haven't +been any recent X events at the time of the claim. + +7/13/94 (feature changes) Overhaul of scrollbar widgets: + - New widget commands: "activate", "cget", "fraction", and "identify". + - New options: -activebackground, -activerelief, -highlightcolor, + -jump, -highlightthickness, and -troughcolor. What used to be + -background is now -troughcolor, -foreground is now -background, + and -activeforeground is now -activebackground. + *** POTENTIAL INCOMPATIBILITY *** + - Added new syntax for "set" command, "get" result, and generated + commands. Changed other widgets to use the new syntax. + - Moved the bindings out of C and into Tcl scripts, using the new + options and widget commands. Added support for all Motif + bindings, plus jump scrolling and cancelling of slider drags. + +7/16/94 (bug fix) Canvases assumed that the Leave event for one item +didn't modify or delete the next current item; this could cause core +dumps under some conditions. + +7/23/94 (feature change) Modified Tk_BackgroundError so that tkerror +is invoked as an idle handler. If tkerror generates a break exception +then all other queued reports are aborted. + +8/14/94 (bug fix) "cursorOffTime" and "cursorOnTime" were confused in +canvases, resulting in the same time being used for both. + +8/16/94 (bug fix) "tkwait variable" command didn't detect errors in +variable name, such as trying to wait for an entire array. + +9/2/94 (new features) Overhaul of scale widgets: + - Floating-point values are supported now, following Paul Mackerras' + "fscale" widget. Added "-resolution" and "-digits" options. + - Added "-variable" option to link scale to variable, following + Henning Schulzrinne's implementation. + - Added focus highlight (-highlightthickness and -highlightcolor + options). + - Added new widget commands "cget", "coords", "identify", plus + improved "get"; removed wired-in bindings, added complete set + of Motif bindings via Tcl scripts. + - Changed -sliderforeground option to -background, -background to + -troughColor, -activeforeground to -activebackground. + *** POTENTIAL INCOMPATIBILITY *** + - Moved value label from below horizontal scales to above the scale, + for Motif compliance. + +9/9/94 (bug fix) Fixed bug in tkWm.c that caused long delays in "raise" +command under some conditions (window already at the top of the stack). + +9/10/94 (new features) Overhaul of label/button/checkbutton/radiobutton +widgets: + - Added focus highlight (-highlightthickness and -highlightcolor + options). + - Added new widget command "cget". + - Changed -selector option to -selectcolor, and changed its meaning + too: empty no longer means don't draw the indicator; it means + don't use a special color when selected. + *** POTENTIAL INCOMPATIBILITY *** + - Added -indicatoron (controls whether indicator is displayed) and + -selectimage (gives special image to display when selected) options. + - Modified bindings to be more Motif-like, added binding for space + key. + - Changed padding defaults to give widgets correct Motif appearance + by default. Also, changed to ignore padding options when displaying + an image or bitmap. + *** POTENTIAL INCOMPATIBILITY *** + - Can now display text on multiple lines: newlines cause line breaks, + and word wrapping can be requested with -wraplength option. Also + added -justify and -underline options. + - The -value option for radiobuttons can now have an empty string as + its value; it no longer defaults to the name of the widget. + *** POTENTIAL INCOMPATIBILITY *** + +9/13/94 (new features) Modified both canvases and messages to support +-highlightthickness and -highlightcolor options plus "cget" widget +command. + +9/19/94 (new features) Added Tk_UnsetGrid procedure, modified widgets +to use it. Also changed Tk_SetGrid so that at most one window per +toplevel can have gridding enabled. + +9/23/94 (new features) Major overhaul of listbox widgets: + - Added focus highlight (-highlightthickness and -highlightcolor + options). + - Added new widget command "cget". + - Revised selection commands to support single selections as well + as multiple disjoint selections; syntax of "selection" widget + command has changed to support this. Added new option -selectmode + for specifying which mode to use. Default is single selection; + tk_listboxSingleSelect procedure no longer exists. Selections + now return as items separated by newlines instead of a list whose + elements are the items. + *** POTENTIAL INCOMPATIBILITY *** + - Extended "get" widget command to allow many items to be retrieved + at once. + - Added "bbox" widget command for finding position of an element on + screen. + - Added "activate" command to mark element with traversal focus. + - Extended index mechanism to support new types of indices: + "active", "anchor", "@x,y". + - Added "see" widget command. + - Revised bindings to include all Motif features except for AddMode. + - If -width or -height option is <= 0, the widget requests a size just + large enough to hold all of its text. + +10/6/94 (new features) Overhaul of menubuttons: + - Added focus highlight (-highlightthickness and -highlightcolor + options). + - Added new widget command "cget". + - Added -indicatoron option to display option menu indicator. + - The -menu option must be a child of the menubutton. + *** POTENTIAL INCOMPATIBILITY *** + +10/6/94 (new features) Overhaul of menu widgets: + - Added new widget commands "cget" and "entrycget". + - Changed the implementation of tear-off menus to be more + Motif-like; added -tearoff option for specifying whether + tearoff entry is displayed. + - Changed interpretation of "@y" index: it now returns the + closest entry, rather than "none" if y is outside the menu's + range. + *** POTENTIAL INCOMPATIBILITY *** + - The -menu option for a cascade entry must now be a child of + the menu. + *** POTENTIAL INCOMPATIBILITY *** + - Added "type" widget command, so that you can query the type of + an entry. + - Added -foreground, -activeforeground, -selectcolor, -indicatoron, + -image, and -selectimage options to menu entries. + - Changed "selector" menu option to "selectColor" for Motif compliance. + *** POTENTIAL INCOMPATIBILITY *** + - Added -relief option for menus, just for consistency with other + widgets (it was implicitly "raised" before). + +10/6/94 (feature change) Completely overhauled the bindings for menus +and menubuttons. They now fit better with other Tk 4.0 facilities, +such as the new binding mechanism, and they provide better Motif +compliance (e.g. keyboard traversal of submenus). Also, the bindings +now support option menus, popup menus, and proper Motif tear-off +menus. + +10/6/94 (obsolete features) The procedures tk_menuBar and +tk_bindForTraversal are no longer needed in Tk 4.0. They still exist +for compability, but they do nothing. + +10/6/94 (new procedures) Added "tk_popup" procedure for posting a +popup menu, and "tk_optionMenu" for creating an option menubutton +and its associated menu. + +10/6/94 (change in name) The variable "tk_priv" has been renamed +to "tkPriv" to reflect that fact that it is private to Tk now. +This shouldn't cause any problems, since no-one except Tk should +have been using it before anyway (right?). + +10/6/94 (bug fix) Fixed bug in texts where sometimes the text would +stop tracking mouse motion (the "current" item wouldn't get updated) +because the text widget missed a ButtonRelease event. + +10/20/94 (new features) Overhauled selection code to support multiple +selections (primary, secondary, etc.) and multiple displays: + - Changed "selection" command to support new options such as + "-displayof" and "-selection". Old command formats are still + supported for compatibility, but they are no longer documented + and are deprecated. + - Changed procedures Tk_GetSelection, Tk_CreateSelHandler, and + Tk_ClearSelection to take additional "selection" argument. + *** POTENTIAL INCOMPATIBILITY *** + - Selection targets APPLICATION and WINDOW_NAME have been replaced + by TK_APPLICATION and TK_WINDOW. + *** POTENTIAL INCOMPATIBILITY *** + +10/20/94 (new features) Added support for clipboard: + - New "clipboard" command. + - C procedures Tk_ClipboardClear and Tk_ClipboardAppend. + - Bindings for "cut", "paste", and "copy" for text and entry widgets, + plus "copy" binding for listboxes. + +10/24/94 (bug fix) Button widgets weren't checking for errors when +setting the values of associated variables. + +11/3/94 (bug fix) Fixed bug whereby Tk would hang if "exit" was invoked +from inside a <Destroy> binding. + +11/15/94 (new features) Overhaul of focus mechanism: + - Added support for multiple displays: separate focus windows are + kept for each display. + - Added support for keyboard traversal. + - Changed focus model so Tk keeps track of a focus window for each + top-level window and automatically sets the focus on Enter to the + top-level. Tk no longer synthesizes FocusIn and FocusOut events, + but just uses the standard X mechanisms. There is no "default" + focus window anymore; the focus reverts to top-levels by default. + *** POTENTIAL INCOMPATIBILITY *** + - Changed focus command: eliminated "focus default" and "focus none", + added "-displayof" and "-lastfor" options. An empty string is now + used to signify "no focus" instead of "none". + *** POTENTIAL INCOMPATIBILITY *** + - Added library procedures tk_focusNext, tk_focusPrev, and + tk_focusFollowsMouse. + - Removed obsolete Tk_CreateFocusHandler: must use FocusIn and + FocusOut events now. + *** POTENTIAL INCOMPATIBILITY *** + +11/23/94 (new features) Overhaul of "send" command: + - Added support for multiple displays: -displayof option to "send". + - Added asynchronous sends: -async option to "send". + - Eliminated fixed timeouts on sends: as long as the target + application appears to exist, the send will wait for it. + - Stale entries get removed from the application registry now, + so "winfo interps" should never return non-existent applications. + - Can change the name of an application with "tk appname" command. + This is also the preferred way of querying the application name + now. + - The errorCode and errorInfo variables are now propagated back to + the sender now, so a full stack trace is available. + - Tk checks display security on each send now, instead of just during + initialization, so changes in the security status are seen immediately + by all applications. + - The above changes required changes to the data formats used for + communication between source and target applications, so Tk 4.0 + applications cannot send to, or be sent from, Tk 3.6 applications. + *** POTENTIAL INCOMPATIBILITY *** + - The procedure Tk_RegisterInterp has been replaced with Tk_SetAppName. + *** POTENTIAL INCOMPATIBILITY *** + +12/6/94 (cleanup) Eliminated "interp" argument to Tk_GetColorByValue, +since it is no longer needed. +*** POTENTIAL INCOMPATIBILITY *** + +12/7/94 (feature change) Changed the "wm" command so that top-level +windows are now resizable by default. You can no longer specify +empty arguments to "wm maxsize" and "wm minsize". +*** POTENTIAL INCOMPATIBILITY *** + +12/8/94 (new feature) Added new "photo" image type using code provided +by Paul Mackerras: currently supports only PPM "P6" format images. + +12/14/94 (new features) Canvas modifications: + - Modified the interfaces between generic canvas code and the item + types so that it's easy for people to write new item types outside + of Tk. + - Added support for transparent bitmap items: just specify an + empty string as the background color. + - Changed the "xview" and "yview" commands for canvases to use the + new scrolling syntax. + - Eliminated -scrollincrement option. + *** POTENTIAL INCOMPATIBILITY *** + +12/14/94 (bug fix) Fixed bug where the dimensions of canvas arrowheads +scaled during a "scale" widget command, but the scaling was only +temporary and got lost on the next re-configure of the item. The +correct behavior is for the arrowheads not to scale. + +-------------------- Release 4.0b1, 12/23/94 ------------------------- + +12/26/94 (bug fix) Removed obsolete demos from Makefile (color, dialog, +size), fixed "install" target. + +1/3/95 (bug fix) Fixed all procedure calls to explicitly cast arguments: +implicit conversions from prototypes don't work when compiling under +non-ANSI compilers. Tk is now clean under gcc -Wconversion. + +1/4/95 (bug fix) Used "screenX" without ever setting it in DisplayText +in tkCanvText.c: caused tabs in canvas text items to get messed up. + +1/4/95 (bug fix) Canvases forgot to register the built-in types if +Tk_CreateItemType was called before a canvas widget was created. + +1/4/95 (bug fixes) Fixed glitches in various text bindings: + - Up used to do nothing if the cursor was at 2.0. + - Right used to make the cursor invisible if it was just before + the final newline of the text. + - Control-t didn't conform to Emacs; made it conform to GNU Emacs. + - Deleted Control-x binding, since it doesn't conform to anything and + is confusing for Emacs users. + +1/4/95 (bug fixes) Changed Control-t for entries just as for texts (see +above) an deleted Control-x for entries (see above). + +1/4/95 (bug fix) The packer didn't map slaves unless the master was mapped; +this could cause slaves to get "lost" so that they weren't mapped until the +master resized. + +1/5/95 (bug fix) Scrollbars weren't executing the proper code the first time +the mouse entered the widget; this caused problems if tk_strictMotif was +set. + +1/6/95 (bug fix) Fixed label/button/checkbutton/radiobutton/menubutton +widgets to allow arbitrary screen distances when specifying -width and +-height for an image or bitmap (the manual pages already documented this +but the code didn't implement it). + +1/6/95 (new feature) Added very primitive support for input methods, +as suggested by Martin Forssen. This should be enough for European +character sets (Compose key) but it isn't near enough for Asian +character sets. + +1/8/95 (bug fix) Fixed problem in canvas "xview" and "yview" commands +where divide-by-zero errors could sometimes occur. + +1/8/95 (bug fix) New event handler didn't properly handle files for +which both TK_READABLE and TK_WRITABLE were specified. + +1/11/95 (bug fix) Fixed bug with text selections: was returning count +too high for data, causing bogus garbage to appear when selection was +copied. + +-------------------- Release 4.0b2, 1/12/95 ------------------------- + +1/27/95 (feature removal) Removed %D substitution from binding scripts: +wasn't portable, shouldn't be used anyway. +*** POTENTIAL INCOMPATIBILITY *** + +1/27/95 (new features) Added -displayof options to the commands +"winfo atom", "winfo atomname", "winfo containing", "winfo interps", +and "winfo pathname". + +1/27/95 (new feature) Added "idle" option to "after" command to run +scripts as idle handlers. + +1/28/95 (new feature) Modified placer to make -x and -relx additive +if you specify both. Same for -y and -rely, -width and -relwidth, +and -height and -relheight. This makes it easy to make request such +as "make .a 2 pixels larger than .b". +*** POTENTIAL INCOMPATIBILITY *** + +1/28/95 (new feature) Improved auto-grab mechanism in canvases (which +prevents current item from changing while a button is down): changed +to report Enter and Leave events for the current item while a button +is down. However, as before, no Enter events are reported for other +items until the button goes up. + +1/28/95 (new feature) Bitmap images are now transparent if the -background +is specified as an empty string (-maskdata and -maskfile are ignored in +this case). This is also the default. + +1/28/95 (bug fix) Tk didn't support manufacturer- or site-specific keysyms +such as SunAudioMute. Modified tkBind.c so that it uses XStringToKeysym +in addition to its own hash table, so that all keysyms are now available. + +1/30/95 (feature change) Modified "clipboard append" so that it reclaims +the clipboard selection if it had been previously lost, rather than just +generating an error. This handles certain race conditions more cleanly, +and also allows the use of programs like "xclipboard". + +1/30/95 (new feature) Added -xscrollincrement and -yscrollincrement +options to canvases. + +1/31/95 (bug fix) Geometry management was broken if a particular geometry +manager claimed a slave away from itself. + +1/31/95 (bug fix) Fixed bug in tkVisual.c where a visual with fewer bits +than requested was being selected in preference to one with just the right +number of bits. + +1/31/95 (bug fix) Texts weren't redisplaying the padding region properly +after changes in -padx or -pady. + +1/31/95 (new features) More text improvements: + - Extended "insert" widget command for texts to allow multiple + text-tagList pairs in the same command. + - Added -nocase option to "search" widget command. + - Added -overstrike option to tags. + - Added tab stops, via -tabs option for widget and for tags. + +2/10/95 (bug fix) Modified all widgets to allow renaming of widget +commands. Deleting a widget command will delete the widget. + +2/11/95 (new feature) Added -highlightbackground option to all widgets. + +2/14/95 (new feature) Added "insert" widget command for menus. + +2/15/95 (new feature) Modified text display code (for all widgets) to +display well-known control characters like newline and backspace as +\n or \b instead of \xa. + +2/15/95 (bug fix) Modified bitmap and photo image managers to delete +the image command when the image is deleted. Also modified them to +allow renaming of the image command, and to delete the image if the +image command is deleted. + +2/15/95 (bug fix) Fixed text widgets to allow horizontal scrolling +even if wrapping was enabled, if a line isn't entirely visible due to +a large character or embedded window. + +2/16/95 (feature change) Added "postcascade" widget command to menus, +changed "invoke" and "activate" not to post or unpost submenus. Also +fixed bug in redisplay that tended to leave bits of garbage on menu +when submenu unposted. +*** POTENTIAL INCOMPATIBILITY *** + +2/16/95 (feature removal) Removed "snap back" behavior (slider +snaps back to old position if you move the mouse outside the widet +before releasing the button) from scrollbars and scales. + +2/16/95 (bug fix) The last line of a listbox wasn't being displayed if +it was only partially visible. + +2/16/95 (new features) Added support for "-resolution 0" (no rounding +of values) to scale widgets, plus smarter computation of how many digits +to display. + +2/17/95 (bug fix) Fixed bug in text bindings for things like Shift-Left: +didn't properly set the anchor position. + +2/20/95 (bug fix) Changed management of COLORMAP_WINDOWS property to +add the toplevel implicitly to the end of the list if it wasn't already +on the list somewhere. Without this, some window managers implicitly +put it at the front of the list, so that colormaps in internal windows +are never used. + +2/20/95 (bug fix) Changed to use separate command procedures for +button, checkbutton, label, and radiobutton commands. This allows the +class commands to be renamed without breaking their behavior. + +2/20/95 (removed feature) The "bind" command no longer supports +"Keymap" events; they never worked anyway. + +2/20/95 (bug fix) The text "search" widget command looped infinitely +when searching an empty text. + +2/20/95 (bug fix) Canvases weren't redrawing their borders after +configuration changes. + +2/20/95 (upgrade) Changed to use autoconf version 2.2. + +2/21/95 (bug fix) Fixed several bug fixes in menu bindings that occur +when menus have no entries. + +2/21/95 (bug fix) Fixed bug in geometry management that caused windows +packed -in siblings to not always be mapped and unmapped properly +(particularly when the toplevel got unmapped and mapped). + +2/22/95 (bug fix) Fixed resource leak problem in tkTextDisp.c that +caused embedded windows not to be unmapped when off-screen. + +2/23/95 (bug fix) "After cancel" dumped core when the script for an +after event cancelled itself. + +2/24/95 (bug fix) Text and entry widgets weren't properly ignoring +Alt-, Control-, and Meta- keystrokes, so a widget-specific binding +for one of these resulted in the character also being inserted. + +2/24/95 (bug fix) Several widgets accidentally performed unsigned +division on negative numbers, thereby losing the sign bit. This +mostly affected the display of images and bitmaps in buttons, +menubuttons, and messages. + +2/24/95 (feature reversal) Restored old behavior of %A so that it +returns non-printing characters as well as printing ones now. +*** POTENTIAL INCOMPATIBILITY with Tk 4.0b2, but not with Tk 3.6 *** + +2/24/95 (bug fix) Duplicate "leave" events could occur for canvas +items under some conditions, due to recursive calls to PickCurrentItem. +Added code to detect and skip the nested calls. + +2/24/95 (bug fix) Fixed bug where an error could occur during the first +keystroke in an application if its binding invoked "break". + +2/25/95 (new feature) Modified syntax of "search" widget command for +texts. The -nowrap switch and the "variable" final argument are no +longer supported. Instead, there is a -count switch to replace +the final argument; if the final argument is specified, it is now +a stopping index for the search. The features of -nowrap can be +achieved now with the stopping index. +*** POTENTIAL INCOMPATIBILITY with Tk 4.0b2, but not with Tk 3.6 *** + +2/27/95 (bug fix) Fixed problem that appears to prevent keyboard +input for working under IRIX: tkBind.c was ignoring XmbLookupString +calls that returned a status of XLookupBoth. + +2/27/95 (new feature) Added Tk_GetItemTypes procedure to return +information about available canvas item types. + +2/27/95 (feature change) Changed Makefile to always use install-sh +for installations: there's just too much variation among "install" +system programs, which makes installation flakey. + +2/27/95 (bug fix) Fixed bug in tkSend.c that caused core dumps if +the app's main window was destroyed by a destroy handler on a +child. + +3/5/95 (feature change) Change separator character used in "bind +..." +bindings from semi-colon to newline (permits bindings that are +comments, for what that's worth). + +3/7/95 (bug fix/feature change) Overhauled focus code, both in C +and in Tcl: + - Tk won't move the X focus in response to the "focus" command + unless either the application already has the focus or the + -force switch is specified. + - Tk no longer sets the X focus to anything other than top-levels; + it synthesizes events for FocusIn and FocusOut to children. + - A window no longer has to be viewable when focussed to; Tk will + set the X focus later, when the window becomes viewable. + - Added -takefocus option to all widgets. + - Rewrote tk_focusPrev and tk_focusNext to use the -takefocus option. + These procedures no longer set the focus; they just return the + next window in focus order. + *** POTENTIAL INCOMPATIBILITY with Tk 4.0b2, but not with Tk 3.6 *** + - Eliminated tk_focusContinue. + *** POTENTIAL INCOMPATIBILITY with Tk 4.0b2, but not with Tk 3.6 *** + +3/8/95 (new feature, bug fix) Added support for tk_strictMotif variable +in C: Tk_StrictMotif library procedure. Modified buttons, menubuttons, +menus to use it. This fixes the problem with menus not supporting +tk_strictMotif properly in Tk4.0b1 and b2. + +3/16/95 (feature overhaul) Overhauled color management: + - Changed Tk so it never denies a color request because a colormap + filled up. Instead, it allocates the closest available color. + - Eliminated "color model" mechanism. The "tk colormodel" command + is gone, as are the procedures Tk_GetColorModel and Tk_SetColorModel. + *** POTENTIAL INCOMPATIBILITY *** + - Changed 3D border implementation to allocate colors for shadows + lazily, so they're never allocated if they're never used. Also + added new feature whereby stippling is used for borders when + the colormap has run out of entries. Changed arguments to many + of Tk_3D C procedures to take a Tk_Window as argument instead of + a (Display *). This is needed to do lazy color allocation. + *** POTENTIAL INCOMPATIBILITY *** + - Eliminated colormap argument to Tk_GetColor, Tk_GetColorByValue, + and Tk_Get3DBorder. + *** POTENTIAL INCOMPATIBILITY *** + +3/16/95 (feature change) Event bindings created from Tcl will now ignore +Enter, Leave, FocusIn, and FocusOut events with detail NotifyInferior. +This is done in anticipation of mega-widgets, so that the user of a +mega-widget can create Enter/Leave bindings on the mega-widget without +seeing spurious events as the mouse moves among the windows in the +mega-widget. +*** POTENTIAL INCOMPATIBILITY *** + +3/17/95 (feature change) Changed C interfaces throughout Tk to use ints +instead of unsigneds: the unsigneds turn out to cause subtle problems +with arithmetic in some places, and using ints everywhere is just +simpler. +*** POTENTIAL INCOMPATIBILITY *** + +3/23/95 (bug fix) Selections longer than 4000 bytes were being +truncated to 4000 bytes. + +-------------------- Release 4.0b3, 3/24/95 ------------------------- + +3/25/95 (bug fix) Changed "install" to "./install" in Makefile so that +"make install" will work even when "." isn't in the search path. + +3/25/95 (bug fix) Modified Tk's selection mechanism to prevent core +dumps in other applications during retrievals of large selections +(this is actually a bug in the other apps, but I've patched Tk to +keep it from getting triggered). + +3/25/95 (bug fix) Fixed bug where X window for "." wasn't being +deleted. + +3/27/95 (bug fix) Fixed many bugs associated with having more than +one application in a single process. + +3/28/95 (bug fix) The "search" widget command for texts didn't +return the correct index and count if there were embedded widgets +on the same line as the returned range but before the end of +the range. + +3/28/95 (bug fix) Changed pasting via button 2 in text and entries +so that it inserts at the pointer location, not the location of +the insertion cursor. + +3/28/95 (bug fix) Fixed several bugs related to <Destroy> bindings +that delete ancestors in the window hierarchy. Also eliminated +extraneous calls to XDestroyWindow, which speeds up window deletion +by about 3x. + +3/28/95 (bug fix) Several widgets (buttons, menubuttons, menus) didn't +properly handle image deletions that occurred while the widget was +being deleted (caused core dumps). + +3/29/95 (bug fix) When retrieving long selections from text widgets, +parts of lines were getting duplicated in the selection information. + +4/1/95 (bug fix) Fixed bug that caused infinite loop in horizontal +scales with 0 range. + +4/1/95 (bug fix) Fixed problem with -command option for scrollbars and +-takefocus option that caused commands to be evaluated in the wrong +context. + +4/1/95 (bug fix) Fixed problem with option database that caused it to +sometimes use the wrong option (wasn't flushing the database properly +after a change in a window's class). + +4/1/95 (bug fix) If a line in a text widget just barely fit in the window, +Tk was allocating a second screen line just for the newline character. + +4/1/95 (new feature) When backspacing in an entry widget, when you reach +the left edge of the widget, the insertion cursor gets recentered. + +4/1/95 (new features) Added "winfo pointerx" and "winfo pointery" commands +to fetch the current pointer position. + +4/6/95 (bug fix) If the last line of a text widget was only partially +visible, it was counted as visible for purposes of the scrollbar. Now +it is treated as if it were off-screen for scrolling purposes. + +4/6/95 (new feature) Modified "bell" command to reset screen saver as well. + +4/6/95 (feature change) Modified menu scanning (where menus pull down +as you drag across their menubuttons) so it only works among menus +in the same toplevel; it used to work for any menubuttons in the +application. + +4/6/95 (bug fix) Canvas text items weren't allowing real numbers in +"@x,y" notation for specifying indices. + +4/7/95 (bug fix) Menus didn't display correctly when -activeborderwidth +was large. + +4/7/95 (bug fix) Changed "clipboard append" command to support -- option +and to always treat the last argument as data, even if it starts with +"-". + +4/17/95 (new feature) Added -wrap option to text tags. + +4/18/95 (bug fix) Listboxes and texts weren't updating their grid information +when -width or -height changed. + +4/18/95 (bug fix) "Down" didn't work right in text widgets if the last +line was only partially visible in the window. + +4/19/95 (bug fix) Listboxes didn't handle partially visible last lines +right: couldn't scroll it into full visibility, for example. + +4/20/95 (bug fix) If a toplevel was positioned with a command like +"wm geometry . -0-0", the window didn't reposition itself to maintain +that geometry after a size change. + +4/21/95 (feature change) Changed order of binding tags so widget bindings +fire before class bindings. New order is: widget, class, toplevel, all. +*** POTENTIAL INCOMPATIBILITY with Tk 4.0b3, but not with Tk 3.6 *** + +4/23/95 (new feature) Added "winfo colormapfull" command. + +4/23/95 (new feature) Buttons and radiobuttons and checkbuttons now +treat Return the same as Space, unless tk_strictMotif is set. + +4/23/95 (bug fix) Modified menu tear-off procedure to duplicate the +binding tags and bindings of the original in the copy. + +4/25/95 (bug fix and feature change) Modified mechanism for choosing +"best" visual to fix a bug where depth wasn't really getting highest +priority in all situations. + +4/28/95 (bug fix) Failed text searches starting at "end" could result +in an infinite loop in Tk. + +4/30/95 (new feature) Added "wm resizable" command to enable and +disable interactive resizing. + +4/30/95 (new feature) Added "window names" widget command to texts: +returns a list of all embedded windows. + +5/2/95 (feature change) Changed text searches so that forward searches +start at the given index, rather than the character just after the +given index. +*** POTENTIAL INCOMPATIBILITY with Tk 4.0b3, but not with Tk 3.6 *** + +5/4/95 (bug fix) Default bit gravity for windows was wrong (it was +ForgetGravity) causing unnecessary flashing when windows were resized. + +5/4/95 (feature change) Modified Tk_DoOneEvent so that it doesn't +sleep if there's nothing that will wake it up again (e.g. no file +or timer handlers). Returns 0 immediately. + +5/5/95 (configuration change) Changed to use BSDgettimeofday instead +of gettimeofday on systems like IRIX where BSDgettimeofday is +available. This avoids compilation problems due to the different +interface to gettimeofday provided by IRIX. + +5/5/95 (feature change) Changed binding mechanism so that all bindings +are created immediately at initialization time, rather than waiting +until the first FocusIn or Enter event for a class. + +5/6/95 (feature change) Changed default text for labels, buttons, +checkbuttons, radiobuttons, menubuttons, and messages from " " to +"". + +5/6/95 (bug fix) If the application was destroyed in the middle of +an "update" command, Tk would dump core. + +5/6/95 (bug fix) Changed manual entries to use the standard .TH +macro instead of a custom .HS macro; the .HS macro confuses index +generators like makewhatis. + +5/6/95 (bug fix) Change "wm iconwindow" command to disable button +presses for the icon window. This is needed so that the window +manager can get those events (X only allows button presses to go +to one client for a given window). + +5/9/95 (new feature) When specifying visuals, can now use "best" +with a depth, e.g. "-visual {best 8}" to get the best 8-bit visual. + +5/18/95 (bug fix) Fixed bug with -spacing* options for text widget: +screen distances weren't allowed, only integers. + +5/20/95 (bug fix) Eliminated memory leaks in tkTextDisp.c and elsewhere. + +5/22/95 (color change) Changed the Tk color palette to a gray scheme. +Also added a library procedure tk_setPalette that makes it easy to +change colors on the fly, and a procedure tk_bisque that restores the +previous light brown scheme. + +5/28/95 (bug fix) Modified canvases so that the -width and -height +options refer to the space inside the borders, not the total widget +space. Also changed "xview" and "yview" commands and scroll-increment +rounding to use the pixel just inside the borders, rather than (0,0). + +5/28/95 (bug fix) Several widgets (e.g. entries, buttons, and menus) +didn't properly handle unsets of variables they were tracing, if the +variables were reference through upvars in procedures. + +6/4/95 (bug fix) The placer wasn't rounding window widths right when +both -relx and -relwidth were specified (or -rely and -relheight) so +that rounding errors accumulated. + +6/4/95 (feature improvement) Change parsing of text indices to handle +weird mark and tag names better (e.g. any string ending with ".first" +will now be parsed as a tag name, even if it contains embedded spaces, +etc.). + +6/4/95 (feature change) If a font defines glyphs for control characters, +they are now displayed, instead of translating the character to a +backslash sequence (however, tabs and newlines are still treated +specially; glyphs are not displayed for these characters). + +6/4/95 (bug fix) Modify the implementation of "raise" and "lower" for +toplevels so that it now works under olwm and olvwm. It didn't use to +work, and the problem is really in the window manager, but Tk now +patches around it. However, only "total" raises and lowers work: +raising and lowering relative to a sibling still don't work under +olvwm and olwm. + +6/4/95 (feature change) Modified tab code in texts so that a tab always +occupies at least as much space as a space character. + +6/4/95 (bug fix) The "%t" substitution wasn't being made properly in +Enter and Leave event bindings. + +6/7/95 (new feature) Added support for GIF images. Unfortunately it's +a bit fragile: certain kinds of badly formed images can cause core +dumps; I don't know enough about the GIF reader (taken from giftoppm) +to figure this out. + +6/7/95 (bug fix and feature change) Fixed PPM image reader to be more +flexible about header formats, and added support for PGM images. + +6/7/95 (feature change) Added -outlinestipple option to canvas arc +items, changed "-style arc" to use -outline as the color instead of +-fill (the old approach was pretty quirky). +*** POTENTIAL INCOMPATIBILITY *** + +6/8/95 (feature change) Modified interface to Tk_Main to pass in the +address of the application-specific initialization procedure. +Tcl_AppInit is no longer hardwired into Tk_Main. This is needed +in order to make Tcl a shared library. + +6/8/95 (feature change) Modified Makefile so that the installed versions +of wish and libtk.a have version number in them (e.g. wish4.0 and +libtk4.0.a) and the library directory name also has an embedded version +number (e.g., /usr/local/lib/tk4.0). This should make it easier for +Tk 4.0 to coexist with earlier versions. + +6/9/95 (new feature) Added -outline and -width options to canvas polygon +items. + +6/9/95 (feature changed) Renamed -decimate in photo widget to -subsample +(decimate wasn't technically correct). +*** POTENTIAL INCOMPATIBILITY with Tk 4.0b3, but not with Tk 3.6 *** + +-------------------- Release 4.0b4, 6/16/95 ------------------------- + +6/19/95 (bug fix) Colors weren't being rounded correctly in canvas +Postscript generation: caused "white" to appear slightly gray when +the display of the canvas used only 8 bits per color. + +6/20/95 (bug fix) "bbox" widget command for texts didn't return +proper width for tabs. + +6/20/95 (bug fix) Scrollbars didn't always work right for texts: +couldn't scroll all the way to the bottom of the text in a single +drag of the slider. + +6/20/95 (new feature) Added "delta" widget command for scrollbars +(needed for above bug fix). + +6/23/95 (bug fix) Listboxes weren't properly redisplaying their +borders when the were configured to a smaller size. + +6/23/95 (new feature) Added "winfo server" command. + +6/23/95 (bug fix) If a menu was posted, couldn't switch to another +menu with an Alt- key. + +6/24/95 (new feature) Added "winfo pointerxy" command. + +6/25/95 (bug fix) Tk_ParseArgv referenced beyond the end of 0-length +option names. + +6/25/95 (bug fix) Fixed problem in tkOption.c where "cachedWindow" +could get garbage in it if the main window's class was changed by +calling Tk_SetClass. + +6/25/95 (bug fix) Fixed two bugs in menus, one where errors in +variable traces weren't propagated correctly and one where "invoke" +was invoked at the wrong stack level, with the result that variable +traces didn't have access to the right variables. + +6/27/95 (bug fix) tk3d.c wasn't using all the right information +when deciding whether or not to stipple borders, so it stippled +borders even on 16-bit true-color displays. + +6/28/95 (bug fix) Page up and down operations in texts could cause +insertion cursor to drift to the right. Changed tkTextScrollPages +to use upper-left corner of current character, rather than center +of character. + +6/28/95 (bug fix) Changed text widget so that you can't put the +insertion cursor after the last newline in the text. + +6/28/95 (bug fix) Bitmap images didn't allow ~'s in file names. + +6/28/95 (bug fix) Fixed problem that could cause core dumps in the +text widget when dealing with embedded windows (there were problems +if the act of redisplaying caused the window layout to change, which +can happen with embedded windows). + +6/28/95 (bug fix) Texts didn't handle indices with double negatives, +such as ".t mark set insert {insert + -20 chars}". + +6/28/95 (bug fix) Fixed problem where focus didn't always revert to +its prior window after a dialog box was dismissed. + +6/28/95 (bug fix) Fixed problem with "search" widget command returning +incorrect length on some backwards regexp searches. + +6/28/95 (bug fix) Successive "wm iconbitmap . {}" commands could cause +a core dump. + +6/29/95 (new feature) Added -elementborderwidth option for scrollbars +so the -borderwidth can be set to 0 without flattening the arrows and +slider. + +-------------------- Release 4.0, 7/1/95 ------------------------- + +7/18/95 (bug fix) %t in event bindings didn't work properly for some +events (e.g. PropertyNotify). + +7/18/95 (bug fix) Changed "exec wish" lines in demo scripts to +"exec wish4.0" to avoid version conflicts. + +7/18/95 (bug fix) Fixed round-off errors in scrolling for texts, +canvases, listboxes, and entries. The error could cause the view +to shift up in a command like "$w yview moveto [lindex [$w yview] 0]". + +7/19/95 (bug fix) Canvases weren't always redrawing borders correctly +when they became unobscured. There were also some problems with +improper refresh after size changes. + +7/19/95 (bug fix) Fixed bug in text index processing that causes +tests textIndex-11.1 and textIndex12.1 to fail on some platforms. + +7/19/95 (bug fix) Fixed bug where 2-second delays were ocurring during +"raise" and "lower" commands for toplevel windows under some window +managers (such as fvwm). + +7/20/95 (bug fix) Text searches were misbehaving when there were embedded +windows on the starting line of the search. The most common symptom is +that Tk would fail to find a match at the starting position for the +search. + +7/22/95 (bug fix) Fixed core dump that could occur in menus if a checkbutton +entry's -variable option referred to an array (or couldn't be read +by the menu C code for some other reason). + +7/22/95 (bug fix) Text widgets didn't update their scrollbars when +changes were made to information that was off-screen. + +7/25/95 (bug fix) Fixed core-dump in tkListbox.c that used to happen +in the command ".l bbox end" if the listbox was empty. + +7/25/95 (bug fix) Page-up and page-down bindings for listboxes didn't +move active element to remain on the screen. + +7/25/95 (bug fix) Patched around H-P compiler problem that results in +core-dumps in tkImgPhoto.c during image handling. + +7/25/95 (bug fix) Fixed bug in tkImgPhoto.c that caused core dumps +(during Tk self-tests and other image uses) on AIX and other machines +where "schar" in tkImgPhoto.c was being defined as "short" instead of +"char". + +7/26/95 (bug fix) The PPM image reader couldn't handle maximum intensity +values other than 255. + +7/26/95 (bug fix) Canvases didn't redraw their borders when the relief +changed from raised to flat. + +7/27/95 (bug fix) Canvases didn't set the scrolling values correctly +when no scroll region was specified. + +7/28/95 (bug fix) Modified menu and tk_dialog scripts to restore any +old grab that might have been in effect before a menu or dialog was +posted. + +----------------- Released patch 4.0p1, 7/29/95 ---------------------- + +8/4/95 (bug fix) Calls to toupper and tolower weren't using the UCHAR +macro, so they didn't always work in non-U.S. locales. (JO) + +8/14/95 (new feature) Added -tearoffcommand option for menus. + +8/16/95 (bug fix) Canvases didn't generate proper Enter and Leave +events if the Leave handler for an item reconfigured the canvas in +a way that made the old current item the new current item again. (JO) + +8/21/95 (bug fix/feature change) When -takefocus was a script, Tk +was allowing window viewability to override it. Changed so that +viewability is now ignored when -takefocus is a script. (JO) + +8/21/95 (bug fixes) Fixed memory leaks in tkSend.c, tkSelect.c, and +tkUnixWm.c (JO). + +8/21/95 (bug fix) Text widgets didn't handle commands like +".t search -backwards foo end 1.0" properly: never found foo. (JO) + +8/23/95 (new feature) Added Makefile and configure.in support for +dynamic loading. (JO) + +8/25/95 (bug fix) The "frame" and "toplevel" commands couldn't safely +be renamed, due to a kludgy way that they shared a single command +procedure. Split into separate procedures. (JO) + +8/25/95 (bug fix) Fixed bug in libary/menu.tcl that caused "grab +window not visible" errors for popup menus (and perhaps elsewhere?). (JO) + +8/25/95 (bug fix / new feature) The "gray25" bitmap was really only +12.5% on, not 25%. Added new "gray12" bitmap that is the same as the +old "gray25". "Gray25" is still supported for compatibility, but its +use is deprecated. (JO) + +8/25/95 (bug fix) Scrollbar bindings didn't properly handle case where +B2 is clicked while B1 is already down. (JO) + +8/26/95 (bug fix) Menus were ignoring -activebackground if tk_strictMotif +was set, but not -activeforeground. Changed to ignore both. (JO) + +8/26/95 (bug fix) Scales and scrollbars didn't properly handle a +-repeatdelay value of 0 (they shouldn't auto-repeat in this case). (JO) + +8/28/95 (bug fix) Tcl errors were occurring for tkPriv(oldGrab) when +clicking on a disabled option menu. (JO) + +8/28/95 (bug fix) Changed event-handling code to use FD_SETSIZE instead +of OPEN_MAX, since OPEN_MAX is incorrect on some systems (e.g., IRIX). (JO) + +8/28/95 (bug fix) Fixed bug in photo images that caused garbling of +image data in the "put" and "copy" commands if the source data had +only one scan line but had a width less than the width of the target +image. (JO) + +8/29/95 (bug fix) Tk used to refuse to post menus if they had no +entries. This made it impossible for a menu to fill itself the first +time it is posted. Changed to allow menus with no entries to be +posted. (JO) + +8/30/95 (bug fix) If there was extra space at the bottom of a menu, +it wasn't being redisplayed properly. + +8/30/95 (new feature) Added -transient option to menus. + +8/30/95 (new features) Added proper button 2 support to both scrollbars +and scales (it sets the slider position from the mouse position). (JO) + +8/30/95 (bug fix) Fixed potential core dump that could occur in +photo images (ReadPPMFileHeader could overflow buffer under some bad +inputs, such as certain GIF images). (JO) + +8/30/95 (bug fix) Errors of the form `syntax error in expression "!"' +could occasionally happen in tkScaleDrag. (JO) + +8/31/95 (new feature) Changed man page installation (with "mkLinks" +script) to create additional links for manual pages corresponding to +each of the procedure and command names described in the pages. (JO) + +9/1/95 (new feature) Added "after info" command. Also added checks +so that one interpreter can't cancel another's "after" events. (JO) + +9/8/95 (bug fix) Fixed bug that could cause memory corruption and core +dumps if a "fileevent" handler was deleted while the handler was +active. (JO) + +9/11/95 Reorganized Tk sources for Windows and Mac ports. All sources +are now in subdirectories: "generic" contains sources that work on all +platforms, "windows", "mac", and "unix" directories contain platform- +specific sources. (SS) + +9/11/95 (new feature) Added new "notifier" mechanism to allow multiple +implementations of the mechanisms for finding out about events. This +change was necessary to support Mac and PC platforms, but it may also +allow other goodies such as combining Xt and Tk widgets in a single +application. See the new manual entry Notifier.3 for details. (SS) + +9/11/95 (feature change) Changed interface to Tk_RestrictProc so that +(a) it takes a clientData argument instead of display and arg, and +(b) it returns a value that can ask for the event to be discarded as well +as deferred or processed. (SS) +*** POTENTIAL INCOMPATIBILITY *** + +9/11/95 (new feature) Added TK_WINDOW_EVENTS #define, which is equivalent +to TK_X_EVENTS but is now preferred, since it applies to all platforms. (SS) + +9/11/95 (feature change) Can't export variables anymore because this doesn't +work under Windows DLLs. Eliminated tk_NumMainWindows variable and replaced +with procedure Tk_GetNumMainWindows. (SS) +*** POTENTIAL INCOMPATIBILITY *** + +9/11/95 (new feature) Added procedure Tk_PreserveColormap to increment +the reference count on colormaps. Used in photo widgets. (SS) + +----------------- Released patch 4.0p2, 9/15/95 ---------------------- + +----------------- Released 4.1a1, 9/15/95 ---------------------- + +9/22/95 (renamed files) Changed the names of the bitmap images in the +$tk_library/demos/images directory to use the .bmap file extension. (RJ) + +9/22/95 (bug fix) Fixed bug where text widgets could occasionally +display the insertion cursor both at the end of one line and the +beginning of the next. (JO) + +9/25/95 (bug fix) Fixed bug that could cause core dumps when an +application uses multiple screens and a binding destroys the main +window (bind code was using MainInfo structure after it had been +freed). (JO) + +9/25/95 (bug fix) Text widgets sometimes scrolled backwards on +occasion if you dragged down past the bottom of the scrollbar. (JO) + +9/25/95 (bug fix) Fixed bug in menus where a cascaded submenu posted +from a torn-off menu could be left posted if mouse was pulled off the +end of the cascade and released. (JO) + +9/25/95 (new feature) Added "--" switch to wish, so that you can +pass arguments like -n through to a script without having wish +interpret them. (JO) + +9/25/95 (bug fix) Fixed core dump that could occur for radiobuttons +and selectbuttons if -selectcolor was an empty string. (JO) + +9/26/95 (bug fix) Entries didn't used to notice if a trace procedure +on the -textvariable overrode a new value set by the entry. This +could cause the variable to get out of sync with the contents of the +entry. (JO) + +9/26/95 (new feature) Added -sliderrelief option to scales, changed +default bindings to change the slider's relief to sunken while it's +being dragged with the mouse. (JO) + +9/26/95 (bug fix) TkColor.c wasn't computing colormap size correctly; +could result in X Protocol error for QueryColors when colormaps run +out of colors. (JO) + +9/26/95 (bug fix) Wish couldn't handle script files with spaces in +their names. (JO) + +9/27/95 (cosmetic clean-up) Removed extraneous spaces to make error +messages consistent: ": should be" is now ": should be". (JO) + +9/27/95 (feature change) Modified tk_dialog so that it uses the +option database for the -wraplength option on the message. This +allows the option to be overridden by the caller. (JO) + +9/28/95 (bug fix) Wish incorrectly parsed the command line under +Windows, causing backslashes to be substituted. (SS) + +9/28/95 (bug fix) Wish now sources wishrc.tcl instead of .wishrc. (SS) + +9/28/95 (bug fix) Tk_DoOneEvent returned 0 under some circumstances +when it was possible to find more work to do. For example, if a +signal interrupted select(), but no event handlers were triggered, it +would return 0 even though it could still detect events by reentering +select(). (SS) + +9/29/95 (bug fix) "winfo interps" caused a crash under Windows. (SS) + +10/1/95 (feature change) Eliminated Tk_NotifyIdle interface in favor of +Tk_IdlePending. (SS) + +10/1/95 (bug fix) Turned motion event collapsing into an idle handler +so it will be easier to move the event loop into Tcl. (SS) + +10/1/95 (bug fix) Fixed several problems with negative coordinates +in canvases. One example: dragging a canvas rectangle with a wide +border and fractional coordinates could leave junk on the screen +if the rectangle was in negative coordinate space. (JO) + +10/2/95 (bug fix) Tk was improperly handling Enter/Leave events +during a button grab. (SS) + +10/2/95 (new feature) Added support for the Macintosh do script +('dosc') event. Available only on the Macintosh. (RJ) + +10/4/95 (new feature) Added support for compiling with VC++. +Resulting binaries work under Win32s through NT. + +----------------- Released 4.1a2, 10/6/95 ---------------------- + +10/10/95 (new feature) Macintosh Tk now supports the complete set +of X cursors that Unix Tk supports. (RJ) + +10/11/95 (bug fix) Tk now supports all of the X11 cursors under +Windows. (SS) + +10/11/95 (bug fix) The "wm resizable" command was missing from the +Windows version of Tk. (SS) + +10/12/95 (bug fix) Macintosh Tk had problems with clipping toplevel +windows that children of any frame other than another toplevel. (RJ) + +10/13/95 (bug fix) Eliminated dependency on MKS toolkit for generating +the tk.def file from Borland object files. (SS) + +10/16/95 (bug fix) Fixed clipping and update problems relating to +the raising and lowering of overlapping windows on Mac. (RJ) + +10/30/95 (bug fix) When focus-follows-mode (invoked via tk_focusFollowsMouse), +was focussing on windows even in situations where keyboard traversal would +skip the window. Changed to use the tkFocusOK procedure so that the +criteria for focussing are the same in both modes. (JO) + +11/2/95 (bug fix) Changed listbox bindings to ignore double-clicks. +This avoids errors that used to occur if a user defined a binding +for double-click that deleted the listbox. (JO) + +11/3/95 (feature change) Moved most of the Tk event loop to Tcl. Many +Tk_ names have become Tcl names now: + +TK_READABLE => TCL_READABLE +TK_WRITABLE => TCL_WRITABLE +TK_EXCEPTION => TCL_EXCEPTION +TK_DONT_WAIT => TCL_DONT_WAIT +TK_WINDOW_EVENTS => TCL_WINDOW_EVENTS +TK_FILE_EVENTS => TCL_FILE_EVENTS +TK_TIMER_EVENTS => TCL_TIMER_EVENTS +TK_IDLE_EVENTS => TCL_IDLE_EVENTS +TK_ALL_EVENTS => TCL_ALL_EVENTS +Tk_IdleProc => Tcl_IdleProc +Tk_FileProc => Tcl_FileProc +Tk_TimerProc => Tcl_TimerProc +Tk_TimerToken => Tcl_TimerToken +Tk_BackgroundError => Tcl_BackgroundError +Tk_CancelIdleCall => Tcl_CancelIdleCall +Tk_CreateFileHandler => Tcl_CreateFileHandler +Tk_CreateTimerHandler =>Tcl_CreateTimerHandler +Tk_DeleteFileHandler => Tcl_DeleteFileHandler +Tk_DeleteTimerHandler =>Tk_DeleteTimerHandler +Tk_DoOneEvent => Tcl_DoOneEvent +Tk_DoWhenIdle => Tcl_DoWhenIdle +Tk_Sleep => Tcl_Sleep +tkerror => bgerror + +Other than the name changes, the functions are the same. In addition, +there are #defines in tk.h so that the old Tk names will still work. +tkerror and bgerror are specially hacked as synonyms, so it should be +safe to use either one. You should switch to the new Tcl names ASAP, +though, since the old Tk names will eventually be desupported. (JO) + +11/7/95 (features removed) As part of moving the event loop to Tcl, +the following procedures were deleted: + - Tk_EventInit (the presence of the event loop in Tcl should + make this unneccessary). + - Tk_CreatFileHandler2 (you can get the same effect by using event + sources in Tcl, but you have to modify your code to use the new + Tcl APIs). + - All of the stuff in the manual entries Notifer.3 and QueueEvent.3; + this has changed because the notifier got reworked when it was + moved to Tcl. +*** POTENTIAL INCOMPATIBILITY *** + +11/7/95 (feature change) Changed to use exit handler to cleanup windows +in Tk, so Tk no longer needs to have a private copy of the "exit" command. +(JO) + +11/7/95 (bug fix) If wish was invoked with a command-line geometry and +a script file (e.g. "wish foo.tcl -geometry 30x20"), and if one of +the windows created by the script used the -setgrid option, then the +width and height from the command line were lost. (JO) + +11/8/95 (bug fix) The "see" command didn't work quite right for texts: +if the window was small and you try to "see" a line just offscreen, +Tk centered the line (actually, mis-centered it) when it should have +aligned it at the top or bottom. (JO) + +11/9/95 (bug fix) The "send" command crashed if you tried to send to +a different display with "-displayof". (JO) + +11/9/95 (bug fix) The Symbol font didn't print right in Postscript +output, because of changes made to re-encode fonts to get proper +ISO Latin1 behavior. Changed the code not to re-encode the Symbol +font. (JO) + +11/13/95 (bug fix) Fixed Makefile.in and configure.in for UNIX so that +configure can be run from a clean directory separate from the Tcl source +tree, and compilations can be performed there. (JO) + +11/17/95 (bug fix) If a window was gridded, Tk still computed the +default maximum dimensions in pixel units, which resulted in windows +that could grow much larger than the screen. (JO) + +11/17/95 (bug fix) If a menus entries were all disabled, posting +the menu and typing Up or Down caused an infinite loop, locking +up the screen (JO). + +11/19/95 (bug fix) The focus wasn't being restored properly after a +menu selection in a cascaded menu. (JO) + +11/19/95 (bug fix) Menubutton's didn't stipple display their images +differently when disabled. Change to have the same behavior as buttons: +the image is stippled over in the background color when the menubutton +is disabled. (JO) + +11/21/95 (bug fix) Changes in display attributes such as font could +cause core dumps in the text widget under some circumstances involving +line wrapping. (JO) + +11/22/95 (bug fix/new feature) Changed both the placer and the packer +to ensure that slaves are unmapped whenever the master is unmapped. +This saves time that slaves might otherwise spend trying to redisplay +themselves when they're unmapped. (JO) + +11/22/95 (bug fix) Space and return keys didn't work for menus if +they were posted via Alt-x keystrokes. (JO) + +11/24/95 (bug fix) tk_dialog procedure had binding for <Return> that +always activated default binding, even if input focus was in some +other binding. Removed this feature, since existing focus support +will already "do the right thing". (JO) + +11/24/95 (bug fix) Both canvases and texts could dump core if a binding +(such as ButtonRelease on an internal item) deleted the widget. (JO) + +11/24/95 (feature change) Replaced "configInfo" file with tkConfig.sh, +which is more complete and uses slightly different names. Also +arranged for tkConfig.sh to be installed in the platform-specific +library directory. (JO) + +11/24/95 (bug fix) It was possible for a slave to be placed or packed +-in itself, with unpleasant consequences. It is now an error for the +slave to be its own master for geometry management. (JO) + +11/25/95 (bug fix) The -command option of scales was sometimes being +invoked spuriously (e.g. when the mouse moved in the scale without a +button down). This was because the scale wasn't rounding properly +when setting the scale value from its associated variable. (JO) + +----------------- Released patch 4.0p3, 11/28/95 ---------------------- + +12/18/95 (feature change) Moved Tk_Preserve, Tk_Release, and +Tk_EventuallyFree to Tcl, renamed to Tcl_Preserve etc. Added #defines +to tk.h so that the old names still work. (JO) + +12/23/95 (bug fix) If a single process had > 1 Tk application, Tk +didn't guarantee that the application names were unique, which could +cause all sorts of confusion with "send". (JO) + +12/23/95 (feature change) Eliminated Tk_CreateMainWindow and moved +all of its functionality to Tk_Init. All that you need to do now +to get Tk in an application is to call Tk_Init. Improved Tk_Init +so that -colormap and -visual command-line arguments are now passed +through to TkCreateFrame. Tk_Main is much simpler now, since a lot +of its functionality has moved to Tk_Init. (JO) +*** POTENTIAL INCOMPATIBILITY *** + +12/23/95 (new feature) Added support for Tcl_StaticPackage so +that Tk can now be loaded into slave interpreters with the "load" +command to create new applications. (JO) + +12/23/95 (new features) Added support for -colormap and -visual command- +line options for wish. (JO) + +1/4/95 (bug fix) Fixed keyboard code to properly handle alt-key +sequences for international keyboards and menu-accelerators. (SS) + +1/5/96 (bug fix) Scrollbar code sometimes generated errors on accesses +to tkPriv(relief) during control-clicks. (JO) + +1/9/96 (new feature) added the "grid" command to provide a table based +geometry manager. (SU) + +1/12/96 (performance optimization) Changed the way tag information is kept +in the text's Btree so the cost of adding and removing tag ranges is no longer +proportional to the number of unique tags in the text. In the old system +the cost of adding N unique tags was O(N-squared). The new implementation is +optimized for tags that only cover a small amount of text, measuring from +their earliest tag range to the end of their last range. In the best case the +cost of adding a tag range is unrelated to the number of unique tags, so the +cost of adding N tags is only O(N). In the worst case, where all tags +cover all the text, the cost is still O(N-squared) to add N such tags. +Deleting tags still has an O(N) cost (so deleting N tags is O(N-squared), +but it is now a factor of 2 faster than the old system. (BW) + +1/12/96 (new feature) added the text "dump" operation that returns information +about all elements in a text widget: text, tags, marks, and windows. (BW) + +1/12/96 (new feature) added the text "mark next" and "mark previous" operations +to search forward and backwards for the next (previous) mark in the text. (BW) + +1/12/96 (new feature) added the text "tag prevrange" operation to search +backwards for the current or previous range of a tag. (BW) + +1/16/96 (new feature) Added support for relative widget placement on +the "grid" command. (SU) + +1/17/96 (new feature) Modified the Makefile/configure setup to support +compiling Tk as a shared library. Use the --enable-shared option to +the "configure" script. (JO) + +----------------- Released 4.1b1, 1/26/96 ----------------------- + +2/2/96 (bug fix) Frames were getting a default size of 200x200, whereas +there should be no default. (JO) + +2/2/96 (bug fix) Argc wasn't getting reset properly after Tk removed +the arguments it understood from those on the command line. (JO) + +2/6/96 (bug fix) Fixed off by one error in argument parsing code under +Windows. (SS) + +2/6/96 (bug fix) "wm transient" now works under Windows. The resulting +toplevel is created with a modal dialog box frame and will not appear +in the taskbar under Windows '95. (SS) + +2/9/96 (bug fix) Changed Makefile.in to use -L and -l for Tcl and Tk +libraries so that shared libraries are more likely to be found correctly +on more platforms. (JO) + +2/14/96 (feature change) Eliminated tk_CanvasTagsOption variable because +it can't be exported safely across DLL boundaries. Instead, exported +Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc procedures for +use by canvas type managers in creating their own custom options. (JO) +*** POTENTIAL INCOMPATIBILITY *** + +2/14/96 (bug fix) "winfo pointerxy" when applied to a non-toplevel window +crashed wish. (SS) + +2/14/96 (bug fix) "tkwait visibility" would hang under Windows. (SS) + +2/14/96 (bug fix) Cursors were not being updated until an enter event. +In cases where the cursor left the toplevel and reentered before Tk +noticed, the cursor would get "stuck" until the next enter event. +Similarly, if the cursor attribute of a window was updated while the +mouse was in the window, the cursor would not change until the next +time the mouse entered the window. (SS) + +2/15/96 (bug fix) If a top-level was resizable in one direction +(e.g. "wm resizable . 0 1"), once the user resized it any changes +in the internally requested size (by the widgets) were ignored, +even for the non-resizable dimension. Fixed to handle the two +dimensions totally independently, so the widget's requests are +honored as long as that dimension hasn't been set by the user. (JO) + +2/17/96 (bug fix) If a text widget had very long lines (e.g. more than +32K pixels), integer overflow could occur, resulting in parts of the +line not being visible. (JO) + +2/20/96 (feature change) Changed the -minsize option of grid to take +screen units instead of pixels. (SU) + +2/20/96 (bug fix) grid row and column weights are compared against +MINWEIGHT (0.001) instead of 0.0 to guard against divide by zero errors +during weight normalization. (SU) + +2/20/96 (bug fix) Menu commands were not being invoked sometimes. +There was a race condition that caused events to be processed while a +menu was being unposted. (SS) + +----------------- Released 4.1b2, 2/23/96 ----------------------- + +2/23/96 (bug fix) Alt-keys invoked in torn-off and popped up menus +caused menus to be posted in the parent toplevel. (JO) + +2/23/96 (bug fix) Canvases weren't always updating their scrollbars +when they should. (JO) + +2/23/96 (bug fix) Fixed core dump that could occur if a WM_DELETE_PROTOCOL +handler generated an error. (JO) + +2/24/96 (bug fix) Removed dependencies on Makefile in the UNIX Makefile: +this caused problems on some platforms (like Linux?). (JO) + +2/24/96 (feature change) Changed text and entry widgets so that they +set the insertion cursor before inserting during a button-2 click. +Also made optional bindings check for tk_strictMotif at the time of +the event, rather than at the time the bindings are created. (JO) + +2/24/96 (bug fix) Tk tended to crash with an X error when unsetting +an icon window (e.g. "wm iconwindow . {}"). (JO) + +2/25/96 (bug fix) Wasn't removing windows from the WM_COLORMAP_WINDOWS +property when they were deleted. (JO) + +3/1/96 (new feature) Added new "bbox" widget command for entries. +Also modified mouse bindings for entries and texts so that the +mouse position rounds to the nearest inter-character gap, rather +than the left edge of the character under the mouse. This provides +more natural selection behavior. (JO) + +3/1/96 (bug fix) Fixed core dump that could occur in image code if an +image was deleted while in use in a widet, then re-used in another +widget while "deleted". (JO) + +3/1/96 (bug fix) Calling wish with a single argument caused a crash +under Windows due to an off-by-one error in the argument parsing code. (SS) + +3/1/96 (bug fix) Palette management was broken and resulted in +incorrect palette realization and refresh behavior. Also, images were +being drawn incorrectly if they were attached to widgets that had a +private colormap. (SS) + +3/2/96 (bug fix) It was possible to press the mouse button over an +option menu, drag to a pulldown menu, and have the pulldown menu +popup in place of the option menu. Fixed this so that option menus +are isolated from each other and from pulldowns. (JO) + +3/2/96 (bug fix) Fixed yet another bug that caused long delays when +raising toplevel windows. (JO) + +3/2/96 (bug fix) Fixed bug in canvases where zero-sized rectangles +and ovals didn't always redisplay right (could leave trailing +garbage on screen when moved). (JO) + +3/2/96 (bug fix) Entry widgets reset their insertion cursor, selection, +and view whenever the text variable changed, plus whenever a "configure" +widget command was invoked and there was a text variable for the +widget. Fixed to preserve this information as much as possible. (JO) + +3/5/96 (new feature) Added version suffix to shared library names so that +Tk will compile under NetBSD and FreeBSD (I hope). (JO) + +3/6/96 (bug fix) Changed the way certain configure & motion events are +reported. This fixes several bugs in menus & "winfo rootx". (RJ) + +3/7/96 (bug fix) Fixed tag remove bug that showed up when draging out a +selection. If you had dragged left, then tried to drag back right, the +left edge of the selection wasn't being updated because the tag remove +wasn't doing anything. (BW) + +3/7/96 (bug fix) Fixed the boundary conditions of tag prevrange. The second +index argument wasn't effecting in stopping the search if it fell within +a range. The second index has to come at or before the start of a range +for the range to be found by tag prevrange. (BW) + +3/7/96 (bug fix) "puts" to stdout or stderr when running from a script +caused wish41.exe to exit silently. Now the output is silently +discarded without generating an error. (SS) + +3/7/96 (bug fix) Fixed bug where wish was treating empty lines in the input +as end of input, if the input came from stdin. This would cause it to +complain about missing closing braces etc. (JL) + +----------------- Released 4.1b3, 3/8/96 ----------------------- + +3/9/96 (bug fix) Fixed bug in text.tcl that could cause errors in text +widgets of the form 'can't use non-numeric string as operand of "-"'. (JO) + +3/12/96 (feature improvement) Modified startup script to look in several +different places for the Tcl library directory. This should allow tk +to find the libraries under all but the weirdest conditions, even without +the TK_LIBRARY environment variable being set. (JO) + +3/14/96 (bug fix) "wish bogus_file_name" didn't print an error message. (JO) + +3/14/96 (bug fix) Button-2 wasn't claiming the focus during paste +operations. (JO) + +3/14/96 (bug fix) "tkwait visibility" use to hang forever if its window +was deleted. Now it detects this condition and returns an error. (JO) + +3/16/96 (bug fix) Changed configuration stuff to get dynamic loading and +shared libraries working under AIX. (JO) + +3/16/96 (bug fix) Fixed core dumps that could occur when a slave interpreter +was deleted in the middle of executin bindings. (JO) + +3/18/96 (new feature) Added support for Activate/Deactivate events. +Currently, these new X events will generated only on the Macintosh. (RJ/CS) + +3/21/96 (bug fix) The "tag prevrange" command would fail to return the current +range if it began at 1.0 and the starting point of the search was within +the range. (BW) + +3/21/96 (configuration improvement) Changed configure script so it +doesn't use version numbers (as in -ltk4.1 and libtk4.1.so) under +SunOS 4.1, where they don't work anyway. (JO) + +3/22/96 (bug fix) Made Tk more robust against interpreter deletion. Now it +should be safe to delete an interpreter with a Tk application inside it, +without first deleting the Tk application. (JL) + +3/26/96 (bug fix) Tk now returns results from a "send" to an interpreter +in which the Tk application is destroyed, if the interpreter continues +computing after the Tk application is destroyed. Previously any results +computed after '.' was destroyed in the target interpreter were discarded +by the "send". (JL) + +3/26/96 (new feature) Tk now provides a static Tktest package which is +present only in test versions of Tk; this allows the testing commands to +be loaded into new interpreters besides the main one. (JL) + +3/28/96 (bug fix) Changed the tk_dialog procedure *not* to make the +dialog a transient for its parent. The old behavior meant that the +dialog did not get posted if the parent was iconified. (JO) + +4/5/96 (bug fix) Tk would occasionally crash when destroying toplevels +under Windows. (SS) + +4/5/96 (bug fix) Fonts were not being properly deallocated, causing +GDI resources to be consumed and never released under Windows. (SS) + +4/11/96 (bug fix) Toplevel windows with no specified geometry were +always appearing in the upper left corner of the screen under +Windows. (SS) + +4/11/96 (bug fix) "wm minsize" did not properly report the minimum +size imposed by the Windows window manager. (SS) + +4/13/96 (bug fix) Text widgets could dump core in some cases where +text was inserted on the top visible line. (JO) + +4/16/96 (bug fix) Changed menu code to ignore errors that occur when +restoring a grab: the old grab window might not be visible anymore. (JO) + +----------------- Released 4.1, 4/21/96 ----------------------- + +5/1/96 (bug fix) "option readfile" did not handle files with CRLF +line termination. (SS) + +5/1/96 (bug fix) Changed to install tkConfig.sh under "make install-binaries", +not "make install-libraries". (JO) + +5/7/96 (bug fix) Moved initScript in tkUnixInit.c to writable memory to +avoid potential core dumps. (JO) + +5/7/96 (bug fix) Changed tk_dialog back so that the dialog box is a +transient window again. This is needed to make sure that the dialog +box doesn't get obscured. Also changed it to return -1 if the dialog +window is deleted before the user presses a button. (JO) + +5/16/96 (bug fix) Fixed bug that caused core-dumps if a text widget +with -setgrid 1 was deleted by removing its command. (JO) + +5/16/96 (bug fix) Fixed bug that caused Tk initialization to use improperly +initialized variables left over from previous invocation of Tk_Init on +another interpreter. (JL) + +5/16/96 (new feature) Implemented application embedding on Windows +platforms (only Tk inside another application, not the other way yet). (JL) + +5/16/96 (new feature) Added C API Tk_SafeInit that adds Tk to a safe +interpreter. (JL) + +5/16/96 (bug fix) Fixed bug that caused Tk initialization to use improperly +initialized variables left over from previous invocation of Tk_Init on +another interpreter. (JL) + +5/16/96 (new feature) Implemented application embedding on Windows +platforms (only Tk inside another application, not the other way yet). (JL) + +5/16/96 (new feature) Added C API Tk_SafeInit that adds Tk to a safe +interpreter. (JL) + +5/22/96 (bug fix) Listboxes weren't properly ignoring double clicks on +button 1. (JO) + +6/12/96 (bug fix) Focus was automatically placed on new toplevels. +This caused the titlebar to flash during menubar traversal. (SS) + +6/12/96 (bug fix) Iconification of a window with a specified geometry +by using the minimize button would leave the window in an inconsistent +state. When the window was deiconified using "wm deiconify", the +window would continue to display as an icon with the deiconified +geometry. (SS) + +6/12/96 (bug fix) Fixed a resource leak where the text widget was not +freeing all of the TkRegions it created. This fix affects all +platforms, but is particularly important for Win32s. (SS) + +6/21/96 (configuration change) Added --enable-gcc switch to configure +script to make Tk just like Tcl. Now Tk will not use gcc unless you +request it explicitly. (JO) + +7/18/96 (bug fix) Changed "configure" script to add an extra -R switch +(or whatever is appropriate to the platform) if the X library is in a +nonstandard place. This guarantees that the shared library can be +found at runtime without having to set the LD_LIBRARY_PATH variable. (JO) + +7/19/96 (bug fix) Fixed bug in tkImgGIF.c that cause core dumps if a +GIF file contained multiple images. (JO) + +7/20/96 (bug fix) Deadlock could occur if a recursive series of send +operations involved multiple displays. (JO) + +7/23/96 (bug fix) Fixed a resource leak where deallocated XIDs were +taking up memory on Windows and Macintosh platforms. (SS) + +7/30/96 (bug fix) A core dump could occur if a <Destroy> handler for +a window tried to create a child in the half-dead window. Fixed by +making the window's name disappear from the name table once it starts +to be deleted. (JO) + +----------------- Released patch 4.1p1, 8/2/96 ----------------------- + +4/30/96 (new feature) Added support for named virtual events. New "event" +command to define/destroy named virtual events and to programmatically +send both real and virtual events to Tk. (CS) + +8/6/96 (bug fix) Entry widgets were invoking scrollbar update functions +too often. (JO) + +8/9/96 (bug fix) 7/30 change above for <Destroy> handlers broke many +things by making window available during Destroy handler. Reworked +fix for core dump to simply disallow creating children of half-dead +parents. (JO) + +8/12/96 (bug fix) Fixed bug where using the Copy menu item on the +Macintosh would append a NULL character at the end of the text. (RJ) + +8/15/96 (bug fix) Fixed Mac code so garbage wouldn't be printed in +text and entry widgets when function & other non-printing keys were +pressed. (RJ) + +8/15/96 (configuration improvement) Changed the file patchlevel.h +to be tkPatch.h. This avoids conflict with the Tcl file and is now +in 8.3 format on the Windows platform. (RJ) + +8/19/96 (bug fix) Fixed a bug under Windows where the initial window +position for a toplevel window was reported as +0+0, regardless of the +actual position. (SS) + +8/21/96 (bug fix) If the last character on a line in a text widget was +a space character that didn't completely fit, the text widget would +sometimes add an extra wrap line. (JO) + +8/22/96 (feature change) Complete rewrite of the grid geometry manager. +There is a new layout algorithm that produces better (but different) +layouts in many common cases. (SU) + +8/22/96 (new feature) There are two new options for the grid geometry +manager, "grid update" which forces an immediate layout calculation, +and a "-pad" option to rowconfigure and columnconfigure that allows for +extra space around widgets. (SU) + +8/22/96 (feature change) The order in which the grid geometry manager +reports slaves is now last-managed first. (SU) + +8/22/96 (feature change) The column and row weights in the grid +geometry manager are kept internally as integers, instead of floating +point values. Floating point values are still accepted on the command line, +but are truncated to integers. (SU) + +8/22/96 (new feature) There are four new commands for opening common +dialog boxes: tk_chooseColor, tk_getOpenFile, tk_getSaveFile and +tk_messageBox. Native dialog boxes are used wherever available. (IL) + +8/22/96 (new demos) Added "fsbox", "msgbox" and "clrpick" demos. (IL) + +8/23/96 (feature change) Invoking the edit menu on the Macintosh now +generates the following virtual events <<Cut>>, <<Copy>>, <<Paste>>, +and <<Clear>> instead of faking key events. (RJ) +*** POTENTIAL INCOMPATIBILITY *** + +8/25/96 (bug fix) Fixed a bug that would cause "grid x" to dump core. (SU) + +8/26/96 (new feature) Added the "unsupported1" command to the +Macintosh version of Tk. This command will allow you to set the style +of a new toplevel Window (much like overrideredirect). You can use +this to get access to all of the Native Mac window styles. This is to +hold you over until we get a more general solution added to the +toplevel command. (RJ) + +8/26/96 (new feature) Added support to handle the zoom box on a +Macintosh window. (Currently, you can only get a Tk window with a +zoom box by using the "unsupported1" command. (RJ) + +8/27/96 (documentation change) Removed old change bars (for changes in +Tk 4.1 and earlier releases) from manual entries. (JO) + +----------------- Released 4.2b1, 8/30/96 ----------------------- + +9/5/96 (bug fixes) Fixed several bugs in file dialogs: individual files +could be listed twice, if a long list of files were shown, and the view +scrolled to the right, and then a different file file was shown, the +scrollregion on the canvas wasn't being reset, so the file dialog was +broken from then on, added an update idletasks so that the watch +cursor was shown when the dialog was thinking. For the motif file +dialog, fixed the weights for resizing. On the clrpicker, fixed the +finalColor variable which caused problems when the OK button was +"clicked" before the dialog was mapped (in the test suite). Added Ioi's +last changes from before he left. For message boxes, if a single button +message box is shown (currently only 'ok'), it is set to be the default +even if not specified. (KC) + +9/5/96 (bug fix) Fixed bug on Macintosh where menus would appear in a +seemingly random location. (RJ) + +9/5/96 (bug fix) Text widgets had rounding problems with the "yview" +command that caused them sometimes to round to the line before the +correct one. (JO) + +9/5/96 (bug fix) Changed grab code to retry grabs after errors where +another application already has the grab. This is needed to get +around race conditions with some window managers and will hopefully +solve the grab errors that people see occasionally. (JO) + +9/6/96 (bug fix) Fixed x-y coordinate confusion problem with scaling +of window items in canvases. (JO) + +9/11/96 (bug fix) The open and save file dialogs would change the +current working directory under Windows. (SS) + +9/12/96 (bug fix) The Tk event system was delivering events to dead +windows, if the event handler got reentered during a Destroy event +handler. This could cause core dumps and other problems. (JO) + +9/20/96 (bug fix) In XFillRectangles under Windows, a brush was not +being deallocated. (SS) + +9/20/96 (bug fix) The Mac window manager used to generate a mouseUp +event for a top level that was recently raised to the front/active +window which often caused a tk(priv) error. The up event is no +longer generated with solves several problems. (RJ) + +9/25/96 (bug fix) The font code under Windows was leaking memory +whenever a new font was referenced using the three part font names. (SS) + +9/26/96 (bug fix) The tests for the common dialogs still used the 'testevent' +function. I updated these calls in clrpick.test, msgbox.test, filebox.test +to use the new event gereating mechanism. + +9/18/96 (bug fix) Long-standing bug in bind where <Button-1><Button-1> was +reported as <Double-Button-1>, but <Double-Key-a> was reported as "aa". (CS) + +9/27/96 (bug fix) Bindings didn't work on 64-bit machines due to changes +made for virtual events. (CS) + +9/30/96 (feature change) Binding for new virtual events included both +lower and upper-case, e.g., <<Copy>> was defined as <Control-c> and +<Control-C>. Previously, widgets were directly bound to only lower-case +bindings. The upper-case binding caused incompatibility with some existing +Tcl programs, so the upper case bindings for <<Cut>>, <<Copy>>, and <<Paste>> +were removed. (CS) + +9/30/96 (bug fix) The postscript code in the canvas widget now uses +channels to get and write .ps files which fixed a bug on the Mac where +an output file would have mixed EOL characters. In addition, I added +the ability for the prolog to come from the Tk shared library on the +Mac which makes it possible to have a standalone application. (RJ) + +10/1/96 (feature change) "grid forget" was renamed "grid remove". A new +command "grid forget" was added whose semantics are the same as "pack forget" +(SAU) +*** POTENTIAL INCOMPATIBILITY *** + +10/1/96 (feature change) grid no longer accepts floating point values for +row or column weights, integers must be used. (SAU) +*** POTENTIAL INCOMPATIBILITY *** + +10/1/96 (feature change) "grid {column,row}configure <master> <index>" +returns a list of option value pairs for all of the row or column +constraints. It used to return an error. (SAU) + +10/1/96 (bug fix) "The way grid handles '^' short-cuts was re-written +to eliminate core dumps. (SAU) + +10/3/96 (feature change) A virtual event binding associated with a +given physical event is now considered less specific than a binding for +that same physical event, all other things being equal. (CS). + +10/3/96 (bug fix) Under Windows text placed on the clipboard did not +undergo CRLF translation when delivered to other applications. (SS) + +10/3/96 (bug fix) Copying an image onto itself with a zoom factor that +caused the image to grow was accessing freed memory. (SS) + +10/3/96 (bug fix) Under Windows, the image blank subcommand did not +work. (SS) + +10/10/96 (bug fix) Under Windows & Macintosh, XSetFont and XChangeGC +were not implemented, and XSetLineAttributes did not correctly update +the GC. (SS) + +10/10/96 (bug fix) Under Windows, 8-bit non-palette displays were not +handled properly. (SS) + +10/10/96 (bug fix) Under Windows, images of depth other than 8 or 24 +bits were not being rendered properly. (SS) + +10/10/96 (bug fix) Under Windows, bitmap subimages were not correctly +displayed. (SS) + +10/14/96 (bug fix) Under Window, wm resizable would constrain both +programatic resizes as well as user resizes. (SS) + +----------------- Released 4.2, 10/16/96 ----------------------- + +10/17/96 (bug fix) XCopyPlane was broken under Windows and would cause +a crash when used with a clipping bitmap. (SS) + +10/21/96 (bug fix) Added missing resources needed by tk_getOpenDialog +on the Macintosh to the shared library for Tk. (RJ) + +10/22/96 (bug fix) Invoking a menu with an Alt key sequence caused an +error due to a misplaced common in library/menu.tcl. (JO) + +10/23/96 (bug fix) Errors in files sourced by the Macintosh +"Source..." menu are now correctly reported via the background +error mechanism. (RJ) + +10/23/96 (bug fix) Fixed a bug in the Mac subwindow implementation +that caused refreshes to not occur for canvases with embedded +windows. (RJ) + +10/24/96 (bug fix) Provided workaround for Apple bug that doesn't +handle zooming correctly for floating windows. (RJ) + +10/24/96 (bug fix) Macintosh tearoff menus are now correctly +displayed as Mac floating windows. (RJ) + +11/1/96 (bug fix) Restored manual page for procedures like +Tk_CreateWindowFromPath and Tk_DestroyWindow; was accidentally deleted +when Tk_CreateMainWindow procedure was decommissioned. (JO) + +11/19/96 (bug fix) Fixed bugs in postscript code that would cause the +prefix to not be included and the output file to have the wrong +permissions. (RJ) + +12/2/96 (bug fix) Fixed problem with canvas lines where it didn't +compute bounding boxes correctly for zero-width lines: this could +potentially leave garbage on the screen when items were deleted or +moved. (JO) + +12/5/96 (bug fix) Fixed the Macintosh implementation of pointer x/y +which was returning garbage. (RJ) + +12/6/96 (bug fix) Fixed grid bug where the positioning of slaves was +incorrect for non-zero values of ipadx and ipady (SU) + +12/6/96 (bug fix) Fixed grid bug where slaves got "lost" when an +already managed slave is re-managed in a different master. (SAU) + +----------------- Released 4.2p1, 12/8/96 (Mac only) -------------- + +1/17/97 (bug fix) Fixed bug where the Tk clipboard was not in sync +with the Macintosh clipboard on start-up. (RJ) + +----------------- Released 4.2p2, 1/31/97 -------------- + +---------------------------------------------------------- +Changes for Tk 4.2 go above this line. +Changes for Tk 4.3 go below this line. +---------------------------------------------------------- + +9/19/96 (improvement) Implemented table driven mechanism for deciding +whether a command is safe. If it is added by Tk_Init and it appears in the +table then it is kept, otherwise it is removed in a safe interpreter. (JL) + +10/18/96 (new feature) Added support for application embedding: + - Frame and toplevel widgets now have a -container option, which + turns the widget into a container. + - Toplevel widgets have a -use option for requesting that the + widget be embedded in another application. + - Wish also supports a -use command-line option. +Embedding is fully supported under Unix, but the implementation is +not complete under Windows or the Macintosh (it works just well +enough to support the Tcl/Tk plugin). (JO) + +10/22/96 (bug fix) The commands "winfo rootx" and "winfo rooty" didn't +work for non-toplevel windows in embedded applications: they returned +the coordinates of the nearest toplevel. (JO) + +12/02/96 (new feature) Implemented Safe Tk. Tk can now be loaded into a +safe interpreter that has been created with tcl_safeCreateInterp, by +calling load {} Tk interpname. (JL) + +12/02/96 (new feature) A safe Tk interpreter can no longer generate +postscript output from a canvas. (JL) + +12/02/96 (new feature) Added -channel option to photo command to allow +image data to be read from a channel. This is useful in safe Tk +interpreters where the data cannot be read directly from a file. (JL) + +---------------------------------------------------------- +Changes for Tk 4.3 go above this line. +Changes for Tk 8.0 go below this line. +---------------------------------------------------------- + +9/1/96 (new features) The font mechanism in Tk has been completely +reworked: + - Font names need not be nasty X LFDs: more intuitive names like + {Times 12 Bold} can also be used. See the manual entry font.n + for details. + - Font requests always succeed now. If the requested font is not + available, Tk finds the closest available font and uses that one. + - Tk now supports named fonts whose precise attributes can be + changed dynamically. If a named font is changed, any widget + using that font updates itself to reflect the change. + - There is a new command "font" for creating named fonts and querying + various information about fonts. + - There are now officially supported C APIs for measuring and + displaying text. If you use these APIs now, your code will + automatically handle international text when internationalization + is added to Tk in a future release. See the manual entries + MeasureChar.3, TextLayout.3, and FontId.3. + - The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct, and + Tk_FreeFontStruct have been replaced with more portable procedures + Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont. + *** POTENTIAL INCOMPATIBILITY *** +(CS) + +9/24/96 (bug fix) Under Windows, transient windows would be destroyed +if their master was destroyed, even if the transient window was not a +child of the master. (SS) + +10/18/96 (new features) A -menu option has been added to the toplevel +widget command, which allows a menu to operate as a menubar. On the +Macintosh, the menubar is displayed accross the top of the main monitor, +just like with other applications. Under Windows and Unix, the menu is +attached to the toplevel window. Also, changed some semantics. +Tearoff menus will now reflect changes to the menu it was +torn off from, and are deleted when the master menu is +deleted. Tearoffs also reflect more look-and-feel of the +platforms they are running on. (SRP) + +10/31/96 (bug fix) Under Windows, missing system cursors would +generate an error instead of falling through to the Tk cursor of the +same name. (SS) + +11/7/96 (feature change) Under Unix, default borderwidth is now 1 to +more closely approximate CDE. (SS) +Note: this change was undone on 6/12/97, restoring the default border +width to 2 again. (JO) + +11/7/96 (new feature) The button widget now supports a -default option +that draws a platform specific default ring around the widget. (SS) + +11/7/96 (feature change) Under Windows, buttons and scrollbars now +have native look and feel. This affects the default class bindings +and the way the some configuration options are interpreted. Refer to +the widget manual pages for more details. (SS) +*** POTENTIAL INCOMPATIBILITY *** + +11/19/96 (bug fix) Under Windows, images were incorrectly drawn on +16-bit displays. (SS) + +11/19/96 (bug fix) Under Windows, the class name for the main window +(.) was not properly generated from argv0. (SS) + +11/20/96 (bug fix) Fixed a couple of bugs in the Canvas widget. The +postscript file is now created with the correct permissions. Also, +the prolog is now properly included in all cases. (RJ) + +11/22/96 (bug fix) Under Windows, the initial directory and file names +were not properly translated before being passed to the system +open/save file dialogs. So forward slashes were not converted to +backslashes, and tilde substitution was not performed. (SS) + +11/25/96 (feature change) Under Windows and Macintosh, the selection +highlight is now hidden whenever an entry or text widget loses focus. +Also, the previous selection information is not lost when a new +selection is made in a different widget. (SS) + +11/26/96 (new feature) Added support for images as primitive types in +text widgets. (SU) + +11/30/96 (configuration improvement) Modified configure.in to handle the +case where Tcl and Tk are installed in different places by including both +their library directories in the library search path for Tk. (JO) + +12/3/96 (bug fixes) Fixed two bugs related to canvas lines that caused +the screen to be incorrectly refreshed, leaving garbage on the screen. +One bug was related to lines with width zero, and the other was +related to lines with very long miters. (JO) + +12/4/96 (bug fix) The "update" command was only syncing the display +for its main window. Changed to sync all displays. (JO) + +12/5/96 (bug fix) Color deallocation would occasionally cause a panic +under Windows. (SS) + +12/5/96 (bug fix) Errors during startup were silently discarded under +Windows. (SS) + +12/5/96 (bug fix) Errors during startup were silently discarded under +Windows. (SS) + +12/11/96 (bug fix) Text widgets weren't considering the -spacing1 +and -spacing2 options when computing their desired geometry. (JO) + +12/12/96 (feature change) Option menus using tk_optionMenu were +created with command entries that set the option menu's variable in a +command string. This has been changed so that the option menu's +entries are now radiobutton entries so that the entries that matches +the variable is now checked when the menu is posted. (SRP) + +12/12/96 (feature change) The destroy command no longer returns an +error when a window does not exist. (SRP) + +12/13/96 (new feature) grid row/column-configure accepts a list of +indices in addition to a single index. (SU) + +12/17/96 (bug fix) Under Windows, command line was not being parsed +correctly if it contained the literal characters \" (CS) + +12/17/96 (feature change) Native Windows labels do not get a focus-ring +border. (CS) + +12/17/96 (bug fix) Under Windows, colors specified as "#XXYYZZ" where XX, YY, +or ZZ were not valid hex digits were getting a random color value instead of +being an error. (CS) + +----------------- Released 8.0a1, 12/17/96 ----------------------- + +12/23/96 (bug fix) Fixed two menu bugs: + - Menus could get stacked below other windows so that they weren't + visible when posted (especially under olvwm and fvwm). + - Under olvwm if you pressed button 1 over an entry in a new-style + menubar, the menu didn't appear until you moved the mouse slightly. +(JO) + +1/6/97 (bug fix) Focus could accidentally get grabbed by an application +away from the rightful focus owner if the focus recently changed from one +application to another. (JO) + +1/6/97 (bug fix) Under Windows, the console was appearing even for +non-interactive applications. This was a side effect of a general +problem with the wm state of windows that were being mapped for the +first time. (SS) + +1/6/97 (bug fix) Under Windows, the initialization code was not +looking in the right directory for the Tk libraries when the program +being run was not in the Tcl installation heirarchy. (SS) + +1/8/97 (bug fix) Under Windows, the windows were not being unmapped +properly, which led to strange packer behavior. (SS) + +1/8/97 (bug fix) The "winfo containing" command (and the Tk_CoordsToWindow +procedure) didn't work properly on Unix in the presence of embedding or +menubars. (JO) + +1/15/97 (bug fix) Invoking "destroy ." as the command from a menu would +cause Tk to crash because TkMainInfo was freed before menu released its +resources. This bug had already been fixed for scrollbars and buttons. (CS) + +1/15/97 (bug fix) Tk is now working under Win32s again, including Win32 +version 1.25. Fixed separate problems in fonts and dialogs. (CS) + +1/15/97 (feature change) Under Windows, font sizes are now specified in +points, not pixels. The mapping between pointsize and pixels depends on +Windows having accurate metrics for the monitor (plug&play helps). Font +metrics are still reported in pixels. (CS) + +1/21/97 (bug fix) Grid no longer reports rows or columns "out of range" +when requesting their constraints. (SAU) + +1/21/97 (bug fix) Fixed some window manager related bugs on the +Macintosh. Now better support global grabs. (RJ) + +1/21/97 (bug fix) For Windows: Fixed problems with canvas items that +used end caps. Fixed arc implementation to more closely approximate +X. Stippling now works properly on fat lines. (SS) + +1/21/97 (bug fix) Small interlaced GIF images were not properly +decoded. (SS) + +1/21/97 (bug fix) More changes to image code to try to handle 16-bit +displays properly under Windows. (SS) + +1/21/97 (bug fix) Numerous display bugs on Unix and Macintosh are now +fixed. Numerous binding problems for menubars under Unix are now +fixed. Deletion of menu separators under Windows is now fixed. (SRP) + +----------------- Released 8.0a2, 1/24/97 ----------------------- + +1/29/97 (feature change) The -transient field for menus is no longer +supported. There is now a -type field which is used to achieve the +same purpose that the -transient field accomplished. When a menu is +created, the -type field controls whether the menu is a normal +pull-down menu, a floating tearoff menu or a menubar. This option is +normally only used by the library code and internally by the menubar +code. (SRP) +*** POTENTIAL INCOMPATIBILITY *** + +2/5/97 (feature change) Changed the photo image mechanism to use +Tcl_Channels instead of FILE * as an argument to image matching +functions. The change will make it much easier to write cross +platform image types in Tk. Note: FILE * is no longer used anywhere +in Tk. (RJ) +*** POTENTIAL INCOMPATIBILITY *** + +2/7/97 (enhancement) Were not allowed to bind to virtual events inside of +canvas or text widget (e.g., "$canvas bind all <<foo>> {script}" or +"$text tag bind sel <<foo>> {script}"); it would return an error +disallowing that binding. Now _can_ bind to a virtual event, but that +binding inside of the canvas or text widget will only fire if the +underlying virtual event definition is of type key, button, motion, +enter, or leave; all other physical event types get filtered out by the +widget before the virtual event mapping is done. (CS) + +2/22/97 (bug fix) Under Unix, "wm geometry +-20+-30" didn't work. (JO) + +2/24/97 (bug fix) The photo image didn't always zero out enough of its +pixel and dither correction arrays. (JO) + +2/25/97 (bug fix) Fixed focus problem that could cause "BadMatch (invalid +parameter attributes)" in X_SetInputFocus requests on Unix. (JO) + +2/25/97 (bug fix and new feature) Added new "gray75" bitmap, fixed +"gray25" bitmap to really be 25% on (due to an ancient mistake, it +had been only 12% on). (JO) + +2/28/97 (bug fix) Windows: made embedding work again on Win32 platform. +Prevent iconification, deiconinification on embedded windows. (JL) + +3/4/97 (new feature) Added the ability to manipulate the Apple and +Help menus on the Macintosh; the system menu on Windows; and to have a +right justified Help menu on Unix. See the documentation for menu.n +for more details. (SRP) + +3/4/97 (bug fix) Prevented core dump at exit if a <Destroy> binding on "." +gets invoked from destroying a nested widget and the binding causes the +interpreter to be deleted. The core dump was being caused by the +interpreter not being Tcl_Preserve'd during the destroy of ".". (JL) + +3/4/97 (bug fix) Under Unix, when embedded Tk is running in a separate +process, correctly handle a race condition: ignore cross-over messages from +the X server for windows that Tk thinks it had already deleted, when the +containing process deletes its container window. Some other race conditions +still remain, e.g. with pixmaps, colormaps and images. (JL) + +3/10/97 (bug fix) Prevented core dump in generic console code due to +following a NULL pointer when the console interpreter was already deleted. +This may happen due to different orders of deletion possible at exit. (JL) + +3/10/97 (bug fix) Fixed bug on Mac and Windows that caused time to be +ignored when considering if a single click was actually a double +click. (RJ) + +3/11/97 (feature change) A major oversight has been that although it was +documented that the Tk programmer was asking for a font in points (1/72 of an +inch), under Unix and Mac Tk was actually asking for a font in pixels, while +only under Windows was it using points. This caused applications to appear +much larger when run under Windows. Now, on all platforms the (purportedly) +correct size in points is used when asking for fonts. However, for +compatibility with existing tk4.2 applications that depend on fonts being of +specified pixel size, XLFDs retain their incorrect behavior of getting a +font in pixels. (CCS) +*** POTENTIAL INCOMPATIBILITY *** + +3/13/97 (new feature) "tk scaling" command to setup the mapping between +pixels and points. This scaling factor is used by all widgets that accept +ruler distances, not just fonts. (CCS) + +3/24/97 (new feature) Added "-columnbreak" option to menu +entries. When this value is "1", the entry will appear at the top of a +new column in a non-menubar menu. Also added "-hideMargin". Together +with "-columnBreak", menus with palettes are now possible. (SRP) + +3/26/97 (new features and bug fix) Titles for tearoff menus were +broken on the Mac and Windows. Added the ability to set the title of a +menu when it gets torn off and override Tk's automatic generation of +the title. On the Macintosh, whenever a menu +label contains three dots in a row "...", the menu will instead +display the elipses character 'É'. (SRP) + +3/27/97 (bug fixes) When a menu had an error executing a postcommand, +the error information was getting lost. On Windows, a set of +menubuttons was not highligting properly when clicking between +windows. On Windows, post commands were getting executed twice for +popup menus. On Macintosh, fixed problem where menubars were not +always current. (SRP) + +4/11/97 (new feature) Menubuttons now have a direction flag which +controls where the menu popups up relative to the button. (SRP) + +4/24/97 (bug fix) Transient windows did not obey the resizable setting +under Windows. (SS) + +4/24/97 (bug fix) wm geometry did not correctly parse negative +coordinates. (SS) + +4/29/97 (bug fix) Changed the canvas polygon implementation to only +report the coordinates specified by the end user not the automatically +generated end point of a self closing polygon. (RJ) +*** POTENTIAL INCOMPATIBILITY *** + +4/23/97 (feature change) Loosened the rules on parsing font names so that +unix-centric fonts in scripts don't break when run on Windows or Mac. +(1) Previously, an XLFD had to specify font name, weight, slant, and size; +now, a minimal XLFD (such as "*-times-*") will be accepted, and all +unspecified attributes will be given default values. (2) Previously, in the +{name size style ...} format, only the style was optional; now both the size +and the style are optional; this solves the problem of old scripts that +contain specifications of the form "-font fixed" or "-font times". (CCS) + +5/7/97 (new feature) Menus now send a virtual event <<MenuSelect>> +when an item is highlighted in a menu. Applications can use this to +implement context-sensitive help. (SRP) + +5/14/97 (bug fix) Fixed a race condition in the focus code where focus +could be taken away from a window incorrectly. Scenario is that the main +window creates a toplevel and assigns focus to it. When the user moves the +mouse from the main window into the toplevel there was a race between +two different kinds of focus events. (BW) + +5/20/97 (bug fix) Fixed bug where the clipboard was not rendered before +the application exited. (SS) + +5/22/97 (feature change) When a Tk8.0 menu is configured, all menus +derived from it (menubars, tearoff) mirror the changes. This was not +true for the "-tearoff" flag. In Tk4.6, tearoff menus had the +"-tearoff" flag turned off. Now, the "-tearoff" flag is tracked just +as the other options are. Tearoff menus and menubars with the +"-tearoff" option set will not display the tearoff item. This means +that a given menu entry for a menu and a tearoff of that menu will +match now. (SRP) +*** POTENTIAL INCOMPATIBILITY *** + +----------------- Released 8.0b1, 5/27/97 ----------------------- + +5/30/97 (bug fix) Made the options to the grid command shortcut-able. +Ie. You can now use -stick, in addition to -sticky. (RJ) + +6/2/97 (bug fix) Fixed bug in startup code that caused a problem in +finding the library files when they are installed in a directory +containing a space in the name. (SS) + +6/2/97 (bug fix) Virtual events associated with <Enter>/<Leave> in text +widget tag caused panic. (CCS) + +6/6/97 (bug fix) On some systems, struct timeval.tv_sec is unsigned. (SS) + +6/6/97 (feature change) Changed -default option on buttons to take +three states: normal, active, disabled. This allows apps to have a +row of buttons where the default ring moves between buttons without +changing the geometry of the buttons. See the button.n manual page +for more details. (SS) +*** POTENTIAL INCOMPATIBILITY with Tk 8.0b1, but not with Tk 4.2 *** + +6/9/97 (bug fix) Canvas postscript printing now works for bitmaps +under Windows. (SS) + +6/10/97 (bug fix) Fixed bug in bindings for listboxes where state wasn't +being properly initialized on Shift-1 button presses. (JO) + +6/11/97 (bug fix) Text widget display code did not include internal +padding in the damage calculation for borders leading to unrefreshed +sections on Windows and Mac. (SS) + +6/12/97 (feature reversal) Changed default border widths under Unix +back to 2 again. This reverses the change made on 11/7/96. (JO) + +6/13/97 (bug fixes) In canvas text item: the insertion cursor wasn't shown +if insertion point was at end of text item, it was impossible to click to +position the insertion point after the last character, and @x,y indices were +computed incorrectly if -scrollregion had been specified and canvas was +scrolled. (CCS) + +6/13/97 (bug fix) Hitting up/down arrows in a text widget packed in a +toplevel window created with the "-screen" option would cause an error dialog +to pop up. (CCS) + +6/12/97 (bug fix) Fixed bug in canvas text items where multi-line +selections were not highlighted properly. This bug existed only in +earlier releases of Tk 8.0. (JO) + +6/16/97 (bug fix) In some obscure cases, canvas window items could +accidentally specified a 0x0 size for the window, which caused a +BadValue error under X. (JO) + +6/17/97 (bug fix) Tk buttons on the Macintosh will now correctly +draw under MacOS 8.0. (RJ) + +6/18/97 (feature change) Changed the way highlights are drawn in text +widgets so that the empty space to the left of a line is highlighted +whenever the leftmost character of the line is highlighted (the empty +space didn't used to be highlighted). This produces a neater left +edge when several lines are selected. (JO) + +6/18/97 (bug fix) Tk was using the wrong system colors to draw various +widgets under Windows. (SS) + +6/19/97 (bug fix) Under Windows, the "wm transient" and "wm overrideredirect" +subcommands can now be applied to a toplevel to change its window +style at any time during the life of the window. (SS) + +6/19/97 (feature change) All GIF and XBM images needed for the "TK" +file dialog box are included in-line in tkfbox.tcl. (IL) + +6/27/97 (bug fix) Revamped focus code to eliminate most XSetInputFocus +calls from the FilterEvent procedure. This moves the implementation back +towards the Tk 4.2 implementation, but adds embedding support. There is +still a known bug with twm's NoTitleFocus and embedded windows. However, +the races in a2 and the funny focus stealing in b1 are gone. (BW) + +6/25/97 (bug fix) Error message was not properly reported when using +button 'toggle'. (DL) + +6/25/97 (bug fix) Removed one source of memory corruption in tkGrid.c code +(fixes what was exercised by "grid col . 0 -w 1; grid col . 0 -w 25") (DL) + +----------------- Released 8.0b2, 6/30/97 ----------------------- + +7/1/97 (bug fix) Menu shortcut and tearoff reported problem fixed. (DL) + +7/1/97 (new feature) TK_BUILD_SHARED flag set in tkConfig.sh +when Tk has been built with --enable-shared. TK_SRC_DIR added. +A new tkLibObjs make target, echoing the list of the .o's needed +to build a tk library, is now provided. (DL) + +7/9/97 (bug fix) Fixed Tk_CreateFileHandler and Tk_DeleteFileHandler +macros to directly call the Tcl equivalents. (JL) + +7/10/97 (bug fix) On the Mac, if the binding for <<MenuSelect>> was +drawing, the drawing could bleed over into the menus. This is now +fixed. (SRP) + +7/10/97 (bug fixes) Removed duplicate code related to Tk_SafeInit, +made a single init script handling both cases. (DL) + +7/10/97 (feature change) On Unix, to be able to load Tk into a safe +interp you need to set the env(DISPLAY) var. Some API should be +added to allow master crontrol over Tk instantiation. (DL) + +7/11/97 (new feature) On the Mac, menus that are too big for the +screen will now scroll. This is part of the interface on the Mac, +impossible under Windows, and is not done for Unix. (SRP) + +7/21/97 (bug fix) After fixing the bug that in canvas text item the insertion +cursor wasn't shown if insertion point was at end of text item, introduced a +different bug in where clicking in entry widget with 0 characters would +crash or display garbage. (CCS) + +7/22/97 (bug fix) If there were a whole bunch of returns or tabs in a row in +a canvas text item, then the temporary buffer used when outputting +postscript could overflow and overwrite the stack. (CCS) + +7/23/97 (feature change) Reenabled "tkwait" in the Safe Tk base. (JL) + +7/24/97 (bug fix) Single init script for both Win and Unix. +new library/safetk.tcl using features from new tcl safe.tcl (DL) + +7/30/97 (feature change) As a result of native menus, you can no +longer drag through a frame of menubuttons on Macintosh and Windows +and have the menus pop down. You can still click on individual +menubuttons and their menus will pop down. Applications needing to +present a menubar should consider using the new "-menu" configuration +of the toplevel widget to set up menubar which behaves correctly on +Macintosh, Windows and X Windows. (SRP) + +7/31/97 (bug fix) Tk widget commands can now safely be hidden commands. +Previously destroying the widget would potentially leave dangling pointers +and destroy an exposed command instead of a hidden one if an exposed +command by that name existed. (JL) + +7/31/97 (bug fix) On Windows, popup menus were not tracking the right mouse +button correctly if it was used to invoke the menu. On Unix, tearoff +menus were stealing focus when the mouse moving over them even when +focus following was turned off. (SRP) + +8/4/97 (bug fix) Fixed problem under USENIX where raising a toplevel +window could cause an X error if the window had just been withdrawn. (JO) + +8/4/97 (feature change) tkerror and bgerror are not anymore hard links +maintained by the Tcl core. The implementation of bgerror provided by +Tk tries, for backward compatibility only, to to call "tkerror" and +if that fails, falls back to the usual dialog and stack trace option +posting. You can thus still use either "bgerror" or "tkerror" as your +application error handling proc, but using "bgerror" is strongly +recommended as support for "tkerror" will eventually vanish in upcoming +releases. (DL) +*** POTENTIAL INCOMPATIBILITY with scripts that were using + the actual hardlink implementation 'features' and with + scripts (if any) that would be calling the default "tkerror" to + simulate error messages (use "bgerror" instead) *** + +8/7/97 (feature change/addition) Removed the gif files used for the +Open dialog box on UNIX (they were previously made inline). Added a +new images directory that includes several images of the Tcl and Tcl +Powered logos. (RJ) + +8/7/97 (bug fix) Fixed focus to deal with embedding when there is +no window manager. (BW) + +8/8/97 (bug fix) Fixed bug in photo image code where photo images from +different interpreters could get confused if they had the same name. (JO) + +8/8/97 (new feature) Added new procedure Tk_GetImageMasterData for +mapping image names to master data. (JO) + +8/8/97 (feature change) Modified Tk_FindPhoto procedure to require +extra "interp" argument (needed for bug fix above). (JO) +*** POTENTIAL INCOMPATIBILITY *** + +8/8/97 (bug fix) Fixed problems under Windows renaming toplevels with +menubars. Fixed problems on all platforms renaming menu widgets and +using new menus of the same name as an old one as cascades. Fixed a +cosmetic problem with tearoff menus. (SRP) + +8/13/97 (bug fixes) Fixed "-from" option for the "image create" and +"imageName read" commands for GIF images, which didn't used to work +correctly. Also made transparency work correctly for GIF images +without the TRANSPARENT_GIF_COLOR hack; TRANSPARENT_GIF_COLOR is +now ignored. These fixes were provided by Jan Nijtmans. (JO) + +8/13/97 (new feature) added safe::loadTk command to load Tk in a +safe slave interpreter. See the loadTk.n manual page for more +details. (DL) + +----------------- Released 8.0, 8/18/97 ----------------------- + +8/22/97 - (bug fix) Fixed syntax error in tk_popup; option menus now +popup over their selected items like they did in tk4.2. Fixed problem +where cascades sometimes did not work on X. On X, menubars with +checkbuttons and radiobuttons in them would infinite loop when +mappped. (SRP) + +8/27/97 (new feature) Added support for new X11R6 colors under Windows +and Mac platforms. (SS) + +8/29/97 (bug fix) Wish crashed if stdin was closed. (SS) + +9/10/97 (bug fix) "font actual {helvetica 10} -displayof ." wasn't taking +into account the "-displayof" option. This problem also existed for the +"font metrics" and "font measure" commands. (CCS) + +9/16/97 (new feature) Added "resource delete" and "resource files" +command to the Mac. Also fixed "resource write" when the resource +was specified by id and already existed. (JI) + +9/16/97 (bug fix) Added null bindings to <Command-KeyPress> for the +text and entry widget on the Macintosh. This prevents unbound command +key sequences from having the character echoed to the widget. Also +fixed Cut & Copy bindings. (JI) (RJ) + +9/18/97 (bug fix) Revamped Macintosh focus code. Cut, Copy & Paste +virtual events now go to the correct (focus) window. (RJ) + +9/19/97 (bug fix) Made Macintosh tearoff menus non-resizable. (RJ) + +10/9/97 (bug fix) Image code could cause crashes during "exit" under +some conditions (such as an image named "place"). (JO) + +10/9/97 (bug fix) Fixed bug that sometimes prevented listboxes from +scrolling far enough horizontally to see the rightmost character. (JO) + +10/9/97 (bug fix) Default font for new canvas text items was hardcoded to +"Helvetica 12" instead of using DEF_CANVTEXT_FONT defined in +tk{platform}Default.h like all the other widget settings. (CCS) + +10/10/97 (bug fix) In canvas text items, if the text ended with a \n, it +was not counted in the bbox height, as it did in tk4.2. This caused +"hello\n" to be the same height as "hello" and you couldn't see the +cursor positioned on the next line. (CCS) + +10/10/97 (bug fix) The grid geometry manager didn't always properly +forget about windows after a "grid forget" or "grid remove" command: +the windows could reappear on the screen later. (JO) + +10/13/97 (bug fix) Selection could not be restored to a text widget +after "selection clear" on Windows. (SS) + +10/14/97 (bug fix) If a canvas had contained windows that were off-screen, +the windows could sometimes reappear (in the wrong place) if the canvas was +enlarged. (JO) + +10/20/97 (bug fix) Omitting the arguments to the text widget "mark +gravity" option caused a crash. (SS) + +10/21/97 (bug fix) Tk did not reset the result after native dialog +modal loops on Window so background events could perturb the dialog +result. (SS) + +10/23/97 (bug fix) Memory leak in unix's TkpGetFontFamilies. Thanks +to James Bonfield for the fix. (DL) + +10/27/97 (bug fix) Fixed event reporting for the Mac during a grab +when the pointer was out of the toplevel window. (RJ) + +10/28/97 (bug fix) Under Unix, override-redirect was getting set +incorrectly for menus, so that "wm overrideredirect" returned 0. (JO) + +10/28/97 (bug fix) Under Unix, focus code could sometimes cause the +display to deadlock (it wasn't flushing the output buffer after issuing +an ungrab command). (JO) + +10/28/97 (bug fix) If a PPM image file wasn't complete (e.g. it +consisted of nothing but space characters) Tk entered an infinite loop +reading the header. (JO) + +10/28/97 (bug fixes) On the Mac, menubars assigned to toplevels would +disappear after a menu item was invoked from them. On Windows, +clicking a system menu with added items and then again with a +different set of added items would crash. On all platforms, a command +menu entry that caused the entry to be deleted, another one created in +its place, and the replacement deleted would cause a panic. On Unix, +<<MenuSelect>> event bindings were firing every time the mouse moved, +instead of everytime the active menu item changed. (SRP) + +10/27/97 (bug fix) If a particular race condition occurred under Windows, +Tk would crash complaining about trying to free a color that wasn't +allocated. (SS) + +10/28/97 (bug fix) Under Windows, button grabs did not report motion +events that occurred outside of Tk windows. (SS) + +10/28/97 (bug fix) Fixed incorrect display of transparent images on +the Macintosh. (JI) + +10/29/97 (bug fix) Reworked the handling of out-of-range indices in +the widget command for listboxes: there were all sorts of quirks +before (e.g., ".l delete -1" actually deleted the first element +of the listbox). (JO) + +10/29/97 (bug fix) Fixed crash on the Macintosh that could occur if a +window is moved before it is mapped where the X window was created but +the Macintosh port was not. (RJ) + +10/29/97 (bug fix) Fixed several errors in how wm state was maintained +on the Macintosh. Tk now also will iconify a toplevel window on the +Mac if the new Appearance Manager is present. (RJ) + +10/28/97 (bug fixes) In canvas' postscript command: User name +information was leaked in safe interpreters on Unix (security fix). +Errors while reading prolog.ps were not propagated and the error +message was mixed with partial data. Note: postscript output does +not work in safe interpreters on unix and windows. (DL) + +10/28/97 (bug fix) Safe Tk interps on unix were leaking env(DISPLAY). (DL) + +10/31/97 (bug fix) Fixed problems related to the input focus when one +application had windows open simultaneously on several displays. (JO) + +10/31/97 (bug fix) Fixed several problems with traversal of menus via +the keyboard under Unix. (SRP) + +11/4/97 (bug fix) Fixed various word-size related problems for 64-bit +architectures. (SS) + +11/5/97 (bug fix) Embedding on Windows was using freed data (crashing +in safe.test with TCL_MEM_DEBUG). NB: Embedding is still not fully +implemented on Windows ! (It works mostly when Tk is embeded into it's +own Tk frame (safe::loadTk case), but not well with respect to resizing +with a toplevel container or with an external process). (DL) + +----------------- Released 8.0p1, 11/7/97 ----------------------- + +11/20/97 (bug fix) Fixed bug on the Mac where the "package require" +command caused menus to stop working. (JI) + +11/20/97 (bug fix) Fixed bug in rendering transparent gifs on Text +widgets. (JI) + +11/20/97 (enhancement) Made the changes required to work with the new +Apple Universal Headers V. 3.0 so we can compile with CW Pro 2.0 (JI) + +----------------- Released 8.0p2, 11/25/97 ----------------------- diff --git a/compat/limits.h b/compat/limits.h new file mode 100644 index 0000000..ec7a909 --- /dev/null +++ b/compat/limits.h @@ -0,0 +1,24 @@ +/* + * limits.h -- + * + * This is a dummy header file to #include in Tcl when there + * is no limits.h in /usr/include. There are only a few + * definitions here; also see tclPort.h, which already + * #defines some of the things here if they're not arleady + * defined. + * + * Copyright (c) 1991 The Regents of the University of California. + * Copyright (c) 1994 Sun Microsystems, Inc. + * + * See the file "license.terms" for information on usage and redistribution + * of this file, and for a DISCLAIMER OF ALL WARRANTIES. + * + * SCCS: @(#) limits.h 1.8 96/07/08 18:00:13 + */ + +#define LONG_MIN 0x80000000 +#define LONG_MAX 0x7fffffff +#define INT_MIN 0x80000000 +#define INT_MAX 0x7fffffff +#define SHRT_MIN 0x8000 +#define SHRT_MAX 0x7fff diff --git a/compat/stdlib.h b/compat/stdlib.h new file mode 100644 index 0000000..059ea29 --- /dev/null +++ b/compat/stdlib.h @@ -0,0 +1,45 @@ +/* + * stdlib.h -- + * + * Declares facilities exported by the "stdlib" portion of + * the C library. This file isn't complete in the ANSI-C + * sense; it only declares things that are needed by Tcl. + * This file is needed even on many systems with their own + * stdlib.h (e.g. SunOS) because not all stdlib.h files + * declare all the procedures needed here (such as strtod). + * + * Copyright (c) 1991 The Regents of the University of California. + * Copyright (c) 1994 Sun Microsystems, Inc. + * + * See the file "license.terms" for information on usage and redistribution + * of this file, and for a DISCLAIMER OF ALL WARRANTIES. + * + * SCCS: @(#) stdlib.h 1.10 96/02/15 14:43:54 + */ + +#ifndef _STDLIB +#define _STDLIB + +#include <tcl.h> + +extern void abort _ANSI_ARGS_((void)); +extern double atof _ANSI_ARGS_((CONST char *string)); +extern int atoi _ANSI_ARGS_((CONST char *string)); +extern long atol _ANSI_ARGS_((CONST char *string)); +extern char * calloc _ANSI_ARGS_((unsigned int numElements, + unsigned int size)); +extern void exit _ANSI_ARGS_((int status)); +extern int free _ANSI_ARGS_((char *blockPtr)); +extern char * getenv _ANSI_ARGS_((CONST char *name)); +extern char * malloc _ANSI_ARGS_((unsigned int numBytes)); +extern void qsort _ANSI_ARGS_((VOID *base, int n, int size, + int (*compar)(CONST VOID *element1, CONST VOID + *element2))); +extern char * realloc _ANSI_ARGS_((char *ptr, unsigned int numBytes)); +extern double strtod _ANSI_ARGS_((CONST char *string, char **endPtr)); +extern long strtol _ANSI_ARGS_((CONST char *string, char **endPtr, + int base)); +extern unsigned long strtoul _ANSI_ARGS_((CONST char *string, + char **endPtr, int base)); + +#endif /* _STDLIB */ diff --git a/compat/unistd.h b/compat/unistd.h new file mode 100644 index 0000000..3af430c --- /dev/null +++ b/compat/unistd.h @@ -0,0 +1,84 @@ +/* + * unistd.h -- + * + * Macros, CONSTants and prototypes for Posix conformance. + * + * Copyright 1989 Regents of the University of California + * Permission to use, copy, modify, and distribute this + * software and its documentation for any purpose and without + * fee is hereby granted, provided that the above copyright + * notice appear in all copies. The University of California + * makes no representations about the suitability of this + * software for any purpose. It is provided "as is" without + * express or implied warranty. + * + * SCCS: @(#) unistd.h 1.7 96/02/15 14:43:57 + */ + +#ifndef _UNISTD +#define _UNISTD + +#include <sys/types.h> +#ifndef _TCL +# include "tcl.h" +#endif + +#ifndef NULL +#define NULL 0 +#endif + +/* + * Strict POSIX stuff goes here. Extensions go down below, in the + * ifndef _POSIX_SOURCE section. + */ + +extern void _exit _ANSI_ARGS_((int status)); +extern int access _ANSI_ARGS_((CONST char *path, int mode)); +extern int chdir _ANSI_ARGS_((CONST char *path)); +extern int chown _ANSI_ARGS_((CONST char *path, uid_t owner, gid_t group)); +extern int close _ANSI_ARGS_((int fd)); +extern int dup _ANSI_ARGS_((int oldfd)); +extern int dup2 _ANSI_ARGS_((int oldfd, int newfd)); +extern int execl _ANSI_ARGS_((CONST char *path, ...)); +extern int execle _ANSI_ARGS_((CONST char *path, ...)); +extern int execlp _ANSI_ARGS_((CONST char *file, ...)); +extern int execv _ANSI_ARGS_((CONST char *path, char **argv)); +extern int execve _ANSI_ARGS_((CONST char *path, char **argv, char **envp)); +extern int execvp _ANSI_ARGS_((CONST char *file, char **argv)); +extern pid_t fork _ANSI_ARGS_((void)); +extern char *getcwd _ANSI_ARGS_((char *buf, size_t size)); +extern gid_t getegid _ANSI_ARGS_((void)); +extern uid_t geteuid _ANSI_ARGS_((void)); +extern gid_t getgid _ANSI_ARGS_((void)); +extern int getgroups _ANSI_ARGS_((int bufSize, int *buffer)); +extern pid_t getpid _ANSI_ARGS_((void)); +extern uid_t getuid _ANSI_ARGS_((void)); +extern int isatty _ANSI_ARGS_((int fd)); +extern long lseek _ANSI_ARGS_((int fd, long offset, int whence)); +extern int pipe _ANSI_ARGS_((int *fildes)); +extern int read _ANSI_ARGS_((int fd, char *buf, size_t size)); +extern int setgid _ANSI_ARGS_((gid_t group)); +extern int setuid _ANSI_ARGS_((uid_t user)); +extern unsigned sleep _ANSI_ARGS_ ((unsigned seconds)); +extern char *ttyname _ANSI_ARGS_((int fd)); +extern int unlink _ANSI_ARGS_((CONST char *path)); +extern int write _ANSI_ARGS_((int fd, CONST char *buf, size_t size)); + +#ifndef _POSIX_SOURCE +extern char *crypt _ANSI_ARGS_((CONST char *, CONST char *)); +extern int fchown _ANSI_ARGS_((int fd, uid_t owner, gid_t group)); +extern int flock _ANSI_ARGS_((int fd, int operation)); +extern int ftruncate _ANSI_ARGS_((int fd, unsigned long length)); +extern int ioctl _ANSI_ARGS_((int fd, int request, ...)); +extern int readlink _ANSI_ARGS_((CONST char *path, char *buf, int bufsize)); +extern int setegid _ANSI_ARGS_((gid_t group)); +extern int seteuid _ANSI_ARGS_((uid_t user)); +extern int setreuid _ANSI_ARGS_((int ruid, int euid)); +extern int symlink _ANSI_ARGS_((CONST char *, CONST char *)); +extern int ttyslot _ANSI_ARGS_((void)); +extern int truncate _ANSI_ARGS_((CONST char *path, unsigned long length)); +extern int vfork _ANSI_ARGS_((void)); +#endif /* _POSIX_SOURCE */ + +#endif /* _UNISTD */ + diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 new file mode 100644 index 0000000..921a948 --- /dev/null +++ b/doc/3DBorder.3 @@ -0,0 +1,262 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) 3DBorder.3 1.23 96/11/17 15:03:05 +'\" +.so man.macros +.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorder \- draw borders with three-dimensional appearance +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_3DBorder +\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR +.sp +void +\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +.sp +void +\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +.sp +void +\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +.sp +void +\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +.sp +void +\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR +.sp +void +\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR +.sp +void +\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR +.sp +char * +\fBTk_NameOf3DBorder(\fIborder\fB)\fR +.sp +XColor * +\fBTk_3DBorderColor(\fIborder\fB)\fR +.sp +GC * +\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR +.sp +\fBTk_Free3DBorder(\fIborder\fB)\fR +.SH ARGUMENTS +.AS "Tk_3DBorder" borderWidth +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window (for all procedures except \fBTk_Get3DBorder\fR, +must be the window for which the border was allocated). +.AP Tk_Uid colorName in +Textual description of color corresponding to background (flat areas). +Illuminated edges will be brighter than this and shadowed edges will +be darker than this. +.AP Drawable drawable in +X token for window or pixmap; indicates where graphics are to be drawn. +Must either be the X window for \fItkwin\fR or a pixmap with the +same screen and depth as \fItkwin\fR. +.AP Tk_3DBorder border in +Token for border previously allocated in call to \fBTk_Get3DBorder\fR. +.AP int x in +X-coordinate of upper-left corner of rectangle describing border +or bevel, in pixels. +.AP int y in +Y-coordinate of upper-left corner of rectangle describing border or +bevel, in pixels. +.AP int width in +Width of rectangle describing border or bevel, in pixels. +.AP int height in +Height of rectangle describing border or bevel, in pixels. +.AP int borderWidth in +Width of border in pixels. Positive means border is inside rectangle +given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means +border is outside rectangle. +.AP int relief in +Indicates 3-D position of interior of object relative to exterior; +should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, +TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT +for \fBTk_Fill3DRectangle\fR). +.AP XPoint *pointPtr in +Pointer to array of points describing the set of vertices in a polygon. +The polygon need not be closed (it will be closed automatically if it +isn't). +.AP int numPoints in +Number of points at \fI*pointPtr\fR. +.AP int polyBorderWidth in +Width of border in pixels. If positive, border is drawn to left of +trajectory given by \fIpointPtr\fR; if negative, border is drawn to +right of trajectory. If \fIleftRelief\fR is TK_RELIEF_GROOVE or +TK_RELIEF_RIDGE then the border is centered on the trajectory. +.AP int leftRelief in +Height of left side of polygon's path relative to right. TK_RELIEF_RAISED +means left side should appear higher and TK_RELIEF_SUNKEN means right side +should appear higher; +TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. +For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to +indicate no difference in height. +.AP int leftBevel in +Non-zero means this bevel forms the left side of the object; zero means +it forms the right side. +.AP int leftIn in +Non-zero means that the left edge of the horizontal bevel angles in, +so that the bottom of the edge is farther to the right than +the top. +Zero means the edge angles out, so that the bottom is farther to the +left than the top. +.AP int rightIn in +Non-zero means that the right edge of the horizontal bevel angles in, +so that the bottom of the edge is farther to the left than the top. +Zero means the edge angles out, so that the bottom is farther to the +right than the top. +.AP int topBevel in +Non-zero means this bevel forms the top side of the object; zero means +it forms the bottom side. +.AP int which in +Specifies which of the border's graphics contexts is desired. +Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. +.BE + +.SH DESCRIPTION +.PP +These procedures provide facilities for drawing window borders in a +way that produces a three-dimensional appearance. \fBTk_Get3DBorder\fR +allocates colors and Pixmaps needed to draw a border in the window +given by the \fItkwin\fR argument. The \fIcolorName\fR +argument indicates what colors should be used in the border. +\fIColorName\fR may be any value acceptable to \fBTk_GetColor\fR. +The color indicated by \fIcolorName\fR will not actually be used in +the border; it indicates the background color for the window +(i.e. a color for flat surfaces). +The illuminated portions of the border will appear brighter than indicated +by \fIcolorName\fR, and the shadowed portions of the border will appear +darker than \fIcolorName\fR. +.PP +\fBTk_Get3DBorder\fR returns a token that may be used in later calls +to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information +for the border (e.g. \fIcolorName\fR isn't a legal color specifier), +then NULL is returned and an error message is left in \fIinterp->result\fR. +.PP +Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be +invoked to draw the border. +The \fItkwin\fR argument specifies the +window for which the border was allocated, and \fIdrawable\fR +specifies a window or pixmap in which the border is to be drawn. +\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it +must refer to a compatible +pixmap or window: one associated with the same screen and with the +same depth as \fItkwin\fR. +The \fIx\fR, \fIy\fR, \fIwidth\fR, and +\fIheight\fR arguments define the bounding box of the border region +within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and +\fIwidth\fR and \fIheight\fR are the dimensions of the window), and +\fIborderWidth\fR specifies the number of pixels actually +occupied by the border. The \fIrelief\fR argument indicates +which of several three-dimensional effects is desired: +TK_RELIEF_RAISED means that the interior of the rectangle should appear raised +relative to the exterior of the rectangle, and +TK_RELIEF_SUNKEN means that the interior should appear depressed. +TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be +a groove or ridge around the exterior of the rectangle. +.PP +\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except +that it first fills the rectangular area with the background color +(one corresponding +to the \fIcolorName\fR used to create \fIborder\fR). Then it calls +\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of +the rectangular area. The argument \fIrelief\fR indicates the desired +effect (TK_RELIEF_FLAT means no border should be drawn; all that +happens is to fill the rectangle with the background color). +.PP +The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex +shapes with a three-dimensional appearance. The \fIpointPtr\fR and +\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR +indicates how wide the border should be (and on which side of the +trajectory to draw it), and \fIleftRelief\fR indicates which side +of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR +draws a border around the given trajectory using the colors from +\fIborder\fR to produce a three-dimensional appearance. If the trajectory is +non-self-intersecting, the appearance will be a raised or sunken +polygon shape. The trajectory may be self-intersecting, although +it's not clear how useful this is. +.PP +\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what +\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills +the polygonal area with the background color from \fIborder\fR, +then calls \fBTk_Draw3DPolygon\fR to draw a border around the +area (unless \fIleftRelief\fR is TK_RELIEF_FLAT; in this case no +border is drawn). +.PP +The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR +provide lower-level drawing primitives that are used by +procedures such as \fBTk_Draw3DRectangle\fR. +These procedures are also useful in their own right for drawing +rectilinear border shapes. +\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the +left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR +draws a horizontal beveled edge, such as the top or bottom of a +rectangle. +Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +arguments that describe the rectangular area of the beveled edge +(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). +The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the +position of the border relative to the ``inside'' of the object, and +\fIrelief\fR indicates the relief of the inside of the object relative +to the outside. +\fBTk_3DVerticalBevel\fR just draws a rectangular region. +\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate +mitered corners; it should be called after \fBTk_3DVerticalBevel\fR +(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in +the corner). +The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR +describe the mitering at the corners; a value of 1 means that the bottom +edge of the trapezoid will be shorter than the top, 0 means it will +be longer. +For example, to draw a rectangular border the top bevel should be +drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the +bottom bevel should be drawn with 0 for both arguments. +.PP +The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background +pixel and/or pixmap of \fItkwin\fR to produce a result compatible +with \fIborder\fR. For color displays, the resulting background will +just be the color given by the \fIcolorName\fR argument passed to +\fBTk_Get3DBorder\fR when \fIborder\fR was created; for monochrome +displays, the resulting background +will be a light stipple pattern, in order to distinguish the background from +the illuminated portion of the border. +.PP +Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR +will return the \fIcolorName\fR string that was passed to +\fBTk_Get3DBorder\fR to create the border. +.PP +The procedure \fBTk_3DBorderColor\fR returns the XColor structure +that will be used for flat surfaces drawn for its \fIborder\fR +argument by procedures like \fBTk_Fill3DRectangle\fR. +The return value corresponds to the \fIcolorName\fR passed to +\fBTk_Get3DBorder\fR. +The XColor, and its associated pixel value, will remain allocated +as long as \fIborder\fR exists. +.PP +The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts +that are used to draw the border. +The argument \fIwhich\fR selects which one of the three possible GC's: +TK_3D_FLAT_GC returns the context used for flat surfaces, +TK_3D_LIGHT_GC returns the context for light shadows, +and TK_3D_DARK_GC returns the context for dark shadows. +.PP +When a border is no longer needed, \fBTk_Free3DBorder\fR should +be called to release the resources associated with the border. +There should be exactly one call to \fBTk_Free3DBorder\fR for +each call to \fBTk_Get3DBorder\fR. + +.SH KEYWORDS +3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect diff --git a/doc/BindTable.3 b/doc/BindTable.3 new file mode 100644 index 0000000..bbcb64d --- /dev/null +++ b/doc/BindTable.3 @@ -0,0 +1,157 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) BindTable.3 1.5 96/03/26 18:03:09 +'\" +.so man.macros +.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_BindingTable +\fBTk_CreateBindingTable(\fIinterp\fB)\fR +.sp +\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR +.sp +unsigned long +\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR +.sp +int +\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR +.sp +char * +\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR +.sp +\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR +.sp +\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR +.sp +\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR +.SH ARGUMENTS +.AS Tk_BindingTable bindingTable +.AP Tcl_Interp *interp in +Interpreter to use when invoking bindings in binding table. Also +used for returning results and errors from binding procedures. +.AP Tk_BindingTable bindingTable in +Token for binding table; must have been returned by some previous +call to \fBTk_CreateBindingTable\fR. +.AP ClientData object in +Identifies object with which binding is associated. +.AP char *eventString in +String describing event sequence. +.AP char *script in +Tcl script to invoke when binding triggers. +.AP int append in +Non-zero means append \fIscript\fR to existing script for binding, +if any; zero means replace existing script with new one. +.AP XEvent *eventPtr in +X event to match against bindings in \fIbindingTable\fR. +.AP Tk_Window tkwin in +Identifier for any window on the display where the event occurred. +Used to find display-related information such as key maps. +.AP int numObjects in +Number of object identifiers pointed to by \fIobjectPtr\fR. +.AP ClientData *objectPtr in +Points to an array of object identifiers: bindings will be considered +for each of these objects in order from first to last. +.BE + +.SH DESCRIPTION +.PP +These procedures provide a general-purpose mechanism for creating +and invoking bindings. +Bindings are organized in terms of \fIbinding tables\fR. +A binding table consists of a collection of bindings plus a history +of recent events. +Within a binding table, bindings are associated with \fIobjects\fR. +The meaning of an object is defined by clients of the binding package. +For example, Tk keeps uses one binding table to hold all of the bindings +created by the \fBbind\fR command. +For this table, objects are pointers to strings such as window names, class +names, or other binding tags such as \fBall\fR. +Tk also keeps a separate binding table for each canvas widget, which manages +bindings created by the canvas's \fBbind\fR widget command; within +this table, an object is either a pointer to the internal structure for a +canvas item or a Tk_Uid identifying a tag. +.PP +The procedure \fBTk_CreateBindingTable\fR creates a new binding +table and associates \fIinterp\fR with it (when bindings in the +table are invoked, the scripts will be evaluated in \fIinterp\fR). +\fBTk_CreateBindingTable\fR returns a token for the table, which +must be used in calls to other procedures such as \fBTk_CreateBinding\fR +or \fBTk_BindEvent\fR. +.PP +\fBTk_DeleteBindingTable\fR frees all of the state associated +with a binding table. +Once it returns the caller should not use the \fIbindingTable\fR +token again. +.PP +\fBTk_CreateBinding\fR adds a new binding to an existing table. +The \fIobject\fR argument identifies the object with which the +binding is to be associated, and it may be any one-word value. +Typically it is a pointer to a string or data structure. +The \fIeventString\fR argument identifies the event or sequence +of events for the binding; see the documentation for the +\fBbind\fR command for a description of its format. +\fIscript\fR is the Tcl script to be evaluated when the binding +triggers. +\fIappend\fR indicates what to do if there already +exists a binding for \fIobject\fR and \fIeventString\fR: if \fIappend\fR +is zero then \fIscript\fR replaces the old script; if \fIappend\fR +is non-zero then the new script is appended to the old one. +\fBTk_CreateBinding\fR returns an X event mask for all the events +associated with the bindings. +This information may be useful to invoke \fBXSelectInput\fR to +select relevant events, or to disallow the use of certain events +in bindings. +If an error occurred while creating the binding (e.g., \fIeventString\fR +refers to a non-existent event), then 0 is returned and an error +message is left in \fIinterp->result\fR. +.PP +\fBTk_DeleteBinding\fR removes from \fIbindingTable\fR the +binding given by \fIobject\fR and \fIeventString\fR, if +such a binding exists. +\fBTk_DeleteBinding\fR always returns TCL_OK. +In some cases it may reset \fIinterp->result\fR to the default +empty value. +.PP +\fBTk_GetBinding\fR returns a pointer to the script associated +with \fIeventString\fR and \fIobject\fR in \fIbindingTable\fR. +If no such binding exists then NULL is returned and an error +message is left in \fIinterp->result\fR. +.PP +\fBTk_GetAllBindings\fR returns in \fIinterp->result\fR a list +of all the event strings for which there are bindings in +\fIbindingTable\fR associated with \fIobject\fR. +If there are no bindings for \fIobject\fR then an empty +string is returned in \fIinterp->result\fR. +.PP +\fBTk_DeleteAllBindings\fR deletes all of the bindings in +\fIbindingTable\fR that are associated with \fIobject\fR. +.PP +\fBTk_BindEvent\fR is called to process an event. +It makes a copy of the event in an internal history list associated +with the binding table, then it checks for bindings that match +the event. +\fBTk_BindEvent\fR processes each of the objects pointed to +by \fIobjectPtr\fR in turn. +For each object, it finds all the bindings that match the current +event history, selects the most specific binding using the priority +mechanism described in the documentation for \fBbind\fR, +and invokes the script for that binding. +If there are no matching bindings for a particular object, then +the object is skipped. +\fBTk_BindEvent\fR continues through all of the objects, handling +exceptions such as errors, \fBbreak\fR, and \fBcontinue\fR as +described in the documentation for \fBbind\fR. + +.SH KEYWORDS +binding, event, object, script diff --git a/doc/CanvPsY.3 b/doc/CanvPsY.3 new file mode 100644 index 0000000..017b762 --- /dev/null +++ b/doc/CanvPsY.3 @@ -0,0 +1,122 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CanvPsY.3 1.6 96/03/26 18:03:26 +'\" +.so man.macros +.TH Tk_CanvasPsY 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +double +\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR) +.sp +int +\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR) +.sp +int +\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR) +.sp +int +\fBTk_CanvasPsFont\fR(\fIinterp, canvas, fontStructPtr\fR) +.sp +\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR) +.sp +int +\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR) +.SH ARGUMENTS +.AS "unsigned int" *fontStructPtr +.AP Tk_Canvas canvas in +A token that identifies a canvas widget for which Postscript is +being generated. +.AP double canvasY in +Y-coordinate in the space of the canvas. +.AP Tcl_Interp *interp in/out +A Tcl interpreter; Postscript is appended to its result, or the +result may be replaced with an error message. +.AP Pixmap bitmap in +Bitmap to use for generating Postscript. +.AP int x in +X-coordinate within \fIbitmap\fR of left edge of region to output. +.AP int y in +Y-coordinate within \fIbitmap\fR of top edge of region to output. +.AP "int" width in +Width of region of bitmap to output, in pixels. +.AP "int" height in +Height of region of bitmap to output, in pixels. +.AP XColor *colorPtr in +Information about color value to set in Postscript. +.AP XFontStruct *fontStructPtr in +Font for which Postscript is to be generated. +.AP double *coordPtr in +Pointer to an array of coordinates for one or more +points specified in canvas coordinates. +The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3, +and so on. +.AP int numPoints in +Number of points at \fIcoordPtr\fR. +.BE + +.SH DESCRIPTION +.PP +These procedures are called by canvas type managers to carry out +common functions related to generating Postscript. +Most of the procedures take a \fIcanvas\fR argument, which +refers to a canvas widget for which Postscript is being +generated. +.PP +\fBTk_CanvasY\fR takes as argument a y-coordinate in the space of +a canvas and returns the value that should be used for that point +in the Postscript currently being generated for \fIcanvas\fR. +Y coordinates require transformation because Postscript uses an +origin at the lower-left corner whereas X uses an origin at the +upper-left corner. +Canvas x coordinates can be used directly in Postscript without +transformation. +.PP +\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region +of a bitmap. +The Postscript is generated in proper image data format for Postscript, +i.e., as data between angle brackets, one bit per pixel. +The Postscript is appended to \fIinterp->result\fR and TCL_OK is returned +unless an error occurs, in which case TCL_ERROR is returned and +\fIinterp->result\fR is overwritten with an error message. +.PP +\fBTk_CanvasPsColor\fR generates Postscript to set the current color +to correspond to its \fIcolorPtr\fR argument, taking into account any +color map specified in the \fBpostscript\fR command. +It appends the Postscript to \fIinterp->result\fR and returns +TCL_OK unless an error occurs, in which case TCL_ERROR is returned and +\fIinterp->result\fR is overwritten with an error message. +.PP +\fBTk_CanvasPsFont\fR generates Postscript that sets the current font +to match \fIfontStructPtr\fR as closely as possible. +\fBTk_CanvasPsFont\fR takes into account any font map specified +in the \fBpostscript\fR command, and it does +the best it can at mapping X fonts to Postscript fonts. +It appends the Postscript to \fIinterp->result\fR and returns TCL_OK +unless an error occurs, in which case TCL_ERROR is returned and +\fIinterp->result\fR is overwritten with an error message. +.PP +\fBTk_CanvasPsPath\fR generates Postscript to set the current path +to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR. +It appends the resulting Postscript to \fIinterp->result\fR. +.PP +\fBTk_CanvasPsStipple\fR generates Postscript that will fill the +current path in stippled fashion. +It uses \fIbitmap\fR as the stipple pattern and the current Postscript +color; ones in the stipple bitmap are drawn in the current color, and +zeroes are not drawn at all. +The Postscript is appended to \fIinterp->result\fR and TCL_OK is +returned, unless an error occurs, in which case TCL_ERROR is returned and +\fIinterp->result\fR is overwritten with an error message. + +.SH KEYWORDS +bitmap, canvas, color, font, path, Postscript, stipple diff --git a/doc/CanvTkwin.3 b/doc/CanvTkwin.3 new file mode 100644 index 0000000..b421b5e --- /dev/null +++ b/doc/CanvTkwin.3 @@ -0,0 +1,161 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CanvTkwin.3 1.8 96/08/27 13:21:54 +'\" +.so man.macros +.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CanvasTkwin\fR(\fIcanvas\fR) +.sp +int +\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR) +.sp +\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR) +.sp +\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR) +.sp +\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) +.sp +\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) +.sp +Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; +.sp +Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; +.SH ARGUMENTS +.AS Tk_ItemType *drawableXPtr +.AP Tk_Canvas canvas in +A token that identifies a canvas widget. +.AP Tcl_Interp *interp in/out +Interpreter to use for error reporting. +.AP char *string in +Textual description of a canvas coordinate. +.AP double *doublePtr out +Points to place to store a converted coordinate. +.AP double x in +An x coordinate in the space of the canvas. +.AP double y in +A y coordinate in the space of the canvas. +.AP short *drawableXPtr out +Pointer to a location in which to store an x coordinate in the space +of the drawable currently being used to redisplay the canvas. +.AP short *drawableYPtr out +Pointer to a location in which to store a y coordinate in the space +of the drawable currently being used to redisplay the canvas. +.AP GC gc out +Graphics context to modify. +.AP short *screenXPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIx\fR. +.AP short *screenYPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIy\fR. +.AP int x1 in +Left edge of the region that needs redisplay. Only pixels at or to +the right of this coordinate need to be redisplayed. +.AP int y1 in +Top edge of the region that needs redisplay. Only pixels at or below +this coordinate need to be redisplayed. +.AP int x2 in +Right edge of the region that needs redisplay. Only pixels to +the left of this coordinate need to be redisplayed. +.AP int y2 in +Bottom edge of the region that needs redisplay. Only pixels above +this coordinate need to be redisplayed. +.BE + +.SH DESCRIPTION +.PP +These procedures are called by canvas type managers to perform various +utility functions. +.PP +\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular +canvas. +.PP +\fBTk_CanvasGetCoord\fR translates a string specification of a +coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision +canvas coordinate. +If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR +stores the corresponding canvas coordinate at *\fIdoublePtr\fR +and returns TCL_OK. +Otherwise it stores an error message in \fIinterp->result\fR and +returns TCL_ERROR. +.PP +\fBTk_CanvasDrawableCoords\fR is called by type managers during +redisplay to compute where to draw things. +Given \fIx\fR and \fIy\fR coordinates in the space of the +canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding +pixel in the drawable that is currently being used for redisplay; +it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR. +This procedure should not be invoked except during redisplay. +.PP +\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay. +It sets the stipple origin in \fIgc\fR so that stipples drawn +with \fIgc\fR in the current offscreen pixmap will line up +with stipples drawn with origin (0,0) in the canvas's actual +window. +\fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee +that stipple patterns line up properly when the canvas is +redisplayed in small pieces. +Redisplays are carried out in double-buffered fashion where a +piece of the canvas is redrawn in an offscreen pixmap and then +copied back onto the screen. +In this approach the stipple origins in graphics contexts need to +be adjusted during each redisplay to compensate for the position +of the off-screen pixmap relative to the window. +If an item is being drawn with stipples, its type manager typically +calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR +to draw something; after it is finished drawing, the type manager +calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0) +(the restore is needed because graphics contexts are shared, so +they cannot be modified permanently). +.PP +\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR +except that it returns coordinates in the canvas's window on the +screen, instead of coordinates in an off-screen pixmap. +.PP +\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager +to inform Tk that a portion of a canvas needs to be redrawn. +The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments +specify the region that needs to be redrawn, in canvas coordinates. +Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR, +since Tk can normally figure out when an item has changed and make +the redisplay request on its behalf (this happens, for example +whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR). +The only time that a type manager needs to call +\fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own +without being invoked through one of the procedures in its Tk_ItemType; +this could happen, for example, in an image item if the image is +modified using image commands. +.PP +\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are +procedures that handle the \fB\-tags\fR option for canvas items. +The code of a canvas type manager won't call these procedures +directly, but will use their addresses to create a \fBTk_CustomOption\fR +structure for the \fB\-tags\fR option. The code typically looks +like this: +.CS +static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, + Tk_CanvasTagsPrintProc, (ClientData) NULL +}; + +static Tk_ConfigSpec configSpecs[] = { + ... + {TK_CONFIG_CUSTOM, "\-tags", (char *) NULL, (char *) NULL, + (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, + ... +}; +.CE + +.SH KEYWORDS +canvas, focus, item type, redisplay, selection, type manager diff --git a/doc/CanvTxtInfo.3 b/doc/CanvTxtInfo.3 new file mode 100644 index 0000000..47b37f7 --- /dev/null +++ b/doc/CanvTxtInfo.3 @@ -0,0 +1,104 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CanvTxtInfo.3 1.8 96/03/26 18:03:51 +'\" +.so man.macros +.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CanvasTextInfo \- additional information for managing text items in canvases +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_CanvasTextInfo * +\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR) +.SH ARGUMENTS +.AS Tk_Canvas canvas +.AP Tk_Canvas canvas in +A token that identifies a particular canvas widget. +.BE + +.SH DESCRIPTION +.PP +Textual canvas items are somewhat more complicated to manage than +other items, due to things like the selection and the input focus. +\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager +to obtain additional information needed for items that display text. +The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to +a structure that is shared between Tk and all the items that display +text. +The structure has the following form: +.CS +typedef struct Tk_CanvasTextInfo { + Tk_3DBorder \fIselBorder\fR; + int \fIselBorderWidth\fR; + XColor *\fIselFgColorPtr\fR; + Tk_Item *\fIselItemPtr\fR; + int \fIselectFirst\fR; + int \fIselectLast\fR; + Tk_Item *\fIanchorItemPtr\fR; + int \fIselectAnchor\fR; + Tk_3DBorder \fIinsertBorder\fR; + int \fIinsertWidth\fR; + int \fIinsertBorderWidth\fR; + Tk_Item *\fIfocusItemPtr\fR; + int \fIgotFocus\fR; + int \fIcursorOn\fR; +} Tk_CanvasTextInfo; +.CE +The \fBselBorder\fR field identifies a Tk_3DBorder that should be +used for drawing the background under selected text. +\fIselBorderWidth\fR gives the width of the raised border around +selected text, in pixels. +\fIselFgColorPtr\fR points to an XColor that describes the foreground +color to be used when drawing selected text. +\fIselItemPtr\fR points to the item that is currently selected, or +NULL if there is no item selected or if the canvas doesn't have the +selection. +\fIselectFirst\fR and \fIselectLast\fR give the indices of the first +and last selected characters in \fIselItemPtr\fR, as returned by the +\fIindexProc\fR for that item. +\fIanchorItemPtr\fR points to the item that currently has the selection +anchor; this is not necessarily the same as \fIselItemPtr\fR. +\fIselectAnchor\fR is an index that identifies the anchor position +within \fIanchorItemPtr\fR. +\fIinsertBorder\fR contains a Tk_3DBorder to use when drawing the +insertion cursor; \fIinsertWidth\fR gives the total width of the +insertion cursor in pixels, and \fIinsertBorderWidth\fR gives the +width of the raised border around the insertion cursor. +\fIfocusItemPtr\fR identifies the item that currently has the input +focus, or NULL if there is no such item. +\fIgotFocus\fR is 1 if the canvas widget has the input focus and +0 otherwise. +\fIcursorOn\fR is 1 if the insertion cursor should be drawn in +\fIfocusItemPtr\fR and 0 if it should not be drawn; this field +is toggled on and off by Tk to make the cursor blink. +.PP +The structure returned by \fBTk_CanvasGetTextInfo\fR +is shared between Tk and the type managers; typically the type manager +calls \fBTk_CanvasGetTextInfo\fR once when an item is created and +then saves the pointer in the item's record. +Tk will update information in the Tk_CanvasTextInfo; for example, +a \fBconfigure\fR widget command might change the \fIselBorder\fR +field, or a \fBselect\fR widget command might change the \fIselectFirst\fR +field, or Tk might change \fIcursorOn\fR in order to make the insertion +cursor flash on and off during successive redisplays. +.PP +Type managers should treat all of the fields of the Tk_CanvasTextInfo +structure as read-only, except for \fIselItemPtr\fR, \fIselectFirst\fR, +\fIselectLast\fR, and \fIselectAnchor\fR. +Type managers may change \fIselectFirst\fR, \fIselectLast\fR, and +\fIselectAnchor\fR to adjust for insertions and deletions in the +item (but only if the item is the current owner of the selection or +anchor, as determined by \fIselItemPtr\fR or \fIanchorItemPtr\fR). +If all of the selected text in the item is deleted, the item should +set \fIselItemPtr\fR to NULL to indicate that there is no longer a +selection. + +.SH KEYWORDS +canvas, focus, insertion cursor, selection, selection anchor, text diff --git a/doc/Clipboard.3 b/doc/Clipboard.3 new file mode 100644 index 0000000..10de58f --- /dev/null +++ b/doc/Clipboard.3 @@ -0,0 +1,80 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Clipboard.3 1.5 96/03/26 18:04:10 +'\" +.so man.macros +.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR) +.sp +int +\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR) +.SH ARGUMENTS +.AS Tk_ClipboardClear tkwin +.AP Tcl_Interp *interp in +Interpreter to use for reporting errors. +.AP Tk_Window tkwin in +Window that determines which display's clipboard to manipulate. +.AP Atom target in +Conversion type for this clipboard item; has same meaning as +\fItarget\fR argument to \fBTk_CreateSelHandler\fR. +.AP Atom format in +Representation to use when data is retrieved; has same meaning as +\fIformat\fR argument to \fBTk_CreateSelHandler\fR. +.AP char *buffer in +Null terminated string containing the data to be appended to the clipboard. +.BE + +.SH DESCRIPTION +.PP +These two procedures manage the clipboard for Tk. +The clipboard is typically managed by calling \fBTk_ClipboardClear\fR +once, then calling \fBTk_ClipboardAppend\fR to add data for any +number of targets. +.PP +\fBTk_ClipboardClear\fR claims the CLIPBOARD selection and frees any +data items previously stored on the clipboard in this application. +It normally returns TCL_OK, but if an error occurs it returns +TCL_ERROR and leaves an error message in \fIinterp->result\fR. +\fBTk_ClipboardClear\fR must be called before a sequence of +\fBTk_ClipboardAppend\fR calls can be issued. +.PP +\fBTk_ClipboardAppend\fR appends a buffer of data to the clipboard. +The first buffer for a given \fItarget\fR determines the \fIformat\fR +for that \fItarget\fR. +Any successive appends for that \fItarget\fR must have +the same format or an error will be returned. +\fBTk_ClipboardAppend\fR returns TCL_OK if the buffer is +successfully copied onto the clipboard. If the clipboard is not +currently owned by the application, either +because \fBTk_ClipboardClear\fR has not been called or because +ownership of the clipboard has changed since the last call to +\fBTk_ClipboardClear\fR, +\fBTk_ClipboardAppend\fR returns TCL_ERROR and leaves an error message in +\fIinterp->result\fR. +.PP +In order to guarantee atomicity, no event handling should occur +between \fBTk_ClipboardClear\fR and the following +\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve +a partially completed clipboard or claim ownership away from +this application). +.PP +\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary +Tcl scripts, as a result of losing the CLIPBOARD selection, so +any calling function should take care to be reentrant at the point +\fBTk_ClipboardClear\fR is invoked. + +.SH KEYWORDS +append, clipboard, clear, format, type diff --git a/doc/ClrSelect.3 b/doc/ClrSelect.3 new file mode 100644 index 0000000..6100973 --- /dev/null +++ b/doc/ClrSelect.3 @@ -0,0 +1,42 @@ +'\" +'\" Copyright (c) 1992-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ClrSelect.3 1.10 96/08/27 13:21:16 +'\" +.so man.macros +.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ClearSelection \- Deselect a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ClearSelection\fR(\fItkwin, selection\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +The selection will be cleared from the display containing this +window. +.AP Atom selection in +The name of selection to be cleared. +.BE + +.SH DESCRIPTION +.PP +\fBTk_ClearSelection\fR cancels the selection specified by the atom +\fIselection\fR for the display containing \fItkwin\fR. +The selection need not be in \fItkwin\fR itself or even in +\fItkwin\fR's application. +If there is a window anywhere on \fItkwin\fR's display that +owns \fIselection\fR, the window will be notified and the +selection will be cleared. +If there is no owner for \fIselection\fR on the display, then the +procedure has no effect. + +.SH KEYWORDS +clear, selection diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 new file mode 100644 index 0000000..3178580 --- /dev/null +++ b/doc/ConfigWidg.3 @@ -0,0 +1,618 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ConfigWidg.3 1.30 96/08/27 13:21:18 +'\" +.so man.macros +.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR +.sp +int +\fBTk_Offset(\fItype, field\fB)\fR +.sp +int +\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR +.sp +int +.sp +\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR +.SH ARGUMENTS +.AS Tk_ConfigSpec *widgRec +.AP Tcl_Interp *interp in +Interpreter to use for returning error messages. +.AP Tk_Window tkwin in +Window used to represent widget (needed to set up X resources). +.AP Tk_ConfigSpec *specs in +Pointer to table specifying legal configuration options for this +widget. +.AP int argc in +Number of arguments in \fIargv\fR. +.AP char **argv in +Command-line options for configuring widget. +.AP char *widgRec in/out +Points to widget record structure. Fields in this structure get +modified by \fBTk_ConfigureWidget\fR to hold configuration information. +.AP int flags in +If non-zero, then it specifies an OR-ed combination of flags that +control the processing of configuration information. +TK_CONFIG_ARGV_ONLY causes the option database and defaults to be +ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to +selectively disable entries in \fIspecs\fR. +.AP "type name" type in +The name of the type of a widget record. +.AP "field name" field in +The name of a field in records of type \fItype\fR. +.AP char *argvName in +The name used on Tcl command lines to refer to a particular option +(e.g. when creating a widget or invoking the \fBconfigure\fR widget +command). If non-NULL, then information is returned only for this +option. If NULL, then information is returned for all available +options. +.AP Display *display in +Display containing widget whose record is being freed; needed in +order to free up resources. +.BE +.SH DESCRIPTION +.PP +\fBTk_ConfigureWidget\fR is called to configure various aspects of a +widget, such as colors, fonts, border width, etc. +It is intended as a convenience procedure to reduce the amount +of code that must be written in individual widget managers to +handle configuration information. +It is typically +invoked when widgets are created, and again when the \fBconfigure\fR +command is invoked for a widget. +Although intended primarily for widgets, \fBTk_ConfigureWidget\fR +can be used in other situations where \fIargc-argv\fR information +is to be used to fill in a record structure, such as configuring +graphical elements for a canvas widget or entries of a menu. +.PP +\fBTk_ConfigureWidget\fR processes +a table specifying the configuration options that are supported +(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and +\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR). +It uses the option database and defaults specified in \fIspecs\fR +to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. +\fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this +case it does not modify \fIinterp\fR. +If an error +occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will +leave an error message in \fIinterp->result\fR in the standard Tcl +fashion. +In the event of an error return, some of the fields of \fIwidgRec\fR +could already have been set, if configuration information for them +was successfully processed before the error occurred. +The other fields will be set to reasonable initial values so that +\fBTk_FreeOptions\fR can be called for cleanup. +.PP +The \fIspecs\fR array specifies the kinds of configuration options +expected by the widget. Each of its entries specifies one configuration +option and has the following structure: +.CS +typedef struct { + int \fItype\fR; + char *\fIargvName\fR; + char *\fIdbName\fR; + char *\fIdbClass\fR; + char *\fIdefValue\fR; + int \fIoffset\fR; + int \fIspecFlags\fR; + Tk_CustomOption *\fIcustomPtr\fR; +} Tk_ConfigSpec; +.CE +The \fItype\fR field indicates what type of configuration option this is +(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for +an integer value). The \fItype\fR field indicates how to use the +value of the option (more on this below). +The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'', +which is compared with the values in \fIargv\fR (if \fIargvName\fR is +NULL it means this is a grouped entry; see GROUPED ENTRIES below). The +\fIdbName\fR and \fIdbClass\fR fields are used to look up a value +for this option in the option database. The \fIdefValue\fR field +specifies a default value for this configuration option if no +value is specified in either \fIargv\fR or the option database. +\fIOffset\fR indicates where in \fIwidgRec\fR to store information +about this option, and \fIspecFlags\fR contains additional information +to control the processing of this configuration option (see FLAGS +below). +The last field, \fIcustomPtr\fR, is only used if \fItype\fR is +TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. +.PP +\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which +(if any) configuration options are specified there. \fIArgv\fR +must contain an even number of fields; the first of each pair +of fields must match the \fIargvName\fR of some entry in \fIspecs\fR +(unique abbreviations are acceptable), +and the second field of the pair contains the value for that +configuration option. If there are entries in \fIspec\fR for which +there were no matching entries in \fIargv\fR, +\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR +fields of the \fIspecs\fR entry to probe the option database; if +a value is found, then it is used as the value for the option. +Finally, if no entry is found in the option database, the +\fIdefValue\fR field of the \fIspecs\fR entry is used as the +value for the configuration option. If the \fIdefValue\fR is +NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in +\fIflags\fR, then there is no default value and this \fIspecs\fR entry +will be ignored if no value is specified in \fIargv\fR or the +option database. +.PP +Once a string value has been determined for a configuration option, +\fBTk_ConfigureWidget\fR translates the string value into a more useful +form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer +if \fItype\fR is TK_CONFIG_INT. This value is then stored in the +record pointed to by \fIwidgRec\fR. This record is assumed to +contain information relevant to the manager of the widget; its exact +type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field +of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store +the information about this configuration option. You should use the +\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for +a description of \fBTk_Offset\fR). The location indicated by +\fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target'' +in the descriptions below. +.PP +The \fItype\fR field of each entry in \fIspecs\fR determines what +to do with the string value of that configuration option. The +legal values for \fItype\fR, and the corresponding actions, are: +.TP +\fBTK_CONFIG_ACTIVE_CURSOR\fR +The value +must be an ASCII string identifying a cursor in a form +suitable for passing to \fBTk_GetCursor\fR. +The value is converted to a \fBTk_Cursor\fR by calling +\fBTk_GetCursor\fR and the result is stored in the target. +In addition, the resulting cursor is made the active cursor +for \fItkwin\fR by calling \fBXDefineCursor\fR. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target and \fItkwin\fR's +active cursor will be set to \fBNone\fR. +If the previous value of the target +wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. +.TP +\fBTK_CONFIG_ANCHOR\fR +The value must be an ASCII string identifying an anchor point in one of the ways +accepted by \fBTk_GetAnchor\fR. +The string is converted to a \fBTk_Anchor\fR by calling +\fBTk_GetAnchor\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_BITMAP\fR +The value must be an ASCII string identifying a bitmap in a form +suitable for passing to \fBTk_GetBitmap\fR. The value is converted +to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result +is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target is set to \fBNone\fR. +If the previous value of the target +wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. +.TP +\fBTK_CONFIG_BOOLEAN\fR +The value must be an ASCII string specifying a boolean value. Any +of the values ``true'', ``yes'', ``on'', or ``1'', +or an abbreviation of one of these values, means true; +any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of +one of these values, means false. +The target is expected to be an integer; for true values it will +be set to 1 and for false values it will be set to 0. +.TP +\fBTK_CONFIG_BORDER\fR +The value must be an ASCII string identifying a border color in a form +suitable for passing to \fBTk_Get3DBorder\fR. The value is converted +to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result +is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target +wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. +.TP +\fBTK_CONFIG_CAP_STYLE\fR +The value must be +an ASCII string identifying a cap style in one of the ways +accepted by \fBTk_GetCapStyle\fR. +The string is converted to an integer value corresponding +to the cap style by calling +\fBTk_GetCapStyle\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_COLOR\fR +The value must be an ASCII string identifying a color in a form +suitable for passing to \fBTk_GetColor\fR. The value is converted +to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result +is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to \fBNone\fR. +If the previous value of the target +wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR. +.TP +\fBTK_CONFIG_CURSOR\fR +This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except +that the new cursor is not made the active one for \fItkwin\fR. +.TP +\fBTK_CONFIG_CUSTOM\fR +This option allows applications to define new option types. +The \fIcustomPtr\fR field of the entry points to a structure +defining the new option type. +See the section CUSTOM OPTION TYPES below for details. +.TP +\fBTK_CONFIG_DOUBLE\fR +The value must be an ASCII floating-point number in +the format accepted by \fBstrtol\fR. The string is converted +to a \fBdouble\fR value, and the value is stored in the +target. +.TP +\fBTK_CONFIG_END\fR +Marks the end of the table. The last entry in \fIspecs\fR +must have this type; all of its other fields are ignored and it +will never match any arguments. +.TP +\fBTK_CONFIG_FONT\fR +The value must be an ASCII string identifying a font in a form +suitable for passing to \fBTk_GetFontStruct\fR. The value is converted +to an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the result +is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target +wasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR. +.TP +\fBTK_CONFIG_INT\fR +The value must be an ASCII integer string +in the format accepted by \fBstrtol\fR (e.g. ``0'' +and ``0x'' prefixes may be used to specify octal or hexadecimal +numbers, respectively). The string is converted to an integer +value and the integer is stored in the target. +.TP +\fBTK_CONFIG_JOIN_STYLE\fR +The value must be +an ASCII string identifying a join style in one of the ways +accepted by \fBTk_GetJoinStyle\fR. +The string is converted to an integer value corresponding +to the join style by calling +\fBTk_GetJoinStyle\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_JUSTIFY\fR +The value must be +an ASCII string identifying a justification method in one of the +ways accepted by \fBTk_GetJustify\fR. +The string is converted to a \fBTk_Justify\fR by calling +\fBTk_GetJustify\fR and the result is stored in the target. +.TP +\fBTK_CONFIG_MM\fR +The value must specify a screen distance in one of the forms acceptable +to \fBTk_GetScreenMM\fR. +The string is converted to double-precision floating-point distance +in millimeters and the value is stored in the target. +.TP +\fBTK_CONFIG_PIXELS\fR +The value must specify screen units in one of the forms acceptable +to \fBTk_GetPixels\fR. +The string is converted to an integer distance in pixels and the +value is stored in the target. +.TP +\fBTK_CONFIG_RELIEF\fR +The value must be an ASCII string identifying a relief in a form +suitable for passing to \fBTk_GetRelief\fR. The value is converted +to an integer relief value by calling \fBTk_GetRelief\fR and the result +is stored in the target. +.TP +\fBTK_CONFIG_STRING\fR +A copy +of the value is made by allocating memory space with +\fBmalloc\fR and copying the value into the dynamically-allocated +space. A pointer to the new string is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value +may be an empty string, in which case the target will be set to NULL. +If the previous value of the target wasn't NULL, then it is +freed by passing it to \fBfree\fR. +.TP +\fBTK_CONFIG_SYNONYM\fR +This \fItype\fR value identifies special entries in \fIspecs\fR that +are synonyms for other entries. If an \fIargv\fR value matches the +\fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used +directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR +for another entry whose \fIargvName\fR is the same as the \fIdbName\fR +field in the TK_CONFIG_SYNONYM entry; this new entry is used just +as if its \fIargvName\fR had matched the \fIargv\fR value. The +synonym mechanism allows multiple \fIargv\fR values to be used for +a single configuration option, such as ``\-background'' and ``\-bg''. +.TP +\fBTK_CONFIG_UID\fR +The value is translated to a \fBTk_Uid\fR +(by passing it to \fBTk_GetUid\fR). The resulting value +is stored in the target. +If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value +is an empty string then the target will be set to NULL. +.TP +\fBTK_CONFIG_WINDOW\fR +The value must be a window path name. It is translated to a +\fBTk_Window\fR token and the token is stored in the target. + +.SH "GROUPED ENTRIES" +.PP +In some cases it is useful to generate multiple resources from +a single configuration value. For example, a color name might +be used both to generate the background color for a widget (using +TK_CONFIG_COLOR) and to generate a 3-D border to draw around the +widget (using TK_CONFIG_BORDER). In cases like this it is possible +to specify that several consecutive entries in \fIspecs\fR are to +be treated as a group. The first entry is used to determine a value +(using its \fIargvName\fR, \fIdbName\fR, +\fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed +several times (one for each entry in the group), generating multiple +different resources and modifying multiple targets within \fIwidgRec\fR. +Each of the entries after the first must have a NULL value in its +\fIargvName\fR field; this indicates that the entry is to be grouped +with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR +fields are used from these follow-on entries. + +.SH "FLAGS" +.PP +The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used +in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR +to provide additional control over the processing of configuration +options. These values are used in three different ways as +described below. +.PP +First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has +the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0), +then the option database and +\fIdefValue\fR fields are not used. In this case, if an entry in +\fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens: +the corresponding target isn't modified. This feature is useful +when the goal is to modify certain configuration options while +leaving others in their current state, such as when a \fBconfigure\fR +widget command is being processed. +.PP +Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used +to control the processing of that entry. Each \fIspecFlags\fR +field may consists of an OR-ed combination of the following values: +.TP +\fBTK_CONFIG_COLOR_ONLY\fR +If this bit is set then the entry will only be considered if the +display for \fItkwin\fR has more than one bit plane. If the display +is monochromatic then this \fIspecs\fR entry will be ignored. +.TP +\fBTK_CONFIG_MONO_ONLY\fR +If this bit is set then the entry will only be considered if the +display for \fItkwin\fR has exactly one bit plane. If the display +is not monochromatic then this \fIspecs\fR entry will be ignored. +.TP +\fBTK_CONFIG_NULL_OK\fR +This bit is only relevant for some types of entries (see the +descriptions of the various entry types above). +If this bit is set, it indicates that an empty string value +for the field is acceptable and if it occurs then the +target should be set to NULL or \fBNone\fR, depending +on the type of the target. +This flag is typically used to allow a +feature to be turned off entirely, e.g. set a cursor value to +\fBNone\fR so that a window simply inherits its parent's cursor. +If this bit isn't set then empty strings are processed as strings, +which generally results in an error. +.TP +\fBTK_CONFIG_DONT_SET_DEFAULT\fR +If this bit is one, it means that the \fIdefValue\fR field of the +entry should only be used for returning the default value in +\fBTk_ConfigureInfo\fR. +In calls to \fBTk_ConfigureWidget\fR no default will be supplied +for entries with this flag set; it is assumed that the +caller has already supplied a default value in the target location. +This flag provides a performance optimization where it is expensive +to process the default string: the client can compute the default +once, save the value, and provide it before calling +\fBTk_ConfigureWidget\fR. +.TP +\fBTK_CONFIG_OPTION_SPECIFIED\fR +This bit is set and cleared by \fBTk_ConfigureWidget\fR. Whenever +\fBTk_ConfigureWidget\fR returns, this bit will be set in all the +entries where a value was specified in \fIargv\fR. +It will be zero in all other entries. +This bit provides a way for clients to determine which values +actually changed in a call to \fBTk_ConfigureWidget\fR. +.PP +The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically +used to specify different default values for +monochrome and color displays. This is done by creating two +entries in \fIspecs\fR that are identical except for their +\fIdefValue\fR and \fIspecFlags\fR fields. One entry should have +the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the +default value for monochrome displays in its \fIdefValue\fR; the +other entry entry should have the value TK_CONFIG_COLOR_ONLY in +its \fIspecFlags\fR and the appropriate \fIdefValue\fR for +color displays. +.PP +Third, it is possible to use \fIflags\fR and \fIspecFlags\fR +together to selectively disable some entries. This feature is +not needed very often. It is useful in cases where several +similar kinds of widgets are implemented in one place. It allows +a single \fIspecs\fR table to be created with all the configuration +options for all the widget types. When processing a particular +widget type, only entries relevant to that type will be used. This +effect is achieved by setting the high-order bits (those in positions +equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR +values or in \fIflags\fR. In order for a particular entry in +\fIspecs\fR to be used, its high-order bits must match exactly +the high-order bits of the \fIflags\fR value passed to +\fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used +for N different widget types, then N of the high-order bits will +be used. Each \fIspecs\fR entry will have one of more of those +bits set in its \fIspecFlags\fR field to indicate the widget types +for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, +\fIflags\fR will have a single one of these bits set to select the +entries for the desired widget type. For a working example of +this feature, see the code in tkButton.c. + +.SH TK_OFFSET +.PP +The \fBTk_Offset\fR macro is provided as a safe way of generating +the \fIoffset\fR values for entries in Tk_ConfigSpec structures. +It takes two arguments: the name of a type of record, and the +name of a field in that record. It returns the byte offset of +the named field in records of the given type. + +.SH TK_CONFIGUREINFO +.PP +The \fBTk_ConfigureInfo\fR procedure may be used to obtain +information about one or all of the options for a given widget. +Given a token for a window (\fItkwin\fR), a table describing the +configuration options for a class of widgets (\fIspecs\fR), a +pointer to a widget record containing the current information for +a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, +\fBTk_ConfigureInfo\fR generates a string describing all of the +configuration options for the window. The string is placed +in \fIinterp->result\fR. Under normal circumstances +it returns TCL_OK; if an error occurs then it returns TCL_ERROR +and \fIinterp->result\fR contains an error message. +.PP +If \fIargvName\fR is NULL, then the value left in +\fIinterp->result\fR by \fBTk_ConfigureInfo\fR +consists of a list of one or more entries, each of which describes +one configuration option (i.e. one entry in \fIspecs\fR). Each +entry in the list will contain either two or five values. If the +corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then +the list will contain two values: the \fIargvName\fR for the entry +and the \fIdbName\fR (synonym name). Otherwise the list will contain +five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, +and current value. The current value is computed from the appropriate +field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. +.PP +If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, +then it indicates a single option, and information is returned only +for that option. The string placed in \fIinterp->result\fR will be +a list containing two or five values as described above; this will +be identical to the corresponding sublist that would have been returned +if \fIargvName\fR had been NULL. +.PP +The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict +the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. + +.SH TK_CONFIGUREVALUE +.PP +\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; +instead of returning a list of values, it just returns the current value +of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). +The value is returned in \fIinterp->result\fR and TCL_OK is +normally returned as the procedure's result. +If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is +not a valid option name), TCL_ERROR is returned and an error message +is left in \fIinterp->result\fR. +This procedure is typically called to implement \fBcget\fR widget +commands. + +.SH TK_FREEOPTIONS +.PP +The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup +to release all of the resources associated with configuration options. +It scans through \fIspecs\fR and for each entry corresponding to a +resource that must be explicitly freed (e.g. those with +type TK_CONFIG_COLOR), it frees the resource in the widget record. +If the field in the widget record doesn't refer to a resource (e.g. +it contains a null pointer) then no resource is freed for that +entry. +After freeing a resource, \fBTk_FreeOptions\fR sets the +corresponding field of the widget record to null. + +.SH "CUSTOM OPTION TYPES" +.PP +Applications can extend the built-in configuration types with additional +configuration types by writing procedures to parse and print options +of the a type and creating a structure pointing to those procedures: +.CS +typedef struct Tk_CustomOption { + Tk_OptionParseProc *\fIparseProc\fR; + Tk_OptionPrintProc *\fIprintProc\fR; + ClientData \fIclientData\fR; +} Tk_CustomOption; + +typedef int Tk_OptionParseProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tk_Window \fItkwin\fR, + char *\fIvalue\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR); + +typedef char *Tk_OptionPrintProc( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR, + char *\fIwidgRec\fR, + int \fIoffset\fR, + Tcl_FreeProc **\fIfreeProcPtr\fR); +.CE +The Tk_CustomOption structure contains three fields, which are pointers +to the two procedures and a \fIclientData\fR value to be passed to those +procedures when they are invoked. The \fIclientData\fR value typically +points to a structure containing information that is needed by the +procedures when they are parsing and printing options. +.PP +The \fIparseProc\fR procedure is invoked by +\fBTk_ConfigureWidget\fR to parse a string and store the resulting +value in the widget record. +The \fIclientData\fR argument is a copy of the \fIclientData\fR +field in the Tk_CustomOption structure. +The \fIinterp\fR argument points to a Tcl interpreter used for +error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument +to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string +describing the value for the option; it could have been specified +explicitly in the call to \fBTk_ConfigureWidget\fR or it could +come from the option database or a default. +\fIValue\fR will never be a null pointer but it may point to +an empty string. +\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to +\fBTk_ConfigureWidget\fR; it points to the start of the widget +record to modify. +The last argument, \fIoffset\fR, gives the offset in bytes from the start +of the widget record to the location where the option value is to +be placed. The procedure should translate the string to whatever +form is appropriate for the option and store the value in the widget +record. It should normally return TCL_OK, but if an error occurs +in translating the string to a value then it should return TCL_ERROR +and store an error message in \fIinterp->result\fR. +.PP +The \fIprintProc\fR procedure is called +by \fBTk_ConfigureInfo\fR to produce a string value describing an +existing option. +Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR +arguments all have the same meaning as for Tk_OptionParseProc +procedures. +The \fIprintProc\fR procedure should examine the option whose value +is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing +that option, and return a pointer to the string. +If the string is stored in dynamically-allocated memory, then +the procedure must set \fI*freeProcPtr\fR to the address of +a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR +will call this procedure when it is finished with the string. +If the result string is stored in static memory then \fIprintProc\fR +need not do anything with the \fIfreeProcPtr\fR argument. +.PP +Once \fIparseProc\fR and \fIprintProc\fR have been defined and a +Tk_CustomOption structure has been created for them, options of this +new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR +fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point +to the Tk_CustomOption structure. + +.SH EXAMPLES +.PP +Although the explanation of \fBTk_ConfigureWidget\fR is fairly +complicated, its actual use is pretty straightforward. +The easiest way to get started is to copy the code +from an existing widget. +The library implementation of frames +(tkFrame.c) has a simple configuration table, and the library +implementation of buttons (tkButton.c) has a much more complex +table that uses many of the fancy \fIspecFlags\fR mechanisms. + +.SH KEYWORDS +anchor, bitmap, boolean, border, cap style, color, configuration options, +cursor, custom, double, font, integer, join style, justify, millimeters, +pixels, relief, synonym, uid diff --git a/doc/ConfigWind.3 b/doc/ConfigWind.3 new file mode 100644 index 0000000..bbfd929 --- /dev/null +++ b/doc/ConfigWind.3 @@ -0,0 +1,153 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ConfigWind.3 1.27 96/08/27 13:21:19 +'\" +.so man.macros +.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR) +.sp +\fBTk_MoveWindow\fR(\fItkwin, x, y\fR) +.sp +\fBTk_ResizeWindow\fR(\fItkwin, width, height\fR) +.sp +\fBTk_MoveResizeWindow\fR(\fItkwin, x, y, width, height\fR) +.sp +\fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR) +.sp +\fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR) +.sp +\fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR) +.sp +\fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR) +.sp +\fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR) +.sp +\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR) +.sp +\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR) +.sp +\fBTk_DefineCursor\fR(\fItkwin, cursor\fR) +.sp +\fBTk_UndefineCursor\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS XSetWindowAttributes borderWidth +.AP Tk_Window tkwin in +Token for window. +.AP "unsigned int" valueMask in +OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR, +indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use. +.AP XWindowChanges *valuePtr in +Points to a structure containing new values for the configuration +parameters selected by \fIvalueMask\fR. Fields not selected +by \fIvalueMask\fR are ignored. +.AP int x in +New x-coordinate for \fItkwin\fR's top left pixel (including +border, if any) within tkwin's parent. +.AP int y in +New y-coordinate for \fItkwin\fR's top left pixel (including +border, if any) within tkwin's parent. +.AP "int" width in +New width for \fItkwin\fR (interior, not including border). +.AP "int" height in +New height for \fItkwin\fR (interior, not including border). +.AP "int" borderWidth in +New width for \fItkwin\fR's border. +.AP XSetWindowAttributes *attsPtr in +Points to a structure containing new values for the attributes +given by the \fIvalueMask\fR argument. Attributes not selected +by \fIvalueMask\fR are ignored. +.AP "unsigned long" pixel in +New background or border color for window. +.AP Pixmap pixmap in +New pixmap to use for background or border of \fItkwin\fR. WARNING: +cannot necessarily be deleted immediately, as for Xlib calls. See +note below. +.AP Colormap colormap in +New colormap to use for \fItkwin\fR. +.AP Tk_Cursor cursor in +New cursor to use for \fItkwin\fR. If \fBNone\fR is specified, then +\fItkwin\fR will not have its own cursor; it will use the cursor +of its parent. +.BE + +.SH DESCRIPTION +.PP +These procedures are analogous to the X library procedures +with similar names, such as \fBXConfigureWindow\fR. Each +one of the above procedures calls the corresponding X procedure +and also saves the configuration information in Tk's local +structure for the window. This allows the information to +be retrieved quickly by the application (using macros such +as \fBTk_X\fR and \fBTk_Height\fR) without having to contact +the X server. In addition, if no X window has actually been +created for \fItkwin\fR yet, these procedures do not issue +X operations or cause event handlers to be invoked; they save +the information in Tk's local +structure for the window; when the window is created later, +the saved information will be used to configure the window. +.PP +See the X library documentation for details on what these +procedures do and how they use their arguments. +.PP +In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR, +\fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and +\fBTk_SetWindowBorderWidth\fR, +if \fItkwin\fR is an internal window then event handlers interested +in configure events are invoked immediately, before the procedure +returns. If \fItkwin\fR is a top-level window +then the event handlers will be invoked later, after X has seen +the request and returned an event for it. +.PP +Applications using Tk should never call procedures like +\fBXConfigureWindow\fR directly; they should always use the +corresponding Tk procedures. +.PP +The size and location of a window should only be modified by the +appropriate geometry manager for that window and never by a window +itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level +window). +.PP +You may not use \fBTk_ConfigureWindow\fR to change the +stacking order of a window (\fIvalueMask\fR may not contain the +\fBCWSibling\fR or \fBCWStackMode\fR bits). +To change the stacking order, use the procedure \fBTk_RestackWindow\fR. +.PP +The procedure \fBTk_SetWindowColormap\fR will automatically add +\fItkwin\fR to the \fBTK_COLORMAP_WINDOWS\fR property of its +nearest top-level ancestor if the new colormap is different from +that of \fItkwin\fR's parent and \fItkwin\fR isn't already in +the \fBTK_COLORMAP_WINDOWS\fR property. + +.SH BUGS +.PP +\fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR +differ slightly from their Xlib counterparts in that the \fIpixmap\fR +argument may not necessarily be deleted immediately after calling +one of these procedures. This is because \fItkwin\fR's window +may not exist yet at the time of the call, in which case \fIpixmap\fR +is merely saved and used later when \fItkwin\fR's window is actually +created. If you wish to delete \fIpixmap\fR, then call +\fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists +and \fIpixmap\fR has been passed to the X server. +.PP +A similar problem occurs for the \fIcursor\fR argument passed to +\fBTk_DefineCursor\fR. The solution is the same as for pixmaps above: +call \fBTk_MakeWindowExist\fR before freeing the cursor. + +.SH "SEE ALSO" +Tk_MoveToplevelWindow, Tk_RestackWindow + +.SH KEYWORDS +attributes, border, color, configure, height, pixel, pixmap, width, window, x, y diff --git a/doc/CoordToWin.3 b/doc/CoordToWin.3 new file mode 100644 index 0000000..8773095 --- /dev/null +++ b/doc/CoordToWin.3 @@ -0,0 +1,51 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CoordToWin.3 1.9 96/03/26 18:05:14 +'\" +.so man.macros +.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CoordsToWindow \- Find window containing a point +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP int rootX in +X-coordinate (in root window coordinates). +.AP int rootY in +Y-coordinate (in root window coordinates). +.AP Tk_Window tkwin in +Token for window that identifies application. +.BE + +.SH DESCRIPTION +.PP +\fBTk_CoordsToWindow\fR locates the window that contains a given point. +The point is specified in root coordinates with \fIrootX\fR and +\fIrootY\fR (if a virtual-root window manager is in use then +\fIrootX\fR and \fIrootY\fR are in the coordinate system of the +virtual root window). +The return value from the procedure is a token for the window that +contains the given point. +If the point is not in any window, or if the containing window +is not in the same application as \fItkwin\fR, then NULL is +returned. +.PP +The containing window is decided using the same rules that determine +which window contains the mouse cursor: if a parent and a child both +contain the point then the child gets preference, and if two siblings +both contain the point then the highest one in the stacking order +(i.e. the one that's visible on the screen) gets preference. + +.SH KEYWORDS +containing, coordinates, root window diff --git a/doc/CrtErrHdlr.3 b/doc/CrtErrHdlr.3 new file mode 100644 index 0000000..a28a77b --- /dev/null +++ b/doc/CrtErrHdlr.3 @@ -0,0 +1,145 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtErrHdlr.3 1.12 96/03/26 18:05:30 +'\" +.so man.macros +.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_ErrorHandler +\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR) +.sp +\fBTk_DeleteErrorHandler\fR(\fIhandler\fR) +.SH ARGUMENTS +.AS "Tk_ErrorHandler" clientData +.AP Display *display in +Display whose errors are to be handled. +.AP int error in +Match only error events with this value in the \fIerror_code\fR +field. If -1, then match any \fIerror_code\fR value. +.AP int request in +Match only error events with this value in the \fIrequest_code\fR +field. If -1, then match any \fIrequest_code\fR value. +.AP int minor in +Match only error events with this value in the \fIminor_code\fR +field. If -1, then match any \fIminor_code\fR value. +.AP Tk_ErrorProc *proc in +Procedure to invoke whenever an error event is received for +\fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR. +NULL means ignore any matching errors. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.AP Tk_ErrorHandler handler in +Token for error handler to delete (return value from a previous +call to \fBTk_CreateErrorHandler\fR). +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreateErrorHandler\fR arranges for a particular procedure +(\fIproc\fR) to be called whenever certain protocol errors occur on a +particular display (\fIdisplay\fR). Protocol errors occur when +the X protocol is used incorrectly, such as attempting to map a window +that doesn't exist. See the Xlib documentation for \fBXSetErrorHandler\fR +for more information on the kinds of errors that can occur. +For \fIproc\fR to be invoked +to handle a particular error, five things must occur: +.IP [1] +The error must pertain to \fIdisplay\fR. +.IP [2] +Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR +must have been -1, or the \fIerror\fR argument must match +the \fIerror_code\fR field from the error event. +.IP [3] +Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR +must have been -1, or the \fIrequest\fR argument must match +the \fIrequest_code\fR field from the error event. +.IP [4] +Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR +must have been -1, or the \fIminor\fR argument must match +the \fIminor_code\fR field from the error event. +.IP [5] +The protocol request to which the error pertains must have been +made when the handler was active (see below for more information). +.PP +\fIProc\fR should have arguments and result that match the +following type: +.CS +typedef int Tk_ErrorProc( + ClientData \fIclientData\fR, + XErrorEvent *\fIerrEventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTcl_CreateErrorHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information that is +needed to deal with the error. \fIErrEventPtr\fR is +a pointer to the X error event. +The procedure \fIproc\fR should return an integer value. If it +returns 0 it means that \fIproc\fR handled the error completely and there +is no need to take any other action for the error. If it returns +non-zero it means \fIproc\fR was unable to handle the error. +.PP +If a value of NULL is specified for \fIproc\fR, all matching errors +will be ignored: this will produce the same result as if a procedure +had been specified that always returns 0. +.PP +If more than more than one handler matches a particular error, then +they are invoked in turn. The handlers will be invoked in reverse +order of creation: most recently declared handler first. +If any handler returns 0, then subsequent (older) handlers will +not be invoked. If no handler returns 0, then Tk invokes X'es +default error handler, which prints an error message and aborts the +program. If you wish to have a default handler that deals with errors +that no other handler can deal with, then declare it first. +.PP +The X documentation states that ``the error handler should not call +any functions (directly or indirectly) on the display that will +generate protocol requests or that will look for input events.'' +This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR; +disobey it at your own risk. +.PP +\fBTk_DeleteErrorHandler\fR may be called to delete a +previously-created error handler. The \fIhandler\fR argument +identifies the error handler, and should be a value returned by +a previous call to \fBTk_CreateEventHandler\fR. +.PP +A particular error handler applies to errors resulting +from protocol requests generated between +the call to \fBTk_CreateErrorHandler\fR and the call to +\fBTk_DeleteErrorHandler\fR. However, the actual callback +to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR +call, due to buffering in the client and server. +If an error event pertains to +a protocol request made just before calling \fBTk_DeleteErrorHandler\fR, +then the error event may not have been processed +before the \fBTk_DeleteErrorHandler\fR +call. When this situation arises, Tk will save information about +the handler and +invoke the handler's \fIproc\fR later when the error event +finally arrives. +If an application wishes to delete an error handler and know +for certain that all relevant errors have been processed, +it should first call \fBTk_DeleteErrorHandler\fR and then +call \fBXSync\fR; this will flush out any buffered requests and errors, +but will result in a performance penalty because +it requires communication to and from the X server. After the +\fBXSync\fR call Tk is guaranteed not to call any error +handlers deleted before the \fBXSync\fR call. +.PP +For the Tk error handling mechanism to work properly, it is essential +that application code never calls \fBXSetErrorHandler\fR directly; +applications should use only \fBTk_CreateErrorHandler\fR. + +.SH KEYWORDS +callback, error, event, handler diff --git a/doc/CrtGenHdlr.3 b/doc/CrtGenHdlr.3 new file mode 100644 index 0000000..df3eca5 --- /dev/null +++ b/doc/CrtGenHdlr.3 @@ -0,0 +1,84 @@ +'\" +'\" Copyright (c) 1992-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtGenHdlr.3 1.9 96/03/26 18:06:21 +'\" +.so man.macros +.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR) +.sp +\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR) +.SH ARGUMENTS +.AS "Tk_GenericProc" clientData +.AP Tk_GenericProc *proc in +Procedure to invoke whenever any X event occurs on any display. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreateGenericHandler\fR arranges for \fIproc\fR to be +invoked in the future whenever any X event occurs. This mechanism is +\fInot\fR intended for dispatching X events on windows managed by Tk +(you should use \fBTk_CreateEventHandler\fR for this purpose). +\fBTk_CreateGenericHandler\fR is intended for other purposes, such +as tracing X events, monitoring events on windows not owned by Tk, +accessing X-related libraries that were not originally designed for +use with Tk, and so on. +.PP +The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; +this mechanism only works in programs that dispatch events +through \fBTk_HandleEvent\fR (or through other Tk procedures that +call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or +\fBTk_MainLoop\fR). +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_GenericProc\fR: +.CS +typedef int Tk_GenericProc( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTk_CreateGenericHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +how to handle events. +\fIEventPtr\fR is a pointer to the X event. +.PP +Whenever an X event is processed by \fBTk_HandleEvent\fR, \fIproc\fR +is called. The return value from \fIproc\fR is normally 0. +A non-zero return value indicates that the event is not to be handled +further; that is, \fIproc\fR has done all processing that is to be +allowed for the event. +.PP +If there are multiple generic event handlers, each one is called +for each event, in the order in which they were established. +.PP +\fBTk_DeleteGenericHandler\fR may be called to delete a +previously-created generic event handler: it deletes each handler +it finds that matches the \fIproc\fR and \fIclientData\fR arguments. If +no such handler exists, then \fBTk_DeleteGenericHandler\fR returns +without doing anything. Although Tk supports it, it's probably +a bad idea to have more than one callback with the same +\fIproc\fR and \fIclientData\fR arguments. +.PP +Establishing a generic event handler does nothing to ensure that the +process will actually receive the X events that the handler wants to +process. +For example, it is the caller's responsibility to invoke +\fBXSelectInput\fR to select the desired events, if that is necessary. +.SH KEYWORDS +bind, callback, event, handler diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3 new file mode 100644 index 0000000..4ad5799 --- /dev/null +++ b/doc/CrtImgType.3 @@ -0,0 +1,255 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtImgType.3 1.9 97/08/08 15:43:15 +'\" +.so man.macros +.TH Tk_CreateImageType 3 8.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateImageType, Tk_GetImageMasterData \- define new kind of image +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateImageType\fR(\fItypePtr\fR) +ClientData +.sp +.VS +\fBTk_GetImageMasterData\fR(\fIinterp, name, typePtrPtr\fR) +.SH ARGUMENTS +.AS Tk_ImageType *typePtrPtr +.AP Tk_ImageType *typePtr in +Structure that defines the new type of image. +Must be static: a +pointer to this structure is retained by the image code. +.AP Tcl_Interp *interp in +Interpreter in which image was created. +.AP char *name in +Name of existing image. +.AP Tk_ImageType **typePtrPtr out +Points to word in which to store a pointer to type information for +the given image, if it exists. +.VE +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreateImageType\fR is invoked to define a new kind of image. +An image type corresponds to a particular value of the \fItype\fR +argument for the \fBimage create\fR command. There may exist +any number of different image types, and new types may be defined +dynamically by calling \fBTk_CreateImageType\fR. +For example, there might be one type for 2-color bitmaps, +another for multi-color images, another for dithered images, +another for video, and so on. +.PP +The code that implements a new image type is called an +\fIimage manager\fR. +It consists of a collection of procedures plus three different +kinds of data structures. +The first data structure is a Tk_ImageType structure, which contains +the name of the image type and pointers to five procedures provided +by the image manager to deal with images of this type: +.CS +typedef struct Tk_ImageType { + char *\fIname\fR; + Tk_ImageCreateProc *\fIcreateProc\fR; + Tk_ImageGetProc *\fIgetProc\fR; + Tk_ImageDisplayProc *\fIdisplayProc\fR; + Tk_ImageFreeProc *\fIfreeProc\fR; + Tk_ImageDeleteProc *\fIdeleteProc\fR; +} Tk_ImageType; +.CE +The fields of this structure will be described in later subsections +of this entry. +.PP +The second major data structure manipulated by an image manager +is called an \fIimage master\fR; it contains overall information +about a particular image, such as the values of the configuration +options specified in an \fBimage create\fR command. +There will usually be one of these structures for each +invocation of the \fBimage create\fR command. +.PP +The third data structure related to images is an \fIimage instance\fR. +There will usually be one of these structures for each usage of an +image in a particular widget. +It is possible for a single image to appear simultaneously +in multiple widgets, or even multiple times in the same widget. +Furthermore, different instances may be on different screens +or displays. +The image instance data structure describes things that may +vary from instance to instance, such as colors and graphics +contexts for redisplay. +There is usually one instance structure for each \fB\-image\fR +option specified for a widget or canvas item. +.PP +The following subsections describe the fields of a Tk_ImageType +in more detail. + +.SH NAME +.PP +\fItypePtr->name\fR provides a name for the image type. +Once \fBTk_CreateImageType\fR returns, this name may be used +in \fBimage create\fR commands to create images of the new +type. +If there already existed an image type by this name then +the new image type replaces the old one. + +.SH CREATEPROC +\fItypePtr->createProc\fR provides the address of a procedure for +Tk to call whenever \fBimage create\fR is invoked to create +an image of the new type. +\fItypePtr->createProc\fR must match the following prototype: +.CS +typedef int Tk_ImageCreateProc( + Tcl_Interp *\fIinterp\fR, + char *\fIname\fR, + int \fIargc\fR, + char **\fIargv\fR, + Tk_ImageType *\fItypePtr\fR, + Tk_ImageMaster \fImaster\fR, + ClientData *\fImasterDataPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the \fBimage\fR +command was invoked, and \fIname\fR is the name for the new image, +which was either specified explicitly in the \fBimage\fR command +or generated automatically by the \fBimage\fR command. +The \fIargc\fR and \fIargv\fR arguments describe all the configuration +options for the new image (everything after the name argument to +\fBimage\fR). +The \fImaster\fR argument is a token that refers to Tk's information +about this image; the image manager must return this token to +Tk when invoking the \fBTk_ImageChanged\fR procedure. +Typically \fIcreateProc\fR will parse \fIargc\fR and \fIargv\fR +and create an image master data structure for the new image. +\fIcreateProc\fR may store an arbitrary one-word value at +*\fImasterDataPtr\fR, which will be passed back to the +image manager when other callbacks are invoked. +Typically the value is a pointer to the master data +structure for the image. +.PP +If \fIcreateProc\fR encounters an error, it should leave an error +message in \fIinterp->result\fR and return \fBTCL_ERROR\fR; otherwise +it should return \fBTCL_OK\fR. +.PP +\fIcreateProc\fR should call \fBTk_ImageChanged\fR in order to set the +size of the image and request an initial redisplay. + +.SH GETPROC +.PP +\fItypePtr->getProc\fR is invoked by Tk whenever a widget +calls \fBTk_GetImage\fR to use a particular image. +This procedure must match the following prototype: +.CS +typedef ClientData Tk_ImageGetProc( + Tk_Window \fItkwin\fR, + ClientData \fImasterData\fR); +.CE +The \fItkwin\fR argument identifies the window in which the +image will be used and \fImasterData\fR is the value +returned by \fIcreateProc\fR when the image master was created. +\fIgetProc\fR will usually create a data structure for the new +instance, including such things as the resources needed to +display the image in the given window. +\fIgetProc\fR returns a one-word token for the instance, which +is typically the address of the instance data structure. +Tk will pass this value back to the image manager when invoking +its \fIdisplayProc\fR and \fIfreeProc\fR procedures. + +.SH DISPLAYPROC +.PP +\fItypePtr->displayProc\fR is invoked by Tk whenever an image needs +to be displayed (i.e., whenever a widget calls \fBTk_RedrawImage\fR). +\fIdisplayProc\fR must match the following prototype: +.CS +typedef void Tk_ImageDisplayProc( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR, + Drawable \fIdrawable\fR, + int \fIimageX\fR, + int \fIimageY\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIdrawableX\fR, + int \fIdrawableY\fR); +.CE +The \fIinstanceData\fR will be the same as the value returned by +\fIgetProc\fR when the instance was created. +\fIdisplay\fR and \fIdrawable\fR indicate where to display the +image; \fIdrawable\fR may be a pixmap rather than +the window specified to \fIgetProc\fR (this is usually the case, +since most widgets double-buffer their redisplay to get smoother +visual effects). +\fIimageX\fR, \fIimageY\fR, \fIwidth\fR, and \fIheight\fR +identify the region of the image that must be redisplayed. +This region will always be within the size of the image +as specified in the most recent call to \fBTk_ImageChanged\fR. +\fIdrawableX\fR and \fIdrawableY\fR indicate where in \fIdrawable\fR +the image should be displayed; \fIdisplayProc\fR should display +the given region of the image so that point (\fIimageX\fR, \fIimageY\fR) +in the image appears at (\fIdrawableX\fR, \fIdrawableY\fR) in \fIdrawable\fR. + +.SH FREEPROC +.PP +\fItypePtr->freeProc\fR contains the address of a procedure that +Tk will invoke when an image instance is released (i.e., when +\fBTk_FreeImage\fR is invoked). +This can happen, for example, when a widget is deleted or a image item +in a canvas is deleted, or when the image displayed in a widget or +canvas item is changed. +\fIfreeProc\fR must match the following prototype: +.CS +typedef void Tk_ImageFreeProc( + ClientData \fIinstanceData\fR, + Display *\fIdisplay\fR); +.CE +The \fIinstanceData\fR will be the same as the value returned by +\fIgetProc\fR when the instance was created, and \fIdisplay\fR +is the display containing the window for the instance. +\fIfreeProc\fR should release any resources associated with the +image instance, since the instance will never be used again. + +.SH DELETEPROC +.PP +\fItypePtr->deleteProc\fR is a procedure that Tk invokes when an +image is being deleted (i.e. when the \fBimage delete\fR command +is invoked). +Before invoking \fIdeleteProc\fR Tk will invoke \fIfreeProc\fR for +each of the image's instances. +\fIdeleteProc\fR must match the following prototype: +.CS +typedef void Tk_ImageDeleteProc( + ClientData \fImasterData\fR); +.CE +The \fImasterData\fR argument will be the same as the value +stored in \fI*masterDataPtr\fR by \fIcreateProc\fR when the +image was created. +\fIdeleteProc\fR should release any resources associated with +the image. + +.SH TK_GETIMAGEMASTERDATA +.VS +.PP +The procedure \fBTk_GetImageMasterData\fR may be invoked to retrieve +information about an image. For example, an image manager can use this +procedure to locate its image master data for an image. +If there exists an image named \fIname\fR +in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is +filled in with type information for the image (the \fItypePtr\fR value +passed to \fBTk_CreateImageType\fR when the image type was registered) +and the return value is the ClientData value returned by the +\fIcreateProc\fR when the image was created (this is typically a +pointer to the image master data structure). If no such image exists +then NULL is returned and NULL is stored at \fI*typePtrPtr\fR. +.VE + +.SH "SEE ALSO" +Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage + +.SH KEYWORDS +image manager, image type, instance, master diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 new file mode 100644 index 0000000..7f26dc5 --- /dev/null +++ b/doc/CrtItemType.3 @@ -0,0 +1,626 @@ +'\" +'\" Copyright (c) 1994-1995 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtItemType.3 1.7 96/02/16 10:30:28 +'\" +.so man.macros +.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateItemType\fR(\fItypePtr\fR) +.sp +Tk_ItemType * +\fBTk_GetItemTypes\fR() +.SH ARGUMENTS +.AS Tk_ItemType *typePtr +.AP Tk_ItemType *typePtr in +Structure that defines the new type of canvas item. +.BE + +.SH INTRODUCTION +.PP +\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item +described by the \fItypePtr\fR argument. +An item type corresponds to a particular value of the \fItype\fR +argument to the \fBcreate\fR widget command for canvases, and +the code that implements a canvas item type is called a \fItype manager\fR. +Tk defines several built-in item types, such as \fBrectangle\fR +and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR +allows additional item types to be defined. +Once \fBTk_CreateItemType\fR returns, the new item type may be used +in new or existing canvas widgets just like the built-in item +types. +.PP +\fBTk_GetItemTypes\fR returns a pointer to the first in the list +of all item types currently defined for canvases. +The entries in the list are linked together through their +\fInextPtr\fR fields, with the end of the list marked by a +NULL \fInextPtr\fR. +.PP +You may find it easier to understand the rest of this manual entry +by looking at the code for an existing canvas item type such as +bitmap (file tkCanvBmap.c) or text (tkCanvText.c). +The easiest way to create a new type manager is to copy the code +for an existing type and modify it for the new type. +.PP +Tk provides a number of utility procedures for the use of canvas +type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; +these are described in separate manual entries. + +.SH "DATA STRUCTURES" +.PP +A type manager consists of a collection of procedures that provide a +standard set of operations on items of that type. +The type manager deals with three kinds of data +structures. +The first data structure is a Tk_ItemType; it contains +information such as the name of the type and pointers to +the standard procedures implemented by the type manager: +.CS +typedef struct Tk_ItemType { + char *\fIname\fR; + int \fIitemSize\fR; + Tk_ItemCreateProc *\fIcreateProc\fR; + Tk_ConfigSpec *\fIconfigSpecs\fR; + Tk_ItemConfigureProc *\fIconfigProc\fR; + Tk_ItemCoordProc *\fIcoordProc\fR; + Tk_ItemDeleteProc *\fIdeleteProc\fR; + Tk_ItemDisplayProc *\fIdisplayProc\fR; + int \fIalwaysRedraw\fR; + Tk_ItemPointProc *\fIpointProc\fR; + Tk_ItemAreaProc *\fIareaProc\fR; + Tk_ItemPostscriptProc *\fIpostscriptProc\fR; + Tk_ItemScaleProc *\fIscaleProc\fR; + Tk_ItemTranslateProc *\fItranslateProc\fR; + Tk_ItemIndexProc *\fIindexProc\fR; + Tk_ItemCursorProc *\fIicursorProc\fR; + Tk_ItemSelectionProc *\fIselectionProc\fR; + Tk_ItemInsertProc *\fIinsertProc\fR; + Tk_ItemDCharsProc *\fIdCharsProc\fR; + Tk_ItemType *\fInextPtr\fR; +} Tk_ItemType; +.CE +.PP +The fields of a Tk_ItemType structure are described in more detail +later in this manual entry. +When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR +argument must point to a structure with all of the fields initialized +except \fInextPtr\fR, which Tk sets to link all the types together +into a list. +The structure must be in permanent memory (either statically +allocated or dynamically allocated but never freed); Tk retains +a pointer to this structure. +.PP +The second data structure manipulated by a type manager is an +\fIitem record\fR. +For each item in a canvas there exists one item record. +All of the items of a given type generally have item records with +the same structure, but different types usually have different +formats for their item records. +The first part of each item record is a header with a standard structure +defined by Tk via the type Tk_Item; the rest of the item +record is defined by the type manager. +A type manager must define its item records with a Tk_Item as +the first field. +For example, the item record for bitmap items is defined as follows: +.CS +typedef struct BitmapItem { + Tk_Item \fIheader\fR; + double \fIx\fR, \fIy\fR; + Tk_Anchor \fIanchor\fR; + Pixmap \fIbitmap\fR; + XColor *\fIfgColor\fR; + XColor *\fIbgColor\fR; + GC \fIgc\fR; +} BitmapItem; +.CE +The \fIheader\fR substructure contains information used by Tk +to manage the item, such as its identifier, its tags, its type, +and its bounding box. +The fields starting with \fIx\fR belong to the type manager: +Tk will never read or write them. +The type manager should not need to read or write any of the +fields in the header except for four fields +whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. +These fields give a bounding box for the items using integer +canvas coordinates: the item should not cover any pixels +with x-coordinate lower than \fIx1\fR or y-coordinate +lower than \fIy1\fR, nor should it cover any pixels with +x-coordinate greater than or equal to \fIx2\fR or y-coordinate +greater than or equal to \fIy2\fR. +It is up to the type manager to keep the bounding box up to +date as the item is moved and reconfigured. +.PP +Whenever Tk calls a procedure in a type manager it passes in a pointer +to an item record. +The argument is always passed as a pointer to a Tk_Item; the type +manager will typically cast this into a pointer to its own specific +type, such as BitmapItem. +.PP +The third data structure used by type managers has type +Tk_Canvas; it serves as an opaque handle for the canvas widget +as a whole. +Type managers need not know anything about the contents of this +structure. +A Tk_Canvas handle is typically passed in to the +procedures of a type manager, and the type manager can pass the +handle back to library procedures such as Tk_CanvasTkwin +to fetch information about the canvas. + +.SH NAME +.PP +This section and the ones that follow describe each of the fields +in a Tk_ItemType structure in detail. +The \fIname\fR field provides a string name for the item type. +Once \fBTk_CreateImageType\fR returns, this name may be used +in \fBcreate\fR widget commands to create items of the new +type. +If there already existed an item type by this name then +the new item type replaces the old one. + +.SH ITEMSIZE +\fItypePtr->itemSize\fR gives the size in bytes of item records +of this type, including the Tk_Item header. +Tk uses this size to allocate memory space for items of the type. +All of the item records for a given type must have the same size. +If variable length fields are needed for an item (such as a list +of points for a polygon), the type manager can allocate a separate +object of variable length and keep a pointer to it in the item record. + +.SH CREATEPROC +.PP +\fItypePtr->createProc\fR points to a procedure for +Tk to call whenever a new item of this type is created. +\fItypePtr->createProc\fR must match the following prototype: +.CS +typedef int Tk_ItemCreateProc( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIargc\fR, + char **\fIargv\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the canvas's +\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a +handle for the canvas widget. +\fIitemPtr\fR is a pointer to a newly-allocated item of +size \fItypePtr->itemSize\fR. +Tk has already initialized the item's header (the first +\fBsizeof(Tk_ItemType)\fR bytes). +The \fIargc\fR and \fIargv\fR arguments describe all of the +arguments to the \fBcreate\fR command after the \fItype\fR +argument. +For example, in the widget command +.CS +\fB\&.c create rectangle 10 20 50 50 \-fill black\fR +.CE +\fIargc\fR will be \fB6\fR and \fIargv\fR[0] will contain the +string \fB10\fR. +.PP +\fIcreateProc\fR should use \fIargc\fR and \fIargv\fR to initialize +the type-specific parts of the item record and set an initial value +for the bounding box in the item's header. +It should return a standard Tcl completion code and leave an +error message in \fIinterp->result\fR if an error occurs. +If an error occurs Tk will free the item record, so \fIcreateProc\fR +must be sure to leave the item record in a clean state if it returns an error +(e.g., it must free any additional memory that it allocated for +the item). + +.SH CONFIGSPECS +.PP +Each type manager must provide a standard table describing its +configuration options, in a form suitable for use with +\fBTk_ConfigureWidget\fR. +This table will normally be used by \fItypePtr->createProc\fR +and \fItypePtr->configProc\fR, but Tk also uses it directly +to retrieve option information in the \fBitemcget\fR and +\fBitemconfigure\fR widget commands. +\fItypePtr->configSpecs\fR must point to the configuration table +for this type. +Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR +for implementing the \fB\-tags\fR option; see an existing type +manager for an example of how to use it in \fIconfigSpecs\fR. + +.SH CONFIGPROC +.PP +\fItypePtr->configProc\fR is called by Tk whenever the +\fBitemconfigure\fR widget command is invoked to change the +configuration options for a canvas item. +This procedure must match the following prototype: +.CS +typedef int Tk_ItemConfigureProc( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIargc\fR, + char **\fIargv\fR, + int \fIflags\fR); +.CE +The \fIinterp\fR argument identifies the interpreter in which the +widget command was invoked, \fIcanvas\fR is a handle for the canvas +widget, and \fIitemPtr\fR is a pointer to the item being configured. +\fIargc\fR and \fIargv\fR contain the configuration options. For +example, if the following command is invoked: +.CS +\fB\&.c itemconfigure 2 \-fill red \-outline black\fR +.CE +\fIargc\fR is \fB4\fR and \fIargv\fR contains the strings \fB\-fill\fR +through \fBblack\fR. +\fIargc\fR will always be an even value. +The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; +currently this value is always TK_CONFIG_ARGV_ONLY when Tk +invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR +procedure will usually invoke \fIconfigProc\fR with different flag values. +.PP +\fItypePtr->configProc\fR returns a standard Tcl completion code and +leaves an error message in \fIinterp->result\fR if an error occurs. +It must update the item's bounding box to reflect the new configuration +options. + +.SH COORDPROC +.PP +\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR +widget command for an item. +It must match the following prototype: +.CS +typedef int Tk_ItemCoordProc( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIargc\fR, + char **\fIargv\fR); +.CE +The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR +all have the standard meanings, and \fIargc\fR and \fIargv\fR +describe the coordinate arguments. +For example, if the following widget command is invoked: +.CS +\fB\&.c coords 2 30 90\fR +.CE +\fIargc\fR will be \fB2\fR and \fBargv\fR will contain the string values +\fB30\fR and \fB90\fR. +.PP +The \fIcoordProc\fR procedure should process the new coordinates, +update the item appropriately (e.g., it must reset the bounding +box in the item's header), and return a standard Tcl completion +code. +If an error occurs, \fIcoordProc\fR must leave an error message in +\fIinterp->result\fR. + +.SH DELETEPROC +.PP +\fItypePtr->deleteProc\fR is invoked by Tk to delete an item +and free any resources allocated to it. +It must match the following prototype: +.CS +typedef void Tk_ItemDeleteProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR); +.CE +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual +interpretations, and \fIdisplay\fR identifies the X display containing +the canvas. +\fIdeleteProc\fR must free up any resources allocated for the item, +so that Tk can free the item record. +\fIdeleteProc\fR should not actually free the item record; this will +be done by Tk when \fIdeleteProc\fR returns. + +.SH "DISPLAYPROC AND ALWAYSREDRAW" +.PP +\fItypePtr->displayProc\fR is invoked by Tk to redraw an item +on the screen. +It must match the following prototype: +.CS +typedef void Tk_ItemDisplayProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + Display *\fIdisplay\fR, + Drawable \fIdst\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR); +.CE +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. +\fIdisplay\fR identifies the display containing the canvas, and +\fIdst\fR specifies a drawable in which the item should be rendered; +typically this is an off-screen pixmap, which Tk will copy into +the canvas's window once all relevant items have been drawn. +\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular +region in canvas coordinates, which is the area to be redrawn; +only information that overlaps this area needs to be redrawn. +Tk will not call \fIdisplayProc\fR unless the item's bounding box +overlaps the redraw area, but the type manager may wish to use +the redraw area to optimize the redisplay of the item. +.PP +Because of scrolling and the use of off-screen pixmaps for +double-buffered redisplay, the item's coordinates in \fIdst\fR +will not necessarily be the same as those in the canvas. +\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR +to transform coordinates from those of the canvas to those +of \fIdst\fR. +.PP +Normally an item's \fIdisplayProc\fR is only invoked if the item +overlaps the area being displayed. +However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then +\fIdisplayProc\fR is invoked during every redisplay operation, +even if the item doesn't overlap the area of redisplay. +\fIalwaysRedraw\fR should normally be set to 0; it is only +set to 1 in special cases such as window items that need to be +unmapped when they are off-screen. + +.SH POINTPROC +.PP +\fItypePtr->pointProc\fR is invoked by Tk to find out how close +a given point is to a canvas item. +Tk uses this procedure for purposes such as locating the item +under the mouse or finding the closest item to a given point. +The procedure must match the following prototype: +.CS +typedef double Tk_ItemPointProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIpointPtr\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. +\fIpointPtr\fR points to an array of two numbers giving +the x and y coordinates of a point. +\fIpointProc\fR must return a real value giving the distance +from the point to the item, or 0 if the point lies inside +the item. + +.SH AREAPROC +.PP +\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship +between an item and a rectangular area. +It must match the following prototype: +.CS +typedef int Tk_ItemAreaProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double *\fIrectPtr\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meaning. +\fIrectPtr\fR points to an array of four real numbers; +the first two give the x and y coordinates of the upper left +corner of a rectangle, and the second two give the x and y +coordinates of the lower right corner. +\fIareaProc\fR must return \-1 if the item lies entirely outside +the given area, 0 if it lies partially inside and partially +outside the area, and 1 if it lies entirely inside the area. + +.SH POSTSCRIPTPROC +.PP +\fItypePtr->postscriptProc\fR is invoked by Tk to generate +Postcript for an item during the \fBpostscript\fR widget command. +If the type manager is not capable of generating Postscript then +\fItypePtr->postscriptProc\fR should be NULL. +The procedure must match the following prototype: +.CS +typedef int Tk_ItemPostscriptProc( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIprepass\fR); +.CE +The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have +standard meanings; \fIprepass\fR will be described below. +If \fIpostscriptProc\fR completes successfully, it should append +Postscript for the item to the information in \fIinterp->result\fR +(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) +and return TCL_OK. +If an error occurs, \fIpostscriptProc\fR should clear the result +and replace its contents with an error message; then it should +return TCL_ERROR. +.PP +Tk provides a collection of utility procedures to simplify +\fIpostscriptProc\fR. +For example, \fBTk_CanvasPsColor\fR will generate Postscript to set +the current color to a given Tk color and \fBTk_CanvasPsFont\fR will +set up font information. +When generating Postscript, the type manager is free to change the +graphics state of the Postscript interpreter, since Tk places +\fBgsave\fR and \fBgrestore\fR commands around the Postscript for +the item. +The type manager can use canvas x coordinates directly in its Postscript, +but it must call \fBTk_CanvasPsY\fR to convert y coordinates from +the space of the canvas (where the origin is at the +upper left) to the space of Postscript (where the origin is at the +lower left). +.PP +In order to generate Postscript that complies with the Adobe Document +Structuring Conventions, Tk actually generates Postscript in two passes. +It calls each item's \fIpostscriptProc\fR in each pass. +The only purpose of the first pass is to collect font information +(which is done by \fBTk_CanvPsFont\fR); the actual Postscript is +discarded. +Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 +during the first pass; the type manager can use \fIprepass\fR to skip +all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. +During the second pass \fIprepass\fR will be 0, so the type manager +must generate complete Postscript. + +.SH SCALEPROC +\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item +during the \fBscale\fR widget command. +The procedure must match the following prototype: +.CS +typedef void Tk_ItemScaleProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIoriginX\fR, + double \fIoriginY\fR, + double \fIscaleX\fR, + double \fIscaleY\fR); +.CE +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. +\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which +the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the +x and y scale factors. +The item should adjust its coordinates so that a point in the item +that used to have coordinates \fIx\fR and \fIy\fR will have new +coordinates \fIx'\fR and \fIy'\fR, where +.CS +\fIx' = originX + scaleX*(x-originX) +y' = originY + scaleY*(y-originY)\fR +.CE +\fIscaleProc\fR must also update the bounding box in the item's +header. + +.SH TRANSLATEPROC +\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item +during the \fBmove\fR widget command. +The procedure must match the following prototype: +.CS +typedef void Tk_ItemTranslateProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + double \fIdeltaX\fR, + double \fIdeltaY\fR); +.CE +The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, +and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be +added to each x and y coordinate within the item. +The type manager should adjust the item's coordinates and +update the bounding box in the item's header. + +.SH INDEXPROC +\fItypePtr->indexProc\fR is invoked by Tk to translate a string +index specification into a numerical index, for example during the +\fBindex\fR widget command. +It is only relevant for item types that support indexable text; +\fItypePtr->indexProc\fR may be specified as NULL for non-textual +item types. +The procedure must match the following prototype: +.CS +typedef int Tk_ItemIndexProc( + Tcl_Interp *\fIinterp\fR, + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + char \fIindexString\fR, + int *\fIindexPtr\fR); +.CE +The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all +have the usual meaning. +\fIindexString\fR contains a textual description of an index, +and \fIindexPtr\fR points to an integer value that should be +filled in with a numerical index. +It is up to the type manager to decide what forms of index +are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, +\fBend\fR, etc.). +\fIindexProc\fR should return a Tcl completion code and set +\fIinterp->result\fR in the event of an error. + +.SH ICURSORPROC +.PP +\fItypePtr->icursorProc\fR is invoked by Tk during +the \fBicursor\fR widget command to set the position of the +insertion cursor in a textual item. +It is only relevant for item types that support an insertion cursor; +\fItypePtr->icursorProc\fR may be specified as NULL for item types +that don't support an insertion cursor. +The procedure must match the following prototype: +.CS +typedef void Tk_ItemIndexProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and +\fIindex\fR is an index into the item's text, as returned by a +previous call to \fItypePtr->insertProc\fR. +The type manager should position the insertion cursor in the +item just before the character given by \fIindex\fR. +Whether or not to actually display the insertion cursor is +determined by other information provided by \fBTk_CanvasGetTextInfo\fR. + +.SH SELECTIONPROC +.PP +\fItypePtr->selectionProc\fR is invoked by Tk during selection +retrievals; it must return part or all of the selected text in +the item (if any). +It is only relevant for item types that support text; +\fItypePtr->selectionProc\fR may be specified as NULL for non-textual +item types. +The procedure must match the following prototype: +.CS +typedef int Tk_ItemSelectionProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIoffset\fR is an offset in bytes into the selection where 0 refers +to the first byte of the selection; it identifies +the first character that is to be returned in this call. +\fIbuffer\fR points to an area of memory in which to store the +requested bytes, and \fImaxBytes\fR specifies the maximum number +of bytes to return. +\fIselectionProc\fR should extract up to \fImaxBytes\fR characters +from the selection and copy them to \fImaxBytes\fR; it should +return a count of the number of bytes actually copied, which may +be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes +in the selection. + +.SH INSERTPROC +.PP +\fItypePtr->insertProc\fR is invoked by Tk during +the \fBinsert\fR widget command to insert new text into a +canvas item. +It is only relevant for item types that support text; +\fItypePtr->insertProc\fR may be specified as NULL for non-textual +item types. +The procedure must match the following prototype: +.CS +typedef void Tk_ItemInsertProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIindex\fR, + char *\fIstring\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIindex\fR is an index into the item's text, as returned by a +previous call to \fItypePtr->insertProc\fR, and \fIstring\fR +contains new text to insert just before the character given +by \fIindex\fR. +The type manager should insert the text and recompute the bounding +box in the item's header. + +.SH DCHARSPROC +.PP +\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR +widget command to delete a range of text from a canvas item. +It is only relevant for item types that support text; +\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual +item types. +The procedure must match the following prototype: +.CS +typedef void Tk_ItemDCharsProc( + Tk_Canvas \fIcanvas\fR, + Tk_Item *\fIitemPtr\fR, + int \fIfirst\fR, + int \fIlast\fR); +.CE +\fIcanvas\fR and \fIitemPtr\fR have the usual meanings. +\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes +to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR. +The type manager should delete the specified characters and update +the bounding box in the item's header. + +.SH "SEE ALSO" +Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin + +.SH KEYWORDS +canvas, focus, item type, selection, type manager diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 new file mode 100644 index 0000000..747b631 --- /dev/null +++ b/doc/CrtPhImgFmt.3 @@ -0,0 +1,235 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +'\" SCCS: @(#) CrtPhImgFmt.3 1.10 97/10/31 12:58:54 +'\" +.so man.macros +.TH Tk_CreatePhotoImageFormat 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreatePhotoImageFormat \- define new file format for photo images +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +\fB#include <tkPhoto.h>\fR +.sp +\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) +.SH ARGUMENTS +.AS Tk_PhotoImageFormat *formatPtr +.AP Tk_PhotoImageFormat *formatPtr in +Structure that defines the new file format. +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format +for image data for use with photo images. The code that implements an +image file format is called an image file format handler, or +handler for short. The photo image code +maintains a list of handlers that can be used to read and +write data to or from a file. Some handlers may also +support reading image data from a string or converting image data to a +string format. +The user can specify which handler to use with the \fB\-format\fR +image configuration option or the \fB\-format\fR option to the +\fBread\fR and \fBwrite\fR photo image subcommands. +.PP +An image file format handler consists of a collection of procedures +plus a Tk_PhotoImageFormat structure, which contains the name of the +image file format and pointers to six procedures provided by the +handler to deal with files and strings in this format. The +Tk_PhotoImageFormat structure contains the following fields: +.CS +typedef struct Tk_PhotoImageFormat { + char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; +} Tk_PhotoImageFormat; +.CE +.PP +The handler need not provide implementations of all six procedures. +For example, the procedures that handle string data would not be +provided for a format in which the image data are stored in binary, +and could therefore contain null characters. If any procedure is not +implemented, the corresponding pointer in the Tk_PhotoImageFormat +structure should be set to NULL. The handler must provide the +\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR +procedure, and the \fIstringMatchProc\fR procedure if it provides the +\fIstringReadProc\fR procedure. + +.SH NAME +.PP +\fIformatPtr->name\fR provides a name for the image type. +Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used +in the \fB\-format\fR photo image configuration and subcommand option. +The manual page for the photo image (photo(n)) describes how image +file formats are chosen based on their names and the value given to +the \fB\-format\fR option. + +.SH FILEMATCHPROC +\fIformatPtr->fileMatchProc\fR provides the address of a procedure for +Tk to call when it is searching for an image file format handler +suitable for reading data in a given file. +\fIformatPtr->fileMatchProc\fR must match the following prototype: +.CS +typedef int Tk_ImageFileMatchProc( + Tcl_Channel \fIchan\fR, + char *\fIfileName\fR, + char *\fIformatString\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR); +.CE +The \fIfileName\fR argument is the name of the file containing the +image data, which is open for reading as \fIchan\fR. The +\fIformatString\fR argument contains the value given for the +\fB\-format\fR option, or NULL if the option was not specified. +If the data in the file appears to be in the format supported by this +handler, the \fIformatPtr->fileMatchProc\fR procedure should store the +width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR +respectively, and return 1. Otherwise it should return 0. + +.SH STRINGMATCHPROC +\fIformatPtr->stringMatchProc\fR provides the address of a procedure for +Tk to call when it is searching for an image file format handler for +suitable for reading data from a given string. +\fIformatPtr->stringMatchProc\fR must match the following prototype: +.CS +typedef int Tk_ImageStringMatchProc( + char *\fIstring\fR, + char *\fIformatString\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR); +.CE +The \fIstring\fR argument points to the string containing the image +data. The \fIformatString\fR argument contains the value given for +the \fB\-format\fR option, or NULL if the option was not specified. +If the data in the string appears to be in the format supported by +this handler, the \fIformatPtr->stringMatchProc\fR procedure should +store the width and height of the image in *\fIwidthPtr\fR and +*\fIheightPtr\fR respectively, and return 1. Otherwise it should +return 0. + +.SH FILEREADPROC +\fIformatPtr->fileReadProc\fR provides the address of a procedure for +Tk to call to read data from an image file into a photo image. +\fIformatPtr->fileReadProc\fR must match the following prototype: +.CS +typedef int Tk_ImageFileReadProc( + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + char *\fIfileName\fR, + char *\fIformatString\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to read the image; it should be used for reporting errors. +The image data is in the file named \fIfileName\fR, which is open for +reading as \fIchan\fR. The \fIformatString\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The image data in the file, or a subimage of it, is to +be read into the photo image identified by the handle +\fIimageHandle\fR. The subimage of the data in the file is of +dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at +coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo +image with its top-left corner at coordinates +(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +The return value is a standard Tcl return value. + +.SH STRINGREADPROC +\fIformatPtr->stringReadProc\fR provides the address of a procedure for +Tk to call to read data from a string into a photo image. +\fIformatPtr->stringReadProc\fR must match the following prototype: +.CS +typedef int Tk_ImageStringReadProc( + Tcl_Interp *\fIinterp\fR, + char *\fIstring\fR, + char *\fIformatString\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to read the image; it should be used for reporting errors. +The \fIstring\fR argument points to the image data in string form. +The \fIformatString\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The image data in the string, or a subimage of it, is to +be read into the photo image identified by the handle +\fIimageHandle\fR. The subimage of the data in the string is of +dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at +coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo +image with its top-left corner at coordinates +(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +The return value is a standard Tcl return value. + +.SH FILEWRITEPROC +\fIformatPtr->fileWriteProc\fR provides the address of a procedure for +Tk to call to write data from a photo image to a file. +\fIformatPtr->fileWriteProc\fR must match the following prototype: +.CS +typedef int Tk_ImageFileWriteProc( + Tcl_Interp *\fIinterp\fR, + char *\fIfileName\fR, + char *\fIformatString\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to write the image; it should be used for reporting errors. +The image data to be written are in memory and are described by the +Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the +manual page FindPhoto(3) for details. The \fIfileName\fR argument +points to the string giving the name of the file in which to write the +image data. The \fIformatString\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The format string can contain extra characters +after the name of the format. If appropriate, the +\fIformatPtr->fileWriteProc\fR procedure may interpret these +characters to specify further details about the image file. +The return value is a standard Tcl return value. + +.SH STRINGWRITEPROC +\fIformatPtr->stringWriteProc\fR provides the address of a procedure for +Tk to call to translate image data from a photo image into a string. +\fIformatPtr->stringWriteProc\fR must match the following prototype: +.CS +typedef int Tk_ImageStringWriteProc( + Tcl_Interp *\fIinterp\fR, + Tcl_DString *\fIdataPtr\fR, + char *\fIformatString\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter in which the command was +invoked to convert the image; it should be used for reporting errors. +The image data to be converted are in memory and are described by the +Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the +manual page FindPhoto(3) for details. The data for the string +should be appended to the dynamic string given by \fIdataPtr\fR. +The \fIformatString\fR argument contains the +value given for the \fB\-format\fR option, or NULL if the option was +not specified. The format string can contain extra characters +after the name of the format. If appropriate, the +\fIformatPtr->stringWriteProc\fR procedure may interpret these +characters to specify further details about the image file. +The return value is a standard Tcl return value. + +.SH "SEE ALSO" +Tk_FindPhoto, Tk_PhotoPutBlock + +.SH KEYWORDS +photo image, image file diff --git a/doc/CrtSelHdlr.3 b/doc/CrtSelHdlr.3 new file mode 100644 index 0000000..96cddca --- /dev/null +++ b/doc/CrtSelHdlr.3 @@ -0,0 +1,120 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CrtSelHdlr.3 1.18 96/08/27 13:21:21 +'\" +.so man.macros +.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR) +.sp +\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR) +.SH ARGUMENTS +.AS Tk_SelectionProc clientData +.AP Tk_Window tkwin in +Window for which \fIproc\fR will provide selection information. +.AP Atom selection in +The name of the selection for which \fIproc\fR will provide +selection information. +.AP Atom target in +Form in which \fIproc\fR can provide the selection (e.g. STRING +or FILE_NAME). Corresponds to \fItype\fR arguments in \fBselection\fR +commands. +.AP Tk_SelectionProc *proc in +Procedure to invoke whenever the selection is owned by \fItkwin\fR +and the selection contents are requested in the format given by +\fItarget\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.AP Atom format in +If the selection requestor isn't in this process, \fIformat\fR determines +the representation used to transmit the selection to its +requestor. +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreateSelHandler\fR arranges for a particular procedure +(\fIproc\fR) to be called whenever \fIselection\fR is owned by +\fItkwin\fR and the selection contents are requested in the +form given by \fItarget\fR. +\fITarget\fR should be one of +the entries defined in the left column of Table 2 of the +X Inter-Client Communication Conventions Manual (ICCCM) or +any other form in which an application is willing to present +the selection. The most common form is STRING. +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_SelectionProc\fR: +.CS +typedef int Tk_SelectionProc( + ClientData \fIclientData\fR, + int \fIoffset\fR, + char *\fIbuffer\fR, + int \fImaxBytes\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the +\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR. +Typically, \fIclientData\fR points to a data +structure containing application-specific information that is +needed to retrieve the selection. \fIOffset\fR specifies an +offset position into the selection, \fIbuffer\fR specifies a +location at which to copy information about the selection, and +\fImaxBytes\fR specifies the amount of space available at +\fIbuffer\fR. \fIProc\fR should place a NULL-terminated string +at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters +(not including the terminating NULL), and it should return a +count of the number of non-NULL characters stored at +\fIbuffer\fR. If the selection no longer exists (e.g. it once +existed but the user deleted the range of characters containing +it), then \fIproc\fR should return -1. +.PP +When transferring large selections, Tk will break them up into +smaller pieces (typically a few thousand bytes each) for more +efficient transmission. It will do this by calling \fIproc\fR +one or more times, using successively higher values of \fIoffset\fR +to retrieve successive portions of the selection. If \fIproc\fR +returns a count less than \fImaxBytes\fR it means that the entire +remainder of the selection has been returned. If \fIproc\fR's return +value is \fImaxBytes\fR it means there may be additional information +in the selection, so Tk must make another call to \fIproc\fR to +retrieve the next portion. +.PP +\fIProc\fR always returns selection information in the form of a +character string. However, the ICCCM allows for information to +be transmitted from the selection owner to the selection requestor +in any of several formats, such as a string, an array of atoms, an +array of integers, etc. The \fIformat\fR argument to +\fBTk_CreateSelHandler\fR indicates what format should be used to +transmit the selection to its requestor (see the middle column of +Table 2 of the ICCCM for examples). If \fIformat\fR is not +STRING, then Tk will take the value returned by \fIproc\fR and divided +it into fields separated by white space. If \fIformat\fR is ATOM, +then Tk will return the selection as an array of atoms, with each +field in \fIproc\fR's result treated as the name of one atom. For +any other value of \fIformat\fR, Tk will return the selection as an +array of 32-bit values where each field of \fIproc\fR's result is +treated as a number and translated to a 32-bit value. In any event, +the \fIformat\fR atom is returned to the selection requestor along +with the contents of the selection. +.PP +If \fBTk_CreateSelHandler\fR is called when there already exists a +handler for \fIselection\fR and \fItarget\fR on \fItkwin\fR, then the +existing handler is replaced with a new one. +.PP +\fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR, +\fIselection\fR, and \fItarget\fR, if such a handler exists. +If there is no such handler then it has no effect. + +.SH KEYWORDS +format, handler, selection, target diff --git a/doc/CrtWindow.3 b/doc/CrtWindow.3 new file mode 100644 index 0000000..7799ed0 --- /dev/null +++ b/doc/CrtWindow.3 @@ -0,0 +1,142 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" @(#) CrtWindow.c 1.21 96/11/01 09:42:20 +'\" +.so man.macros +.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR) +.sp +Tk_Window +\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) +.sp +\fBTk_DestroyWindow\fR(\fItkwin\fR) +.sp +\fBTk_MakeWindowExist\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tcl_Interp *topLevScreen +.AP Tcl_Interp *interp out +Tcl interpreter to use for error reporting. If no error occurs, +then \fI*interp\fR isn't modified. +.AP Tk_Window parent in +Token for the window that is to serve as the logical parent of +the new window. +.AP char *name in +Name to use for this window. Must be unique among all children of +the same \fIparent\fR. +.AP char *topLevScreen in +Has same format as \fIscreenName\fR. If NULL, then new window is +created as an internal window. If non-NULL, new window is created as +a top-level window on screen \fItopLevScreen\fR. If \fItopLevScreen\fR +is an empty string (``'') then new +window is created as top-level window of \fIparent\fR's screen. +.AP Tk_Window tkwin in +Token for window. +.AP char *pathName in +Name of new window, specified as path name within application +(e.g. \fB.a.b.c\fR). +.BE + +.SH DESCRIPTION +.PP +The procedures \fBTk_CreateWindow\fR +.VS +and \fBTk_CreateWindowFromPath\fR +are used to create new windows for +use in Tk-based applications. Each of the procedures returns a token +that can be used to manipulate the window in other calls to the Tk +library. If the window couldn't be created successfully, then NULL +is returned and \fIinterp->result\fR is modified to hold an error +message. +.PP +Tk supports two different kinds of windows: internal +windows and top-level windows. +.VE +An internal window is an interior window of a Tk application, such as a +scrollbar or menu bar or button. A top-level window is one that is +created as a child of a screen's root window, rather than as an +interior window, but which is logically part of some existing main +window. Examples of top-level windows are pop-up menus and dialog boxes. +.PP +New windows may be created by calling +\fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is +NULL, then the new window will be an internal window. If +\fItopLevScreen\fR is non-NULL, then the new window will be a +top-level window: \fItopLevScreen\fR indicates the name of +a screen and the new window will be created as a child of the +root window of \fItopLevScreen\fR. In either case Tk will +consider the new window to be the logical child of \fIparent\fR: +the new window's path name will reflect this fact, options may +be specified for the new window under this assumption, and so on. +The only difference is that new X window for a top-level window +will not be a child of \fIparent\fR's X window. For example, a pull-down +menu's \fIparent\fR would be the button-like window used to invoke it, +which would in turn be a child of the menu bar window. A dialog box might +have the application's main window as its parent. +.PP +\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying +new windows. In \fBTk_CreateWindowFromPath\fR the new +window is specified with a token for any window in the target +application (\fItkwin\fR), plus a path name for the new window. +It produces the same effect as \fBTk_CreateWindow\fR and allows +both top-level and internal windows to be created, depending on +the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR, +as in calls to \fBTk_CreateWindow\fR, the parent of the new window +must exist at the time of the call, but the new window must not +already exist. +.PP +The window creation procedures don't +actually issue the command to X to create a window. +Instead, they create a local data structure associated with +the window and defer the creation of the X window. +The window will actually be created by the first call to +\fBTk_MapWindow\fR. Deferred window creation allows various +aspects of the window (such as its size, background color, +etc.) to be modified after its creation without incurring +any overhead in the X server. When the window is finally +mapped all of the window attributes can be set while creating +the window. +.PP +The value returned by a window-creation procedure is not the +X token for the window (it can't be, since X hasn't been +asked to create the window yet). Instead, it is a token +for Tk's local data structure for the window. Most +of the Tk library procedures take Tk_Window tokens, rather +than X identifiers. The actual +X window identifier can be retrieved from the local +data structure using the \fBTk_WindowId\fR macro; see +the manual entry for \fBTk_WindowId\fR for details. +.PP +\fBTk_DestroyWindow\fR deletes a window and all the data +structures associated with it, including any event handlers +created with \fBTk_CreateEventHandler\fR. In addition, +\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR +recursively (where children are defined in the Tk sense, consisting +of all windows that were created with the given window as \fIparent\fR). +If \fItkwin\fR was created by \fBTk_CreateInternalWindow\fR then event +handlers interested in destroy events +are invoked immediately. If \fItkwin\fR is a top-level or main window, +then the event handlers will be invoked later, after X has seen +the request and returned an event for it. +.PP +If a window has been created +but hasn't been mapped, so no X window exists, it is +possible to force the creation of the X window by +calling \fBTk_MakeWindowExist\fR. This procedure issues +the X commands to instantiate the window given by \fItkwin\fR. + +.SH KEYWORDS +create, deferred creation, destroy, display, internal window, +screen, top-level window, window diff --git a/doc/DeleteImg.3 b/doc/DeleteImg.3 new file mode 100644 index 0000000..88b2d23 --- /dev/null +++ b/doc/DeleteImg.3 @@ -0,0 +1,35 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) DeleteImg.3 1.4 96/03/26 18:07:21 +'\" +.so man.macros +.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_DeleteImage \- Destroy an image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_DeleteImage\fR(\fIinterp, name\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Interpreter for which the image was created. +.AP char *name in +Name of the image. +.BE + +.SH DESCRIPTION +.PP +\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR +and \fIname\fR, if there is one. All instances of that image +will redisplay as empty regions. If the given image does not +exist then the procedure has no effect. + +.SH KEYWORDS +delete image, image manager diff --git a/doc/DrawFocHlt.3 b/doc/DrawFocHlt.3 new file mode 100644 index 0000000..dfcc810 --- /dev/null +++ b/doc/DrawFocHlt.3 @@ -0,0 +1,40 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) DrawFocHlt.3 1.4 96/03/26 18:07:35 +'\" +.so man.macros +.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GetPixels(\fItkwin, gc, width, drawable\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tk_Window tkwin in +Window for which the highlight is being drawn. Used to retrieve +the window's dimensions, among other things. +.AP GC gc in +Graphics context to use for drawing the highlight. +.AP int width in +Width of the highlight ring, in pixels. +.AP Drawable drawable in +Drawable in which to draw the highlight; usually an offscreen +pixmap for double buffering. +.BE + +.SH DESCRIPTION +.PP +\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the +traversal highlight ring for a widget. +It is typically invoked by widgets during redisplay. + +.SH KEYWORDS +focus, traversal highlight diff --git a/doc/EventHndlr.3 b/doc/EventHndlr.3 new file mode 100644 index 0000000..c9222b4 --- /dev/null +++ b/doc/EventHndlr.3 @@ -0,0 +1,79 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) EventHndlr.3 1.15 96/03/14 10:55:08 +'\" +.so man.macros +.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) +.sp +\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) +.SH ARGUMENTS +.AS "unsigned long" clientData +.AP Tk_Window tkwin in +Token for window in which events may occur. +.AP "unsigned long" mask in +Bit-mask of events (such as \fBButtonPressMask\fR) +for which \fIproc\fR should be called. +.AP Tk_EventProc *proc in +Procedure to invoke whenever an event in \fImask\fR occurs +in the window given by \fItkwin\fR. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be +invoked in the future whenever one of the event types specified +by \fImask\fR occurs in the window specified by \fItkwin\fR. +The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; +this mechanism only works in programs that dispatch events +through \fBTk_HandleEvent\fR (or through other Tk procedures that +call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or +\fBTk_MainLoop\fR). +.PP +\fIProc\fR should have arguments and result that match the +type \fBTk_EventProc\fR: +.CS +typedef void Tk_EventProc( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR +argument given to \fBTk_CreateEventHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +the window in which the event occurred. \fIEventPtr\fR is +a pointer to the X event, which will be one of the ones +specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR. +.PP +\fBTk_DeleteEventHandler\fR may be called to delete a +previously-created event handler: it deletes the first handler +it finds that is associated with \fItkwin\fR and matches the +\fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. If +no such handler exists, then \fBTk_EventHandler\fR returns +without doing anything. Although Tk supports it, it's probably +a bad idea to have more than one callback with the same \fImask\fR, +\fIproc\fR, and \fIclientData\fR arguments. +When a window is deleted all of its handlers will be deleted +automatically; in this case there is no need to call +\fBTk_DeleteEventHandler\fR. +.PP +If multiple handlers are declared for the same type of X event +on the same window, then the handlers will be invoked in the +order they were created. + +.SH KEYWORDS +bind, callback, event, handler diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3 new file mode 100644 index 0000000..188477c --- /dev/null +++ b/doc/FindPhoto.3 @@ -0,0 +1,202 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +'\" "@(#) FindPhoto.3 1.11 97/08/22 18:52:33" +'\" +.so man.macros +.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +\fB#include <tkPhoto.h>\fR +.sp +Tk_PhotoHandle +.VS 8.0 br +\fBTk_FindPhoto\fR(\fIinterp, imageName\fR) +.VE +.sp +void +\fBTk_PhotoPutBlock\fR(\fIhandle, blockPtr, x, y, width, height\fR) +.sp +void +\fBTk_PhotoPutZoomedBlock\fR(\fIhandle, blockPtr, x, y, width, height,\ +zoomX, zoomY, subsampleX, subsampleY\fR) +.sp +int +\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) +.sp +void +\fBTk_PhotoBlank\fR(\fIhandle\fR) +.sp +void +\fBTk_PhotoExpand\fR(\fIhandle, width, height\fR) +.sp +void +\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) +.sp +void +\fBTk_PhotoSetSize\fR(\fIhandle, width, height\fR) +.SH ARGUMENTS +.AS Tk_PhotoImageBlock window_path +.AP Tcl_Interp *interp in +.VS +Interpreter in which image was created. +.VE +.AP char *imageName in +Name of the photo image. +.AP Tk_PhotoHandle handle in +Opaque handle identifying the photo image to be affected. +.AP Tk_PhotoImageBlock *blockPtr in +Specifies the address and storage layout of image data. +.AP int x in +Specifies the X coordinate where the top-left corner of the block is +to be placed within the image. +.AP int y in +Specifies the Y coordinate where the top-left corner of the block is +to be placed within the image. +.AP int width in +Specifies the width of the image area to be affected (for +\fBTk_PhotoPutBlock\fR) or the desired image width (for +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). +.AP int height in +Specifies the height of the image area to be affected (for +\fBTk_PhotoPutBlock\fR) or the desired image height (for +\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). +.AP int *widthPtr out +Pointer to location in which to store the image width. +.AP int *heightPtr out +Pointer to location in which to store the image height. +.AP int subsampleX in +Specifies the subsampling factor in the X direction for input +image data. +.AP int subsampleY in +Specifies the subsampling factor in the Y direction for input +image data. +.AP int zoomX in +Specifies the zoom factor to be applied in the X direction to pixels +being written to the photo image. +.AP int zoomY in +Specifies the zoom factor to be applied in the Y direction to pixels +being written to the photo image. +.BE + +.SH DESCRIPTION +.PP +\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a +particular photo image to the other procedures. The parameter is the +name of the image, that is, the name specified to the \fBimage create +photo\fR command, or assigned by that command if no name was specified. +.PP +\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be +displayed. The call affects an area of the image of size +\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at +coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR, +\fIx\fR, and \fIy\fR must be non-negative. +If part of this area lies outside the +current bounds of the image, the image will be expanded to include the +area, unless the user has specified an explicit image size with the +\fB\-width\fR and/or \fB\-height\fR widget configuration options +(see photo(n)); in that +case the area is silently clipped to the image boundaries. +.PP +The \fIblock\fR parameter is a pointer to a +\fBTk_PhotoImageBlock\fR structure, defined as follows: +.CS +typedef struct { + unsigned char *\fIpixelPtr\fR; + int \fIwidth\fR; + int \fIheight\fR; + int \fIpitch\fR; + int \fIpixelSize\fR; + int \fIoffset[3]\fR; +} Tk_PhotoImageBlock; +.CE +The \fIpixelPtr\fR field points to the first pixel, that is, the +top-left pixel in the block. +The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the +block of pixels. The \fIpixelSize\fR field specifies the address +difference between two horizontally adjacent pixels. Often it is 3 +or 4, but it can have any value. The \fIpitch\fR field specifies the +address difference between two vertically adjacent pixels. The +\fIoffset\fR array contains the offsets from the address of a pixel +to the addresses of the bytes containing the red, green and blue +components. These are normally 0, 1 and 2, but can have other values, +e.g., for images that are stored as separate red, green and blue +planes. +.PP +The value given for the \fIwidth\fR and \fIheight\fR parameters to +\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified +in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a +sub-block from the image data supplied. If they are larger, the data +given are replicated (in a tiled fashion) to fill the specified area. +These rules operate independently in the horizontal and vertical +directions. +.PP +\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that +the image can be reduced or enlarged for display. The +\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the +image to be reduced by subsampling. +\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image +whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y +coordinates are multiples of \fIsubsampleY\fR. For example, an image +of 512x512 pixels can be reduced to 256x256 by setting +\fIsubsampleX\fR and \fIsubsampleY\fR to 2. +.PP +The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be +enlarged by pixel replication. Each pixel of the (possibly subsampled) +input image will be written to a block \fIzoomX\fR pixels wide and +\fIzoomY\fR pixels high of the displayed image. Subsampling and +zooming can be used together for special effects. +.PP +\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo +image. \fBTk_PhotoGetImage\fR fills +in the structure pointed to by the \fIblockPtr\fR parameter with values +that describe the address and layout of the image data that the +photo image has stored internally. The values are valid +until the image is destroyed or its size is changed. +\fBTk_PhotoGetImage\fR returns 1 for compatibility with the +corresponding procedure in the old photo widget. +.PP +\fBTk_PhotoBlank\fR blanks the entire area of the +photo image. Blank areas of a photo image are transparent. +.PP +\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be +at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or +height are unchanged if the user has specified an explicit image width +or height with the \fB\-width\fR and/or \fB\-height\fR configuration +options, respectively. +If the image data +are being supplied in many small blocks, it is more efficient to use +\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than +allowing the image to expand in many small increments as image blocks +are supplied. +.PP +\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user +had specified the given \fIwidth\fR and \fIheight\fR values to the +\fB\-width\fR and \fB\-height\fR configuration options. A value of +zero for \fIwidth\fR or \fIheight\fR does not change the image's width +or height, but allows the width or height to be changed by subsequent +calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or +\fBTk_PhotoExpand\fR. +.PP +\fBTk_PhotoGetSize\fR returns the dimensions of the image in +*\fIwidthPtr\fR and *\fIheightPtr\fR. + +.SH CREDITS +.PP +The code for the photo image type was developed by Paul Mackerras, +based on his earlier photo widget code. + +.SH KEYWORDS +photo, image diff --git a/doc/FontId.3 b/doc/FontId.3 new file mode 100644 index 0000000..71f39e1 --- /dev/null +++ b/doc/FontId.3 @@ -0,0 +1,95 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) FontId.3 1.4 97/11/04 18:03:07 +'\" +.so man.macros +.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_FontId, Tk_FontMetrics, Tk_PostscriptFontName \- accessor functions for +fonts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Font +\fBTk_FontId(\fItkfont\fB)\fR +.sp +void +\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR +.sp +int +\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR + +.SH ARGUMENTS +.AS Tk_FontMetrics *dsPtr +.AP Tk_Font tkfont in +Opaque font token being queried. Must have been returned by a previous +call to \fBTk_GetFont\fR. +.AP Tk_FontMetrics *fmPtr out +Pointer to structure in which the font metrics for \fItkfont\fR will +be stored. +.AP Tcl_DString *dsPtr out +Pointer to an initialized \fBTcl_DString\fR to which the name of the +Postscript font that corresponds to \fItkfont\fR will be appended. +.BE + +.SH DESCRIPTION +.PP +Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be +selected into an XGCValues structure in order to construct a graphics +context that can be used to draw text in the specified font. +.PP +\fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the +\fItkfont\fR in pixels and stores those values in the structure pointer to by +\fIfmPtr\fR. These values can be used in computations such as to space +multiple lines of text, to align the baselines of text in different +fonts, and to vertically align text in a given region. See the +documentation for the \fBfont\fR command for definitions of the terms +ascent, descent, and linespace, used in font metrics. +.PP +\fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding +Postcript font name that should be used when printing. The return value +is the size in points of the \fItkfont\fR and the Postscript font name is +appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized +\fBTcl_DString\fR. Given a ``reasonable'' Postscript printer, the +following screen font families should print correctly: +.IP +\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, +\fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, +\fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, +\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and +\fBZapf Dingbats\fR. +.PP +Any other font families may not print correctly because the computed +Postscript font name may be incorrect or not exist on the printer. +.VS 8.0 br +.SH DATA STRUCTURES +The Tk_FontMetrics data structure is used by Tk_GetFontMetrics to return +information about a font and is defined as follows: +.CS +typedef struct Tk_FontMetrics { + int ascent; + int descent; + int linespace; +} Tk_FontMetrics; +.CE +The \fIlinespace\fR field is the amount in pixels that the tallest +letter sticks up above the baseline, plus any extra blank space added +by the designer of the font. +.PP +The \fIdescent\fR is the largest amount in pixels that any letter +sticks below the baseline, plus any extra blank space added by the +designer of the font. +.PP +The \fIlinespace\fR is the sum of the ascent and descent. How far +apart two lines of text in the same font should be placed so that none +of the characters in one line overlap any of the characters in the +other line. +.VE +.SH KEYWORDS +font diff --git a/doc/FreeXId.3 b/doc/FreeXId.3 new file mode 100644 index 0000000..904523a --- /dev/null +++ b/doc/FreeXId.3 @@ -0,0 +1,52 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) FreeXId.3 1.5 96/03/26 18:07:59 +'\" +.so man.macros +.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_FreeXId \- make X resource identifier available for reuse +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_FreeXId(\fIdisplay, id\fB)\fR +.SH ARGUMENTS +.AS Display *display out +.AP Display *display in +Display for which \fIid\fR was allocated. +.AP XID id in +Identifier of X resource (window, font, pixmap, cursor, graphics +context, or colormap) that is no longer in use. +.BE + +.SH DESCRIPTION +.PP +The default allocator for resource identifiers provided by Xlib is very +simple-minded and does not allow resource identifiers to be re-used. +If a long-running application reaches the end of the resource id +space, it will generate an X protocol error and crash. +Tk replaces the default id allocator with its own allocator, which +allows identifiers to be reused. +In order for this to work, \fBTk_FreeXId\fR must be called to +tell the allocator about resources that have been freed. +Tk automatically calls \fBTk_FreeXId\fR whenever it frees a +resource, so if you use procedures like \fBTk_GetFontStruct\fR, +\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call +\fBTk_FreeXId\fR. +However, if you allocate resources directly from Xlib, for example +by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR +when you call the corresponding Xlib free procedure, such as +\fBXFreePixmap\fR. +If you don't call \fBTk_FreeXId\fR then the resource identifier will +be lost, which could cause problems if the application runs long enough +to lose all of the available identifiers. + +.SH KEYWORDS +resource identifier diff --git a/doc/GeomReq.3 b/doc/GeomReq.3 new file mode 100644 index 0000000..d06b0f8 --- /dev/null +++ b/doc/GeomReq.3 @@ -0,0 +1,69 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" +'\" SCCS: @(#) GeomReq.3 1.11 96/03/26 18:08:21 +'\" +.so man.macros +.TH Tk_GeometryRequest 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GeometryRequest, Tk_SetInternalBorder \- specify desired geometry or internal border for a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) +.sp +\fBTk_SetInternalBorder\fR(\fItkwin, width\fR) +.SH ARGUMENTS +.AS baseHeight clientData +.AP Tk_Window tkwin in +Window for which geometry is being requested. +.AP int reqWidth in +Desired width for \fItkwin\fR, in pixel units. +.AP int reqHeight in +Desired height for \fItkwin\fR, in pixel units. +.AP int width in +Space to leave for internal border for \fItkwin\fR, in pixel units. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GeometryRequest\fR is called by widget code to indicate its +preference for the dimensions of a particular window. The arguments +to \fBTk_GeometryRequest\fR are made available to the geometry +manager for the window, which then decides on the actual geometry +for the window. Although geometry managers generally try to satisfy +requests made to \fBTk_GeometryRequest\fR, there is no guarantee that +this will always be possible. Widget code should not assume that +a geometry request will be satisfied until it receives a +\fBConfigureNotify\fR event indicating that the geometry change has +occurred. Widget code should never call procedures like +\fBTk_ResizeWindow\fR directly. Instead, it should invoke +\fBTk_GeometryRequest\fR and leave the final geometry decisions to +the geometry manager. +.PP +If \fItkwin\fR is a top-level window, then the geometry information +will be passed to the window manager using the standard ICCCM protocol. +.PP +\fBTk_SetInternalBorder\fR is called by widget code to indicate that +the widget has an internal border. This means that the widget draws +a decorative border inside the window instead of using the standard +X borders, which are external to the window's area. For example, +internal borders are used to draw 3-D effects. \fIWidth\fR +specifies the width of the border in pixels. Geometry managers will +use this information to avoid placing any children of \fItkwin\fR +overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area. +.PP +The information specified in calls to \fBTk_GeometryRequest\fR and +\fBTk_SetInternalBorder\fR can be retrieved using the macros +\fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, and \fBTk_InternalBorderWidth\fR. +See the \fBTk_WindowId\fR manual entry for details. + +.SH KEYWORDS +geometry, request diff --git a/doc/GetAnchor.3 b/doc/GetAnchor.3 new file mode 100644 index 0000000..4c5cdfb --- /dev/null +++ b/doc/GetAnchor.3 @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetAnchor.3 1.9 96/03/26 18:08:45 +'\" +.so man.macros +.TH Tk_GetAnchor 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR +.sp +char * +\fBTk_NameOfAnchor(\fIanchor\fB)\fR +.SH ARGUMENTS +.AS "Tk_Anchor" *anchorPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP char *string in +String containing name of anchor point: one of ``n'', ``ne'', ``e'', ``se'', +``s'', ``sw'', ``w'', ``nw'', or ``center''. +.AP int *anchorPtr out +Pointer to location in which to store anchor position corresponding to +\fIstring\fR. +.AP Tk_Anchor anchor in +Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetAnchor\fR places in \fI*anchorPtr\fR an anchor position +(enumerated type \fBTk_Anchor\fR) +corresponding to \fIstring\fR, which will be one of +\fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR, +\fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR, +or \fBTK_ANCHOR_CENTER\fR. +Anchor positions are typically used for indicating a point on an object +that will be used to position that object, e.g. \fBTK_ANCHOR_N\fR means +position the top center point of the object at a particular place. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR doesn't contain a valid anchor position +or an abbreviation of one of these names, then an error message is +stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +\fI*anchorPtr\fR is unmodified. +.PP +\fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR. +Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a +statically-allocated string corresponding to \fIanchor\fR. +If \fIanchor\fR isn't a legal anchor value, then +``unknown anchor position'' is returned. + +.SH KEYWORDS +anchor position diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3 new file mode 100644 index 0000000..efe7760 --- /dev/null +++ b/doc/GetBitmap.3 @@ -0,0 +1,266 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetBitmap.3 1.27 97/08/22 18:52:11 +'\" +.so man.macros +.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Pixmap +\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR +.sp +int +\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR +.sp +Tk_Uid +\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR +.sp +\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR +.sp +\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR +.SH ARGUMENTS +.AS "unsigned long" *pixelPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which the bitmap will be used. +.AP Tk_Uid id in +Description of bitmap; see below for possible values. +.AP Tk_Uid nameId in +Name for new bitmap to be defined. +.AP char *source in +Data for bitmap, in standard bitmap format. +Must be stored in static memory whose value will never change. +.AP "int" width in +Width of bitmap. +.AP "int" height in +Height of bitmap. +.AP "int" *widthPtr out +Pointer to word to fill in with \fIbitmap\fR's width. +.AP "int" *heightPtr out +Pointer to word to fill in with \fIbitmap\fR's height. +.AP Display *display in +Display for which \fIbitmap\fR was allocated. +.AP Pixmap bitmap in +Identifier for a bitmap allocated by \fBTk_GetBitmap\fR. +.BE + +.SH DESCRIPTION +.PP +These procedures manage a collection of bitmaps (one-plane pixmaps) +being used by an application. The procedures allow bitmaps to be +re-used efficiently, thereby avoiding server overhead, and also +allow bitmaps to be named with character strings. +.PP +\fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap. +It returns a Pixmap identifier for a bitmap corresponding to the +description. It re-uses an existing bitmap, if possible, and +creates a new one otherwise. At present, \fIid\fR must have +one of the following forms: +.TP 20 +\fB@\fIfileName\fR +\fIFileName\fR must be the name of a file containing a bitmap +description in the standard X11 or X10 format. +.TP 20 +\fIname\fR +\fIName\fR must be the name of a bitmap defined previously with +a call to \fBTk_DefineBitmap\fR. The following names are pre-defined +by Tk: +.RS +.TP 12 +\fBerror\fR +The international "don't" symbol: a circle with a diagonal line +across it. +.VS "" br +.TP 12 +\fBgray75\fR +75% gray: a checkerboard pattern where three out of four bits are on. +.VE +.TP 12 +\fBgray50\fR +50% gray: a checkerboard pattern where every other bit is on. +.VS "" br +.TP 12 +\fBgray25\fR +25% gray: a checkerboard pattern where one out of every four bits is on. +.VE +.TP 12 +\fBgray12\fR +12.5% gray: a pattern where one-eighth of the bits are on, consisting of +every fourth pixel in every other row. +.TP 12 +\fBhourglass\fR +An hourglass symbol. +.TP 12 +\fBinfo\fR +A large letter ``i''. +.TP 12 +\fBquesthead\fR +The silhouette of a human head, with a question mark in it. +.TP 12 +\fBquestion\fR +A large question-mark. +.TP 12 +\fBwarning\fR +A large exclamation point. +.PP +In addition, the following pre-defined names are available only on the +\fBMacintosh\fR platform: +.TP 12 +\fBdocument\fR +A generic document. +.TP 12 +\fBstationery\fR +Document stationery. +.TP 12 +\fBedition\fR +The \fIedition\fR symbol. +.TP 12 +\fBapplication\fR +Generic application icon. +.TP 12 +\fBaccessory\fR +A desk accessory. +.TP 12 +\fBfolder\fR +Generic folder icon. +.TP 12 +\fBpfolder\fR +A locked folder. +.TP 12 +\fBtrash\fR +A trash can. +.TP 12 +\fBfloppy\fR +A floppy disk. +.TP 12 +\fBramdisk\fR +A floppy disk with chip. +.TP 12 +\fBcdrom\fR +A cd disk icon. +.TP 12 +\fBpreferences\fR +A folder with prefs symbol. +.TP 12 +\fBquerydoc\fR +A database document icon. +.TP 12 +\fBstop\fR +A stop sign. +.TP 12 +\fBnote\fR +A face with ballon words. +.TP 12 +\fBcaution\fR +A triangle with an exclamation point. +.RE +.LP +Under normal conditions, \fBTk_GetBitmap\fR +returns an identifier for the requested bitmap. If an error +occurs in creating the bitmap, such as when \fIid\fR refers +to a non-existent file, then \fBNone\fR is returned and an error +message is left in \fIinterp->result\fR. +.PP +\fBTk_DefineBitmap\fR associates a name with +in-memory bitmap data so that the name can be used in later +calls to \fBTk_GetBitmap\fR. The \fInameId\fR +argument gives a name for the bitmap; it must not previously +have been used in a call to \fBTk_DefineBitmap\fR. +The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR +describe the bitmap. +\fBTk_DefineBitmap\fR normally returns TCL_OK; if an error occurs +(e.g. a bitmap named \fInameId\fR has already been defined) then +TCL_ERROR is returned and an error message is left in +\fIinterp->result\fR. +Note: \fBTk_DefineBitmap\fR expects the memory pointed to by +\fIsource\fR to be static: \fBTk_DefineBitmap\fR doesn't make +a private copy of this memory, but uses the bytes pointed to +by \fIsource\fR later in calls to \fBTk_GetBitmap\fR. +.PP +Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a +bitmap file directly into a C program and then referencing +the variables defined by the file. +For example, suppose there exists a file \fBstip.bitmap\fR, +which was created by the \fBbitmap\fR program and contains +a stipple pattern. +The following code uses \fBTk_DefineBitmap\fR to define a +new bitmap named \fBfoo\fR: +.CS +Pixmap bitmap; +#include "stip.bitmap" +Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits, + stip_width, stip_height); +\&... +bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo")); +.CE +This code causes the bitmap file to be read +at compile-time and incorporates the bitmap information into +the program's executable image. The same bitmap file could be +read at run-time using \fBTk_GetBitmap\fR: +.CS +Pixmap bitmap; +bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap")); +.CE +The second form is a bit more flexible (the file could be modified +after the program has been compiled, or a different string could be +provided to read a different file), but it is a little slower and +requires the bitmap file to exist separately from the program. +.PP +\fBTk_GetBitmap\fR maintains a +database of all the bitmaps that are currently in use. +Whenever possible, it will return an existing bitmap rather +than creating a new one. +This approach can substantially reduce server overhead, so +\fBTk_GetBitmap\fR should generally be used in preference to Xlib +procedures like \fBXReadBitmapFile\fR. +.PP +The bitmaps returned by \fBTk_GetBitmap\fR +are shared, so callers should never modify them. +If a bitmap must be modified dynamically, then it should be +created by calling Xlib procedures such as \fBXReadBitmapFile\fR +or \fBXCreatePixmap\fR directly. +.PP +The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of +\fBTk_GetBitmap\fR. +Given an X Pixmap argument, it returns the \fIid\fR that was +passed to \fBTk_GetBitmap\fR when the bitmap was created. +\fIBitmap\fR must have been the return value from a previous +call to \fBTk_GetBitmap\fR. +.PP +\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR +argument in the words pointed to by the \fIwidthPtr\fR and +\fIheightPtr\fR arguments. As with \fBTk_NameOfBitmap\fR, +\fIbitmap\fR must have been created by \fBTk_GetBitmap\fR. +.PP +When a bitmap returned by \fBTk_GetBitmap\fR +is no longer needed, \fBTk_FreeBitmap\fR should be called to release it. +There should be exactly one call to \fBTk_FreeBitmap\fR for +each call to \fBTk_GetBitmap\fR. +When a bitmap is no longer in use anywhere (i.e. it has been freed as +many times as it has been gotten) \fBTk_FreeBitmap\fR will release +it to the X server and delete it from the database. + +.SH BUGS +In determining whether an existing bitmap can be used to satisfy +a new request, \fBTk_GetBitmap\fR +considers only the immediate value of its \fIid\fR argument. For +example, when a file name is passed to \fBTk_GetBitmap\fR, +\fBTk_GetBitmap\fR will assume it is safe to re-use an existing +bitmap created from the same file name: it will not check to +see whether the file itself has changed, or whether the current +directory has changed, thereby causing the name to refer to +a different file. + +.SH KEYWORDS +bitmap, pixmap diff --git a/doc/GetCapStyl.3 b/doc/GetCapStyl.3 new file mode 100644 index 0000000..a9b8ec9 --- /dev/null +++ b/doc/GetCapStyl.3 @@ -0,0 +1,63 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetCapStyl.3 1.9 96/03/26 18:09:14 +'\" +.so man.macros +.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR +.sp +char * +\fBTk_NameOfCapStyle(\fIcap\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *capPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP char *string in +String containing name of cap style: one of ```butt'', ``projecting'', +or ``round''. +.AP int *capPtr out +Pointer to location in which to store X cap style corresponding to +\fIstring\fR. +.AP int cap in +Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style +corresponding to \fIstring\fR. +This will be one of the values +\fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. +Cap styles are typically used in X graphics contexts to indicate +how the end-points of lines should be capped. +See the X documentation for information on what each style +implies. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR doesn't contain a valid cap style +or an abbreviation of one of these names, then an error message is +stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +\fI*capPtr\fR is unmodified. +.PP +\fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. +Given a cap style such as \fBCapButt\fR it returns a +statically-allocated string corresponding to \fIcap\fR. +If \fIcap\fR isn't a legal cap style, then +``unknown cap style'' is returned. + +.SH KEYWORDS +butt, cap style, projecting, round diff --git a/doc/GetClrmap.3 b/doc/GetClrmap.3 new file mode 100644 index 0000000..4a4121f --- /dev/null +++ b/doc/GetClrmap.3 @@ -0,0 +1,73 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetClrmap.3 1.5 96/03/26 18:09:27 +'\" +.so man.macros +.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Colormap +\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR +.sp +\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR +.SH ARGUMENTS +.AS "Colormap" colormap +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which colormap will be used. +.AP char *string in +Selects a colormap: either \fBnew\fR or the name of a window +with the same screen and visual as \fItkwin\fR. +.AP Display *display in +Display for which \fIcolormap\fR was allocated. +.AP Colormap colormap in +Colormap to free; must have been returned by a previous +call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR. +.BE + +.SH DESCRIPTION +.PP +These procedures are used to manage colormaps. +\fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR. +If its \fIstring\fR argument is \fBnew\fR then a new colormap is +created; otherwise \fIstring\fR must be the name of another window +with the same screen and visual as \fItkwin\fR, and the colormap from that +window is returned. +If \fIstring\fR doesn't make sense, or if it refers to a window on +a different screen from \fItkwin\fR or with +a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns +\fBNone\fR and leaves an error message in \fIinterp->result\fR. +.PP +\fBTk_FreeColormap\fR should be called when a colormap returned by +\fBTk_GetColormap\fR is no longer needed. +Tk maintains a reference count for each colormap returned by +\fBTk_GetColormap\fR, so there should eventually be one call to +\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR. +When a colormap's reference count becomes zero, Tk releases the +X colormap. +.PP +\fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that +a new colormap created by \fBTk_GetVisual\fR may later be returned +by \fBTk_GetColormap\fR. +The reference counting mechanism for colormaps includes both procedures, +so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR +to release the colormap. +If \fBTk_GetColormap\fR is called with a \fIstring\fR value of +\fBnew\fR then the resulting colormap will never +be returned by \fBTk_GetVisual\fR; however, it can be used in other +windows by calling \fBTk_GetColormap\fR with the original window's +name as \fIstring\fR. + +.SH KEYWORDS +colormap diff --git a/doc/GetColor.3 b/doc/GetColor.3 new file mode 100644 index 0000000..7f89446 --- /dev/null +++ b/doc/GetColor.3 @@ -0,0 +1,146 @@ +'\" +'\" Copyright (c) 1990, 1991 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetColor.3 1.22 96/08/27 13:21:26 +'\" +.so man.macros +.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +XColor * +\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR +.sp +XColor * +\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR +.sp +char * +\fBTk_NameOfColor(\fIcolorPtr\fB)\fR +.sp +GC +\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) +.sp +\fBTk_FreeColor(\fIcolorPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *colorPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which color will be used. +.AP Tk_Uid nameId in +Textual description of desired color. +.AP XColor *prefPtr in +Indicates red, green, and blue intensities of desired +color. +.AP XColor *colorPtr in +Pointer to X color information. Must have been allocated by previous +call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed +to \fBTk_NameOfColor\fR. +.AP Drawable drawable in +Drawable in which the result graphics context will be used. Must have +same screen and depth as the window for which the color was allocated. +.BE + +.SH DESCRIPTION +.PP +The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures +locate pixel values that may be used to render particular +colors in the window given by \fItkwin\fR. In \fBTk_GetColor\fR +the desired color is specified with a Tk_Uid (\fInameId\fR), which +may have any of the following forms: +.TP 20 +\fIcolorname\fR +Any of the valid textual names for a color defined in the +server's color database file, such as \fBred\fR or \fBPeachPuff\fR. +.TP 20 +\fB#\fIRGB\fR +.TP 20 +\fB#\fIRRGGBB\fR +.TP 20 +\fB#\fIRRRGGGBBB\fR +.TP 20 +\fB#\fIRRRRGGGGBBBB\fR +A numeric specification of the red, green, and blue intensities +to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR +represents a single hexadecimal digit. The four forms permit +colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values. +When fewer than 16 bits are provided for each color, they represent +the most significant bits of the color. For example, #3a7 is the +same as #3000a0007000. +.PP +In \fBTk_GetColorByValue\fR, the desired color is indicated with +the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure +pointed to by \fIcolorPtr\fR. +.PP +If \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR is successful +in allocating the desired color, then it returns a pointer to +an XColor structure; the structure indicates the exact intensities of +the allocated color (which may differ slightly from those requested, +depending on the limitations of the screen) and a pixel value +that may be used to draw in the color. +If the colormap for \fItkwin\fR is full, \fBTk_GetColor\fR +and \fBTk_GetColorByValue\fR will use the closest existing color +in the colormap. +If \fBTk_GetColor\fR encounters an error while allocating +the color (such as an unknown color name) then NULL is returned and +an error message is stored in \fIinterp->result\fR; +\fBTk_GetColorByValue\fR never returns an error. +.PP +\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database +of all the colors currently in use. +If the same \fInameId\fR is requested multiple times from +\fBTk_GetColor\fR (e.g. by different windows), or if the +same intensities are requested multiple times from +\fBTk_GetColorByValue\fR, then existing pixel values will +be re-used. Re-using an existing pixel avoids any interaction +with the X server, which makes the allocation much more +efficient. For this reason, you should generally use +\fBTk_GetColor\fR or \fBTk_GetColorByValue\fR +instead of Xlib procedures like \fBXAllocColor\fR, +\fBXAllocNamedColor\fR, or \fBXParseColor\fR. +.PP +Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR +may return the same shared +pixel value, callers should never change the color of a pixel +returned by the procedures. +If you need to change a color value dynamically, you should use +\fBXAllocColorCells\fR to allocate the pixel value for the color. +.PP +The procedure \fBTk_NameOfColor\fR is roughly the inverse of +\fBTk_GetColor\fR. If its \fIcolorPtr\fR argument was created +by \fBTk_GetColor\fR, then the return value is the \fInameId\fR +string that was passed to \fBTk_GetColor\fR to create the +color. If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR, +or by any other mechanism, then the return value is a string +that could be passed to \fBTk_GetColor\fR to return the same +color. Note: the string returned by \fBTk_NameOfColor\fR is +only guaranteed to persist until the next call to \fBTk_NameOfColor\fR. +.PP +\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR +field is the pixel allocated for \fIcolorPtr\fR and whose other fields +all have default values. +This provides an easy way to do basic drawing with a color. +The graphics context is cached with the color and will exist only as +long as \fIcolorPtr\fR exists; it is freed when the last reference +to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR. +.PP +When a pixel value returned by \fBTk_GetColor\fR or +\fBTk_GetColorByValue\fR is no longer +needed, \fBTk_FreeColor\fR should be called to release the color. +There should be exactly one call to \fBTk_FreeColor\fR for +each call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR. +When a pixel value is no longer in +use anywhere (i.e. it has been freed as many times as it has been gotten) +\fBTk_FreeColor\fR will release it to the X server and delete it from +the database. + +.SH KEYWORDS +color, intensity, pixel value diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 new file mode 100644 index 0000000..5f940c9 --- /dev/null +++ b/doc/GetCursor.3 @@ -0,0 +1,188 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetCursor.3 1.23 96/08/27 13:21:26 +'\" +.so man.macros +.TH Tk_GetCursor 3 4.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor \- maintain database of cursors +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Cursor +\fBTk_GetCursor(\fIinterp, tkwin, nameId\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR +.sp +char * +\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR +.sp +\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR +.SH ARGUMENTS +.AS "unsigned long" *pixelPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which the cursor will be used. +.AP Tk_Uid nameId in +Description of cursor; see below for possible values. +.AP char *source in +Data for cursor bitmap, in standard bitmap format. +.AP char *mask in +Data for mask bitmap, in standard bitmap format. +.AP "int" width in +Width of \fIsource\fR and \fImask\fR. +.AP "int" height in +Height of \fIsource\fR and \fImask\fR. +.AP "int" xHot in +X-location of cursor hot-spot. +.AP "int" yHot in +Y-location of cursor hot-spot. +.AP Tk_Uid fg in +Textual description of foreground color for cursor. +.AP Tk_Uid bg in +Textual description of background color for cursor. +.AP Display *display in +Display for which \fIcursor\fR was allocated. +.AP Tk_Cursor cursor in +Opaque Tk identifier for cursor. If passed to\fBTk_FreeCursor\fR, must +have been returned by some previous call to \fBTk_GetCursor\fR or +\fBTk_GetCursorFromData\fR. +.BE + +.SH DESCRIPTION +.PP +These procedures manage a collection of cursors +being used by an application. The procedures allow cursors to be +re-used efficiently, thereby avoiding server overhead, and also +allow cursors to be named with character strings (actually Tk_Uids). +.PP +\fBTk_GetCursor\fR takes as argument a Tk_Uid describing a cursor, +and returns an opaque Tk identifier for a cursor corresponding to the +description. +It re-uses an existing cursor if possible and +creates a new one otherwise. \fINameId\fR must be a standard Tcl +list with one of the following forms: +.TP +\fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] +\fIName\fR is the name of a cursor in the standard X cursor font, +i.e., any of the names defined in \fBcursorfont.h\fR, without +the \fBXC_\fR. Some example values are \fBX_cursor\fR, \fBhand2\fR, +or \fBleft_ptr\fR. Appendix B of ``The X Window System'' +by Scheifler & Gettys has illustrations showing what each of these +cursors looks like. If \fIfgColor\fR and \fIbgColor\fR are both +specified, they give the foreground and background colors to use +for the cursor (any of the forms acceptable to \fBTk_GetColor\fR +may be used). If only \fIfgColor\fR is specified, then there +will be no background color: the background will be transparent. +If no colors are specified, then the cursor +will use black for its foreground color and white for its background +color. + +The Macintosh version of Tk also supports all of the X cursors. +Tk on the Mac will also accept any of the standard Mac cursors +including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and +\fBarrow\fR. In addition, Tk will load Macintosh cursor resources of +the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the +name of the of the resource. The application and all its open +dynamic library's resource files will be searched for the named +cursor. If there are conflicts color cursors will always be loaded +in preference to black and white cursors. +.TP +\fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR +In this form, \fIsourceName\fR and \fImaskName\fR are the names of +files describing bitmaps for the cursor's source bits and mask. +Each file must be in standard X11 or X10 bitmap format. +\fIFgColor\fR and \fIbgColor\fR +indicate the colors to use for the +cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This +form of the command will not work on Macintosh or Windows computers. +.TP +\fB@\fIsourceName\0fgColor\fR +This form is similar to the one above, except that the source is +used as mask also. This means that the cursor's background is +transparent. This form of the command will not work on Macintosh +or Windows computers. +.PP +\fBTk_GetCursorFromData\fR allows cursors to be created from +in-memory descriptions of their source and mask bitmaps. \fISource\fR +points to standard bitmap data for the cursor's source bits, and +\fImask\fR points to standard bitmap data describing +which pixels of \fIsource\fR are to be drawn and which are to be +considered transparent. \fIWidth\fR and \fIheight\fR give the +dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the +location of the cursor's hot-spot (the point that is reported when +an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's +foreground and background colors textually (any of the forms +suitable for \fBTk_GetColor\fR may be used). Typically, the +arguments to \fBTk_GetCursorFromData\fR are created by including +a cursor file directly into the source code for a program, as in +the following example: +.CS +Tk_Cursor cursor; +#include "source.cursor" +#include "mask.cursor" +cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, + mask_bits, source_width, source_height, source_x_hot, + source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue")); +.CE +.PP +Under normal conditions, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR +will return an identifier for the requested cursor. If an error +occurs in creating the cursor, such as when \fInameId\fR refers +to a non-existent file, then \fBNone\fR is returned and an error +message will be stored in \fIinterp->result\fR. +.PP +\fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR maintain a +database of all the cursors they have created. Whenever possible, +a call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR will +return an existing cursor rather than creating a new one. This +approach can substantially reduce server overhead, so the Tk +procedures should generally be used in preference to Xlib procedures +like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which +create a new cursor on each call. +.PP +The procedure \fBTk_NameOfCursor\fR is roughly the inverse of +\fBTk_GetCursor\fR. If its \fIcursor\fR argument was created +by \fBTk_GetCursor\fR, then the return value is the \fInameId\fR +argument that was passed to \fBTk_GetCursor\fR to create the +cursor. If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR, +or by any other mechanism, then the return value is a hexadecimal string +giving the X identifier for the cursor. +Note: the string returned by \fBTk_NameOfCursor\fR is +only guaranteed to persist until the next call to +\fBTk_NameOfCursor\fR. Also, this call is not portable except for +cursors returned by \fBTk_GetCursor\fR. +.PP +When a cursor returned by \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR +is no longer needed, \fBTk_FreeCursor\fR should be called to release it. +There should be exactly one call to \fBTk_FreeCursor\fR for +each call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR. +When a cursor is no longer in use anywhere (i.e. it has been freed as +many times as it has been gotten) \fBTk_FreeCursor\fR will release +it to the X server and remove it from the database. + +.SH BUGS +In determining whether an existing cursor can be used to satisfy +a new request, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR +consider only the immediate values of their arguments. For +example, when a file name is passed to \fBTk_GetCursor\fR, +\fBTk_GetCursor\fR will assume it is safe to re-use an existing +cursor created from the same file name: it will not check to +see whether the file itself has changed, or whether the current +directory has changed, thereby causing the name to refer to +a different file. Similarly, \fBTk_GetCursorFromData\fR assumes +that if the same \fIsource\fR pointer is used in two different calls, +then the pointers refer to the same data; it does not check to +see if the actual data values have changed. + +.SH KEYWORDS +cursor diff --git a/doc/GetFont.3 b/doc/GetFont.3 new file mode 100644 index 0000000..ec6c052 --- /dev/null +++ b/doc/GetFont.3 @@ -0,0 +1,74 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetFont.3 1.11 96/07/31 14:07:40 +'\" +.so man.macros +.TH Tk_GetFont 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Font +\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR +.sp +char * +\fBTk_NameOfFont(\fItkfont\fB)\fR +.sp +void +\fBTk_FreeFont(\fItkfont\fB)\fR + +.SH ARGUMENTS +.AS "const char" *tkfont +.AP "Tcl_Interp" *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window on the display in which font will be used. +.AP "const char" *string in +Name or description of desired font. See documentation for the \fBfont\fR +command for details on acceptable formats. +.AP Tk_Font tkfont in +Opaque font token. +.BE +.SH DESCRIPTION +.PP +\fBTk_GetFont\fR finds the font indicated by \fIstring\fR and returns a +token that represents the font. The return value can be used in subsequent +calls to procedures such as \fBTk_FontMetrics\fR, \fBTk_MeasureChars\fR, and +\fBTk_FreeFont\fR. The token returned by \fBTk_GetFont\fR will remain +valid until \fBTk_FreeFont\fR is called to release it. \fIString\fR can +be either a symbolic name or a font description; see the documentation for +the \fBfont\fR command for a description of the valid formats. If +\fBTk_GetFont\fR is unsuccessful (because, for example, \fIstring\fR was +not a valid font specification) then it returns \fBNULL\fR and stores an +error message in \fIinterp->result\fR. +.PP +\fBTk_GetFont\fR maintains a database of all fonts it has allocated. If +the same \fIstring\fR is requested multiple times (e.g. by different +windows or for different purposes), then additional calls for the same +\fIstring\fR will be handled without involving the platform-specific +graphics server. +.PP +The procedure \fBTk_NameOfFont\fR is roughly the inverse of +\fBTk_GetFont\fR. Given a \fItkfont\fR that was created by +\fBTk_GetFont\fR, the return value is the \fIstring\fR argument that was +passed to \fBTk_GetFont\fR to create the font. The string returned by +\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR +is deleted. The caller must not modify this string. +.PP +When a font returned by \fBTk_GetFont\fR is no longer needed, +\fBTk_FreeFont\fR should be called to release it. There should be +exactly one call to \fBTk_FreeFont\fR for each call to \fBTk_GetFont\fR. +When a font is no longer in use anywhere (i.e. it has been freed as many +times as it has been gotten) \fBTk_FreeFont\fR will release any +platform-specific storage and delete it from the database. + +.SH KEYWORDS +font diff --git a/doc/GetGC.3 b/doc/GetGC.3 new file mode 100644 index 0000000..6908e9d --- /dev/null +++ b/doc/GetGC.3 @@ -0,0 +1,74 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetGC.3 1.11 96/03/26 18:10:14 +'\" +.so man.macros +.TH Tk_GetGC 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +GC +\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) +.sp +\fBTk_FreeGC(\fIdisplay, gc\fR) +.SH ARGUMENTS +.AS "unsigned long" valueMask +.AP Tk_Window tkwin in +Token for window in which the graphics context will be used. +.AP "unsigned long" valueMask in +Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) +indicating which fields of \fI*valuePtr\fR are valid. +.AP XGCValues *valuePtr in +Pointer to structure describing the desired values for the +graphics context. +.AP Display *display in +Display for which \fIgc\fR was allocated. +.AP GC gc in +X identifier for graphics context that is no longer needed. +Must have been allocated by \fBTk_GetGC\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts +being used by an application. The procedures allow graphics contexts to be +shared, thereby avoiding the server overhead that would be incurred +if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments +describing the desired graphics context and returns an X identifier +for a GC that fits the description. The graphics context that is returned +will have default values in all of the fields not specified explicitly +by \fIvalueMask\fR and \fIvaluePtr\fR. +.PP +\fBTk_GetGC\fR maintains a +database of all the graphics contexts it has created. Whenever possible, +a call to \fBTk_GetGC\fR will +return an existing graphics context rather than creating a new one. This +approach can substantially reduce server overhead, so \fBTk_GetGC\fR +should generally be used in preference to the Xlib procedure +\fBXCreateGC\fR, which creates a new graphics context on each call. +.PP +Since the return values of \fBTk_GetGC\fR +are shared, callers should never modify the graphics contexts +returned by \fBTk_GetGC\fR. +If a graphics context must be modified dynamically, then it should be +created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR. +.PP +When a graphics context +is no longer needed, \fBTk_FreeGC\fR should be called to release it. +There should be exactly one call to \fBTk_FreeGC\fR for +each call to \fBTk_GetGC\fR. +When a graphics context is no longer in use anywhere (i.e. it has +been freed as many times as it has been gotten) \fBTk_FreeGC\fR +will release it to the X server and delete it from the database. + +.SH KEYWORDS +graphics context diff --git a/doc/GetImage.3 b/doc/GetImage.3 new file mode 100644 index 0000000..4ac178a --- /dev/null +++ b/doc/GetImage.3 @@ -0,0 +1,135 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetImage.3 1.8 96/03/26 18:10:29 +'\" +.so man.macros +.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Image +\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) +.sp +\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) +.sp +\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) +.sp +\fBTk_FreeImage\fR(\fIimage\fR) +.SH ARGUMENTS +.AS Tk_ImageChangedProc *changeProc +.AP Tcl_Interp *interp in +Place to leave error message. +.AP Tk_Window tkwin in +Window in which image will be used. +.AP char *name in +Name of image. +.AP Tk_ImageChangedProc *changeProc in +Procedure for Tk to invoke whenever image content or size changes. +.AP ClientData clientData in +One-word value for Tk to pass to \fIchangeProc\fR. +.AP Tk_Image image in +Token for image instance; must have been returned by a previous +call to \fBTk_GetImage\fR. +.AP int imageX in +X-coordinate of upper-left corner of region of image to redisplay +(measured in pixels from the image's upper-left corner). +.AP int imageY in +Y-coordinate of upper-left corner of region of image to redisplay +(measured in pixels from the image's upper-left corner). +.AP "int" width (in) +Width of region of image to redisplay. +.AP "int" height (in) +Height of region of image to redisplay. +.AP Drawable drawable in +Where to display image. Must either be window specified to +\fBTk_GetImage\fR or a pixmap compatible with that window. +.AP int drawableX in +Where to display image in \fIdrawable\fR: this is the x-coordinate +in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image +should be displayed. +.AP int drawableY in +Where to display image in \fIdrawable\fR: this is the y-coordinate +in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image +should be displayed. +.AP "int" widthPtr out +Store width of \fIimage\fR (in pixels) here. +.AP "int" heightPtr out +Store height of \fIimage\fR (in pixels) here. +.BE + +.SH DESCRIPTION +.PP +These procedures are invoked by widgets that wish to display images. +\fBTk_GetImage\fR is invoked by a widget when it first decides to +display an image. +\fIname\fR gives the name of the desired image and \fItkwin\fR +identifies the window where the image will be displayed. +\fBTk_GetImage\fR looks up the image in the table of existing +images and returns a token for a new instance of the image. +If the image doesn't exist then \fBTk_GetImage\fR returns NULL +and leaves an error message in \fIinterp->result\fR. +.PP +When a widget wishes to actually display an image it must +call \fBTk_RedrawWidget\fR, identifying the image (\fIimage\fR), +a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR, +\fIwidth\fR, and \fIheight\fR), and a place to display the +image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR). +Tk will then invoke the appropriate image manager, which will +display the requested portion of the image before returning. +.PP +A widget can find out the dimensions of an image by calling +\fBTk_SizeOfImage\fR: the width and height will be stored +in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR, +respectively. +.PP +When a widget is finished with an image (e.g., the widget is +being deleted or it is going to use a different image instead +of the current one), it must call \fBTk_FreeImage\fR to +release the image instance. +The widget should never again use the image token after passing +it to \fBTk_FreeImage\fR. +There must be exactly one call to \fBTk_FreeImage\fR for each +call to \fBTk_GetImage\fR. +.PP +If the contents or size of an image changes, then any widgets +using the image will need to find out about the changes so that +they can redisplay themselves. +The \fIchangeProc\fR and \fIclientData\fR arguments to +\fBTk_GetImage\fR are used for this purpose. +\fIchangeProc\fR will be called by Tk whenever a change occurs +in the image; it must match the following prototype: +.CS +typedef void Tk_ImageChangedProc( + ClientData \fIclientData\fR, + int \fIx\fR, + int \fIy\fR, + int \fIwidth\fR, + int \fIheight\fR, + int \fIimageWidth\fR, + int \fIimageHeight\fR); +.CE +The \fIclientData\fR argument to \fIchangeProc\fR is the same as the +\fIclientData\fR argument to \fBTk_GetImage\fR. +It is usually a pointer to the widget record for the widget or +some other data structure managed by the widget. +The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +identify a region within the image that must be redisplayed; +they are specified in pixels measured from the upper-left +corner of the image. +The arguments \fIimageWidth\fR and \fIimageHeight\fR give +the image's (new) size. + +.SH "SEE ALSO" +Tk_CreateImageType + +.SH KEYWORDS +images, redisplay diff --git a/doc/GetJoinStl.3 b/doc/GetJoinStl.3 new file mode 100644 index 0000000..8be41da --- /dev/null +++ b/doc/GetJoinStl.3 @@ -0,0 +1,62 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetJoinStl.3 1.8 96/03/26 18:10:46 +'\" +.so man.macros +.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR +.sp +char * +\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP char *string in +String containing name of join style: one of ``bevel'', ``miter'', +or ``round''. +.AP int *joinPtr out +Pointer to location in which to store X join style corresponding to +\fIstring\fR. +.AP int join in +Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style +corresponding to \fIstring\fR, which will be one of +\fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR. +Join styles are typically used in X graphics contexts to indicate +how adjacent line segments should be joined together. +See the X documentation for information on what each style +implies. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR doesn't contain a valid join style +or an abbreviation of one of these names, then an error message is +stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +\fI*joinPtr\fR is unmodified. +.PP +\fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. +Given a join style such as \fBJoinBevel\fR it returns a +statically-allocated string corresponding to \fIjoin\fR. +If \fIjoin\fR isn't a legal join style, then +``unknown join style'' is returned. + +.SH KEYWORDS +bevel, join style, miter, round diff --git a/doc/GetJustify.3 b/doc/GetJustify.3 new file mode 100644 index 0000000..35ec0ae --- /dev/null +++ b/doc/GetJustify.3 @@ -0,0 +1,69 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetJustify.3 1.11 96/08/27 13:21:27 +'\" +.so man.macros +.TH Tk_GetJustify 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Justify +\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR +.sp +char * +\fBTk_NameOfJustify(\fIjustify\fB)\fR +.SH ARGUMENTS +.AS "Tk_Justify" *justifyPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP char *string in +String containing name of justification style (``left'', ``right'', or +``center''). +.AP int *justifyPtr out +Pointer to location in which to store justify value corresponding to +\fIstring\fR. +.AP Tk_Justify justify in +Justification style (one of the values listed below). +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetJustify\fR places in \fI*justifyPtr\fR the justify value +corresponding to \fIstring\fR. This value will be one of the following: +.TP +\fBTK_JUSTIFY_LEFT\fR +Means that the text on each line should start at the left edge of +the line; as a result, the right edges of lines may be ragged. +.TP +\fBTK_JUSTIFY_RIGHT\fR +Means that the text on each line should end at the right edge of +the line; as a result, the left edges of lines may be ragged. +.TP +\fBTK_JUSTIFY_CENTER\fR +Means that the text on each line should be centered; as a result, +both the left and right edges of lines may be ragged. +.PP +Under normal circumstances the return value is \fBTCL_OK\fR and +\fIinterp\fR is unused. +If \fIstring\fR doesn't contain a valid justification style +or an abbreviation of one of these names, then an error message is +stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and +\fI*justifyPtr\fR is unmodified. +.PP +\fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR. +Given a justify value it returns a statically-allocated string +corresponding to \fIjustify\fR. +If \fIjustify\fR isn't a legal justify value, then +``unknown justification style'' is returned. + +.SH KEYWORDS +center, fill, justification, string diff --git a/doc/GetOption.3 b/doc/GetOption.3 new file mode 100644 index 0000000..d00fd9b --- /dev/null +++ b/doc/GetOption.3 @@ -0,0 +1,46 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetOption.3 1.9 96/03/26 18:11:11 +'\" +.so man.macros +.TH Tk_GetOption 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetOption \- retrieve an option from the option database +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Uid +\fBTk_GetOption\fR(\fItkwin, name, class\fR) +.SH ARGUMENTS +.AS Tk_Window *class +.AP Tk_Window tkwin in +Token for window. +.AP char *name in +Name of desired option. +.AP char *class in +Class of desired option. Null means there is no class for +this option; do lookup based on name only. +.BE + +.SH DESCRIPTION +.PP +This procedure is invoked to retrieve an option from the database +associated with \fItkwin\fR's main window. If there is an option +for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR, +then it is returned in the form of a Tk_Uid. If multiple options +match \fIname\fR and \fIclass\fR, then the highest-priority one +is returned. If no option matches, then NULL is returned. +.PP +\fBTk_GetOption\fR caches options related to \fItkwin\fR so that +successive calls for the same \fItkwin\fR will execute much more +quickly than successive calls for different windows. + +.SH KEYWORDS +class, name, option, retrieve diff --git a/doc/GetPixels.3 b/doc/GetPixels.3 new file mode 100644 index 0000000..6b26eb3 --- /dev/null +++ b/doc/GetPixels.3 @@ -0,0 +1,76 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetPixels.3 1.8 96/03/26 18:11:30 +'\" +.so man.macros +.TH Tk_GetPixels 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetPixels, Tk_GetScreenMM \- translate between strings and screen units +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR +.sp +int +\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *joinPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Window whose screen geometry determines the conversion between absolute +units and pixels. +.AP char *string in +String that specifies a distance on the screen. +.AP int *intPtr out +Pointer to location in which to store converted distance in pixels. +.AP double *doublePtr out +Pointer to location in which to store converted distance in millimeters. +.BE + +.SH DESCRIPTION +.PP +These two procedures take as argument a specification of distance on +the screen (\fIstring\fR) and compute the corresponding distance +either in integer pixels or floating-point millimeters. +In either case, \fIstring\fR specifies a screen distance as a +floating-point number followed by one of the following characters +that indicates units: +.TP +<none> +The number specifies a distance in pixels. +.TP +\fBc\fR +The number specifies a distance in centimeters on the screen. +.TP +\fBi\fR +The number specifies a distance in inches on the screen. +.TP +\fBm\fR +The number specifies a distance in millimeters on the screen. +.TP +\fBp\fR +The number specifies a distance in printer's points (1/72 inch) +on the screen. +.PP +\fBTk_GetPixels\fR converts \fIstring\fR to the nearest even +number of pixels and stores that value at \fI*intPtr\fR. +\fBTk_GetScreenMM\fR converts \fIstring\fR to millimeters and +stores the double-precision floating-point result at \fI*doublePtr\fR. +.PP +Both procedures return \fBTCL_OK\fR under normal circumstances. +If an error occurs (e.g. \fIstring\fR contains a number followed +by a character that isn't one of the ones above) then +\fBTCL_ERROR\fR is returned and an error message is left +in \fIinterp->result\fR. + +.SH KEYWORDS +centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/doc/GetPixmap.3 b/doc/GetPixmap.3 new file mode 100644 index 0000000..f5d030e --- /dev/null +++ b/doc/GetPixmap.3 @@ -0,0 +1,56 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetPixmap.3 1.7 96/03/26 18:11:47 +'\" +.so man.macros +.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Pixmap +\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR +.sp +\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR +.SH ARGUMENTS +.AS "Drawable" *pixelPtr +.AP Display *display in +X display for the pixmap. +.AP Drawable d in +Pixmap or window where the new pixmap will be used for drawing. +.AP "int" width in +Width of pixmap. +.AP "int" height in +Height of pixmap. +.AP "int" depth in +Number of bits per pixel in pixmap. +.AP Pixmap pixmap in +Pixmap to destroy. +.BE + +.SH DESCRIPTION +.PP +These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR +and \fBXFreePixmap\fR, except that they have extra code to manage X +resource identifiers so that identifiers for deleted pixmaps can be +reused in the future. +It is important for Tk applications to use these procedures rather +than \fBXCreatePixmap\fR and \fBXFreePixmap\fR; otherwise long-running +applications may run out of resource identifiers. +.PP +\fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR, +with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, +and returns its identifier. +\fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes +its resource identifier available for reuse. + +.SH KEYWORDS +pixmap, resource identifier diff --git a/doc/GetRelief.3 b/doc/GetRelief.3 new file mode 100644 index 0000000..d0eade4 --- /dev/null +++ b/doc/GetRelief.3 @@ -0,0 +1,59 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetRelief.3 1.11 96/11/17 14:54:49 +'\" +.so man.macros +.TH Tk_GetRelief 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR +.sp +char * +\fBTk_NameOfRelief(\fIrelief\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *reliefPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP char *name in +String containing relief name (one of ``flat'', ``groove'', +``raised'', ``ridge'', ``solid'', or ``sunken''). +.AP int *reliefPtr out +Pointer to location in which to store relief value corresponding to +\fIname\fR. +.AP int relief in +Relief value (one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, +TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE). +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetRelief\fR places in \fI*reliefPtr\fR the relief value +corresponding to \fIname\fR. This value will be one of +TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, +TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE. +Under normal circumstances the return value is TCL_OK and +\fIinterp\fR is unused. +If \fIname\fR doesn't contain one of the valid relief names +or an abbreviation of one of them, then an error message +is stored in \fIinterp->result\fR, +TCL_ERROR is returned, and \fI*reliefPtr\fR is unmodified. +.PP +\fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR. +Given a relief value it returns the corresponding string (``flat'', +``raised'', ``sunken'', ``groove'', ``solid'', or ``ridge''). +If \fIrelief\fR isn't a legal relief value, then ``unknown relief'' +is returned. + +.SH KEYWORDS +name, relief, string diff --git a/doc/GetRootCrd.3 b/doc/GetRootCrd.3 new file mode 100644 index 0000000..c9dea3c --- /dev/null +++ b/doc/GetRootCrd.3 @@ -0,0 +1,43 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetRootCrd.3 1.9 96/03/26 18:12:16 +'\" +.so man.macros +.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetRootCoords \- Compute root-window coordinates of window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for window. +.AP int *xPtr out +Pointer to location in which to store root-window x-coordinate +corresponding to left edge of \fItkwin\fR's border. +.AP int *yPtr out +Pointer to location in which to store root-window y-coordinate +corresponding to top edge of \fItkwin\fR's border. +.BE + +.SH DESCRIPTION +.PP +This procedure scans through the structural information maintained +by Tk to compute the root-window coordinates corresponding to +the upper-left corner of \fItkwin\fR's border. If \fItkwin\fR has +no border, then \fBTk_GetRootCoords\fR returns the root-window +coordinates corresponding to location (0,0) in \fItkwin\fR. +\fBTk_GetRootCoords\fR is relatively efficient, since it doesn't have to +communicate with the X server. + +.SH KEYWORDS +coordinates, root window diff --git a/doc/GetScroll.3 b/doc/GetScroll.3 new file mode 100644 index 0000000..72b97f7 --- /dev/null +++ b/doc/GetScroll.3 @@ -0,0 +1,65 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetScroll.3 1.7 96/03/26 18:12:29 +'\" +.so man.macros +.TH Tk_GetScrollInfo 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetScrollInfo \- parse arguments for scrolling commands +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *dblPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP int argc in +Number of strings in \fIargv\fR array. +.AP char *argv[] in +Argument strings. These represent the entire widget command, of +which the first word is typically the widget name and the second +word is typically \fBxview\fR or \fByview\fR. This procedure parses +arguments starting with \fIargv\fR[2]. +.AP double *dblPtr out +Filled in with fraction from \fBmoveto\fR option, if any. +.AP int *intPtr out +Filled in with line or page count from \fBscroll\fR option, if any. +The value may be negative. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetScrollInfo\fR parses the arguments expected by widget +scrolling commands such as \fBxview\fR and \fByview\fR. +It receives the entire list of words that make up a widget command +and parses the words starting with \fIargv\fR[2]. +The words starting with \fIargv\fR[2] must have one of the following forms: +.CS +\fBmoveto \fIfraction\fR +\fBscroll \fInumber\fB units\fR +\fBscroll \fInumber\fB pages\fR +.CE +.LP +Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR +keywords may be abbreviated. +If \fIargv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR +is returned as result and \fI*dblPtr\fR is filled in with the +\fIfraction\fR argument to the command, which must be a proper real +value. +If \fIargv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR +or \fBTK_SCROLL_PAGES\fR is returned and \fI*intPtr\fR is filled +in with the \fInumber\fR value, which must be a proper integer. +If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR +is returned and an error message is left in \fIinterp->result\fR. + +.SH KEYWORDS +parse, scrollbar, scrolling command, xview, yview diff --git a/doc/GetSelect.3 b/doc/GetSelect.3 new file mode 100644 index 0000000..f0780cc --- /dev/null +++ b/doc/GetSelect.3 @@ -0,0 +1,79 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetSelect.3 1.16 96/08/27 13:21:28 +'\" +.so man.macros +.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetSelection \- retrieve the contents of a selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) +.SH ARGUMENTS +.AS Tk_GetSelProc clientData +.AP Tcl_Interp *interp in +Interpreter to use for reporting errors. +.AP Tk_Window tkwin in +Window on whose behalf to retrieve the selection (determines +display from which to retrieve). +.AP Atom selection in +The name of the selection to be retrieved. +.AP Atom target in +Form in which to retrieve selection. +.AP Tk_GetSelProc *proc in +Procedure to invoke to process pieces of the selection as they +are retrieved. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetSelection\fR retrieves the selection specified by the atom +\fIselection\fR in the format specified by \fItarget\fR. The +selection may actually be retrieved in several pieces; as each piece +is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR +should have arguments and result that match the type +\fBTk_GetSelProc\fR: +.CS +typedef int Tk_GetSelProc( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + char *\fIportion\fR); +.CE +The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR +will be copies of the corresponding arguments to +\fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to +a string containing part or all of the selection. For large +selections, \fIproc\fR will be called several times with successive +portions of the selection. The X Inter-Client Communication +Conventions Manual allows a selection to be returned in formats +other than strings, e.g. as an array of atoms or integers. If +this happens, Tk converts the selection back into a string +before calling \fIproc\fR. If a selection is returned as an +array of atoms, Tk converts it to a string containing the atom names +separated by white space. For any other format besides string, +Tk converts a selection to a string containing hexadecimal +values separated by white space. +.PP +\fBTk_GetSelection\fR returns to its caller when the selection has +been completely retrieved and processed by \fIproc\fR, or when a +fatal error has occurred (e.g. the selection owner didn't respond +promptly). \fBTk_GetSelection\fR normally returns TCL_OK; if +an error occurs, it returns TCL_ERROR and leaves an error message +in \fIinterp->result\fR. \fIProc\fR should also return either +TCL_OK or TCL_ERROR. If \fIproc\fR encounters an error in dealing with the +selection, it should leave an error message in \fIinterp->result\fR +and return TCL_ERROR; this will abort the selection retrieval. + +.SH KEYWORDS +format, get, selection retrieval diff --git a/doc/GetUid.3 b/doc/GetUid.3 new file mode 100644 index 0000000..7c6bb7c --- /dev/null +++ b/doc/GetUid.3 @@ -0,0 +1,50 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetUid.3 1.10 96/03/26 18:12:55 +'\" +.so man.macros +.TH Tk_GetUid 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetUid, Tk_Uid \- convert from string to unique identifier +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fB#typedef char *Tk_Uid\fR +.sp +Tk_Uid +\fBTk_GetUid\fR(\fIstring\fR) +.SH ARGUMENTS +.AP char *string in +String for which the corresponding unique identifier is +desired. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetUid\fR returns the unique identifier corresponding +to \fIstring\fR. +Unique identifiers are similar to atoms in Lisp, and are used +in Tk to speed up comparisons and +searches. A unique identifier (type Tk_Uid) is a string pointer +and may be used anywhere that a variable of type ``char *'' +could be used. However, there is guaranteed to be exactly +one unique identifier for any given string value. If \fBTk_GetUid\fR +is called twice, once with string \fIa\fR and once with string +\fIb\fR, and if \fIa\fR and \fIb\fR have the same string value +(strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly +the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). +This means that variables of type +Tk_Uid may be compared directly (x == y) without having to call +\fBstrcmp\fR. +In addition, the return value from \fBTk_GetUid\fR will have the +same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). + +.SH KEYWORDS +atom, unique identifier diff --git a/doc/GetVRoot.3 b/doc/GetVRoot.3 new file mode 100644 index 0000000..9895e42 --- /dev/null +++ b/doc/GetVRoot.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetVRoot.3 1.10 96/08/27 13:21:28 +'\" +.so man.macros +.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetVRootGeometry \- Get location and size of virtual root for window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR +.SH ARGUMENTS +.AS Tk_Window heightPtr +.AP Tk_Window tkwin in +Token for window whose virtual root is to be queried. +.AP int xPtr out +Points to word in which to store x-offset of virtual root. +.AP int yPtr out +Points to word in which to store y-offset of virtual root. +.AP "int" widthPtr out +Points to word in which to store width of virtual root. +.AP "int" heightPtr out +Points to word in which to store height of virtual root. +.BE + +.SH DESCRIPTION +.PP +\fBTkGetVRootGeometry\fR returns geometry information about the virtual +root window associated with \fItkwin\fR. The ``associated'' virtual +root is the one in which \fItkwin\fR's nearest top-level ancestor (or +\fItkwin\fR itself if it is a top-level window) has +been reparented by the window manager. This window is identified by +a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level +window by the window manager. +If \fItkwin\fR is not associated with a virtual root (e.g. +because the window manager doesn't use virtual roots) then *\fIxPtr\fR and +*\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR +will be set to the dimensions of the screen containing \fItkwin\fR. + +.SH KEYWORDS +geometry, height, location, virtual root, width, window manager diff --git a/doc/GetVisual.3 b/doc/GetVisual.3 new file mode 100644 index 0000000..cf54c2c --- /dev/null +++ b/doc/GetVisual.3 @@ -0,0 +1,98 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) GetVisual.3 1.9 96/03/26 18:13:20 +'\" +.so man.macros +.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_GetVisual \- translate from string to visual +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Visual * +\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR +.SH ARGUMENTS +.AS "Tcl_Interp" *colormapPtr +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tk_Window tkwin in +Token for window in which the visual will be used. +.AP char *string in +String that identifies the desired visual. See below for +valid formats. +.AP int *depthPtr out +Depth of returned visual gets stored here. +.AP Colormap *colormapPtr out +If non-NULL then a suitable colormap for visual is found and its +identifier is stored here. +.BE + +.SH DESCRIPTION +.PP +\fBTk_GetVisual\fR takes a string description of a visual and +finds a suitable X Visual for use in \fItkwin\fR, if there is one. +It returns a pointer to the X Visual structure for the visual +and stores the number of bits per pixel for it at \fI*depthPtr\fR. +If \fIstring\fR is unrecognizable or if no suitable visual could +be found, then NULL is returned and \fBTk_GetVisual\fR leaves +an error message in \fIinterp->result\fR. +If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR +also locates an appropriate colormap for use with the result visual +and stores its X identifier at \fI*colormapPtr\fR. +.PP +The \fIstring\fR argument specifies the desired visual in one +of the following ways: +.TP 15 +\fIclass depth\fR +The string consists of a class name followed by an integer depth, +with any amount of white space (including none) in between. +\fIclass\fR selects what sort of visual is desired and must be one of +\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, +\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or +\fBtruecolor\fR, or a unique abbreviation. +\fIdepth\fR specifies how many bits per pixel are needed for the +visual. +If possible, \fBTk_GetVisual\fR will return a visual with this depth; +if there is no visual of the desired depth then \fBTk_GetVisual\fR +looks first for a visual with greater depth, then one with less +depth. +.TP 15 +\fBdefault\fR +Use the default visual for \fItkwin\fR's screen. +.TP 15 +\fIpathName\fR +Use the visual for the window given by \fIpathName\fR. +\fIpathName\fR must be the name of a window on the same screen +as \fItkwin\fR. +.TP 15 +\fInumber\fR +Use the visual whose X identifier is \fInumber\fR. +.TP 15 +\fBbest\fR ?\fIdepth\fR? +Choose the ``best possible'' visual, using the following rules, in +decreasing order of priority: +(a) a visual that has exactly the desired depth is best, followed +by a visual with greater depth than requested (but as little extra +as possible), followed by a visual with less depth than requested +(but as great a depth as possible); +(b) if no \fIdepth\fR is specified, then the deepest available visual +is chosen; +(c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, +which are better than \fBstaticcolor\fR, which is better than +\fBstaticgray\fR or \fBgrayscale\fR; +(d) the default visual for the screen is better than any other visual. + +.SH CREDITS +.PP +The idea for \fBTk_GetVisual\fR, and the first implementation, came +from Paul Mackerras. + +.SH KEYWORDS +colormap, screen, visual diff --git a/doc/HandleEvent.3 b/doc/HandleEvent.3 new file mode 100644 index 0000000..4fb0a7f --- /dev/null +++ b/doc/HandleEvent.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) HandleEvent.3 1.6 96/03/26 18:13:34 +'\" +.so man.macros +.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_HandleEvent \- invoke event handlers for window system events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_HandleEvent\fR(\fIeventPtr\fR) +.SH ARGUMENTS +.AS XEvent *eventPtr +.AP XEvent *eventPtr in +Pointer to X event to dispatch to relevant handler(s). +.BE + +.SH DESCRIPTION +.PP +\fBTk_HandleEvent\fR is a lower-level procedure that deals with window +events. It is called by \fBTk_ServiceEvent\fR (and indirectly by +\fBTk_DoOneEvent\fR), and in a few other cases within Tk. +It makes callbacks to any window event +handlers (created by calls to \fBTk_CreateEventHandler\fR) +that match \fIeventPtr\fR and then returns. In some cases +it may be useful for an application to bypass the Tk event +queue and call \fBTk_HandleEvent\fR directly instead of +calling \fBTk_QueueEvent\fR followed by +\fBTk_ServiceEvent\fR. +.PP +This procedure may be invoked recursively. For example, +it is possible to invoke \fBTk_HandleEvent\fR recursively +from a handler called by \fBTk_HandleEvent\fR. This sort +of operation is useful in some modal situations, such +as when a +notifier has been popped up and an application wishes to +wait for the user to click a button in the notifier before +doing anything else. + +.SH KEYWORDS +callback, event, handler, window diff --git a/doc/IdToWindow.3 b/doc/IdToWindow.3 new file mode 100644 index 0000000..fd7af7d --- /dev/null +++ b/doc/IdToWindow.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) IdToWindow.3 1.4 96/03/26 18:14:08 +'\" +.so man.macros +.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_IdToWindow \- Find Tk's window information for an X window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_IdToWindow\fR(\fIdisplay, window\fR) +.SH ARGUMENTS +.AS Tk_Window display +.AP Display *display in +X display containing the window. +.AP Window window in +X id for window. +.BE + +.SH DESCRIPTION +.PP +Given an X window identifier and the X display it corresponds to, +this procedure returns the corresponding Tk_Window handle. +If there is no Tk_Window corresponding to \fIwindow\fR then +NULL is returned. + +.SH KEYWORDS +X window id diff --git a/doc/ImgChanged.3 b/doc/ImgChanged.3 new file mode 100644 index 0000000..5210e82 --- /dev/null +++ b/doc/ImgChanged.3 @@ -0,0 +1,69 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ImgChanged.3 1.6 96/03/26 18:14:18 +'\" +.so man.macros +.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ImageChanged \- notify widgets that image needs to be redrawn +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ImageChanged\fR(\fIimageMaster, x, y, width, height, imageWidth, imageHeight\fR) +.SH ARGUMENTS +.AS Tk_ImageMaster imageHeight +.AP Tk_ImageMaster imageMaster in +Token for image, which was passed to image's \fIcreateProc\fR when +the image was created. +.AP int x in +X-coordinate of upper-left corner of region that needs redisplay (measured +from upper-left corner of image). +.AP int y in +Y-coordinate of upper-left corner of region that needs redisplay (measured +from upper-left corner of image). +.AP "int" width in +Width of region that needs to be redrawn, in pixels. +.AP "int" height in +Height of region that needs to be redrawn, in pixels. +.AP "int" imageWidth in +Current width of image, in pixels. +.AP "int" imageHeight in +Current height of image, in pixels. +.BE + +.SH DESCRIPTION +.PP +An image manager calls \fBTk_ImageChanged\fR for an image +whenever anything happens that requires the image to be redrawn. +As a result of calling \fBTk_ImageChanged\fR, any widgets using +the image are notified so that they can redisplay themselves +appropriately. +The \fIimageMaster\fR argument identifies the image, and +\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR +specify a rectangular region within the image that needs to +be redrawn. +\fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. +.PP +An image manager should call \fBTk_ImageChanged\fR during +its \fIcreateProc\fR to specify the image's initial size and to +force redisplay if there are existing instances for the image. +If any of the pixel values in the image should change later on, +\fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR, +\fIwidth\fR, and \fIheight\fR values that cover all the pixels +that changed. +If the size of the image should change, then \fBTk_ImageChanged\fR +must be called to indicate the new size, even if no pixels +need to be redisplayed. + +.SH "SEE ALSO" +Tk_CreateImageType + +.SH KEYWORDS +images, redisplay, image size changes diff --git a/doc/InternAtom.3 b/doc/InternAtom.3 new file mode 100644 index 0000000..e6eff2c --- /dev/null +++ b/doc/InternAtom.3 @@ -0,0 +1,58 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) InternAtom.3 1.8 96/03/26 18:14:31 +'\" +.so man.macros +.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Atom +\fBTk_InternAtom(\fItkwin, name\fR) +.sp +char * +\fBTk_GetAtomName(\fItkwin, atom\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. Used to map atom or name relative to a particular display. +.AP char *name in +String name for which atom is desired. +.AP Atom atom in +Atom for which corresponding string name is desired. +.BE + +.SH DESCRIPTION +.PP +These procedures are similar to the Xlib procedures +\fBXInternAtom\fR and \fBXGetAtomName\fR. \fBTk_InternAtom\fR +returns the atom identifier associated with string given by +\fIname\fR; the atom identifier is only valid for the display +associated with \fItkwin\fR. +\fBTk_GetAtomName\fR returns the string associated +with \fIatom\fR on \fItkwin\fR's display. The string returned +by \fBTk_GetAtomName\fR is in Tk's storage: the caller need +not free this space when finished with the string, and the caller +should not modify the contents of the returned string. +If there is no atom \fIatom\fR on \fItkwin\fR's display, +then \fBTk_GetAtomName\fR returns the string ``?bad atom?''. +.PP +Tk caches +the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR +so that future calls +for the same information can be serviced from the cache without +contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR +are generally much faster than their Xlib counterparts, and they +should be used in place of the Xlib procedures. + +.SH KEYWORDS +atom, cache, display diff --git a/doc/MainLoop.3 b/doc/MainLoop.3 new file mode 100644 index 0000000..339f7e1 --- /dev/null +++ b/doc/MainLoop.3 @@ -0,0 +1,32 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MainLoop.3 1.3 96/03/26 18:15:01 +'\" +.so man.macros +.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MainLoop \- loop for events until all windows are deleted +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MainLoop\fR() +.BE + +.SH DESCRIPTION +.PP +\fBTk_MainLoop\fR is a procedure that loops repeatedly calling +\fBTcl_DoOneEvent\fR. It returns only when there are no applications +left in this process (i.e. no main windows exist anymore). Most +windowing applications will call \fBTk_MainLoop\fR after +initialization; the main execution of the application will consist +entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. + +.SH KEYWORDS +application, event, main loop diff --git a/doc/MainWin.3 b/doc/MainWin.3 new file mode 100644 index 0000000..4144812 --- /dev/null +++ b/doc/MainWin.3 @@ -0,0 +1,36 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MainWin.3 1.5 96/03/26 18:15:15 +'\" +.so man.macros +.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MainWindow \- find the main window for an application +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_MainWindow\fR(\fIinterp\fR) +.SH ARGUMENTS +.AS Tcl_Interp *pathName +.AP Tcl_Interp *interp in/out +Interpreter associated with the application. +.BE + +.SH DESCRIPTION +.PP +If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR +returns the application's main window. +If there is no Tk application associated with \fIinterp\fR then +\fBTk_MainWindow\fR returns NULL and leaves an error message +in \fIinterp->result\fR. + +.SH KEYWORDS +application, main window diff --git a/doc/MaintGeom.3 b/doc/MaintGeom.3 new file mode 100644 index 0000000..159b3b7 --- /dev/null +++ b/doc/MaintGeom.3 @@ -0,0 +1,102 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MaintGeom.3 1.7 96/03/26 18:15:30 +'\" +.so man.macros +.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MaintainGeometry\fR(\fIslave, master, x, y, width, height\fR) +.sp +\fBTk_UnmaintainGeometry\fR(\fIslave, master\fR) +.SH ARGUMENTS +.AS Tk_Window master +.AP Tk_Window slave in +Window whose geometry is to be controlled. +.AP Tk_Window master in +Window relative to which \fIslave\fR's geometry will be controlled. +.AP int x in +Desired x-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels +from the inside of \fImaster\fR's left border to the outside of +\fIslave\fR's left border. +.AP int y in +Desired y-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels +from the inside of \fImaster\fR's top border to the outside of +\fIslave\fR's top border. +.AP int width in +Desired width for \fIslave\fR, in pixels. +.AP int height in +Desired height for \fIslave\fR, in pixels. +.BE + +.SH DESCRIPTION +.PP +\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it +easier for geometry managers to deal with slaves whose masters are not +their parents. +Three problems arise if the master for a slave is not its parent: +.IP [1] +The x- and y-position of the slave must be translated from the +coordinate system of the master to that of the parent before +positioning the slave. +.IP [2] +If the master window, or any of its ancestors up to the slave's +parent, is moved, then the slave must be repositioned within its +parent in order to maintain the correct position relative to the +master. +.IP [3] +If the master or one of its ancestors is mapped or unmapped, then +the slave must be mapped or unmapped to correspond. +.LP +None of these problems is an issue if the parent and master are +the same. For example, if the master or one of its ancestors +is unmapped, the slave is automatically removed by the screen +by X. +.PP +\fBTk_MaintainGeometry\fR deals with these problems for slaves +whose masters aren't their parents. +\fBTk_MaintainGeometry\fR is typically called by a window manager +once it has decided where a slave should be positioned relative +to its master. +\fBTk_MaintainGeometry\fR translates the coordinates to the +coordinate system of \fIslave\fR's parent and then moves and +resizes the slave appropriately. +Furthermore, it remembers the desired position and creates event +handlers to monitor the master and all of its ancestors up +to (but not including) the slave's parent. +If any of these windows is moved, mapped, or unmapped, +the slave will be adjusted so that it is mapped only when the +master is mapped and its geometry relative to the master +remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and +\fIheight\fR. +.PP +When a window manager relinquishes control over a window, or +if it decides that it does not want the window to appear on the +screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR. +\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any +previous calls to \fBTk_MaintainGeometry\fR for the +\fImaster\fR\-\fIslave\fR pair, so that the slave's +geometry and mapped state are no longer maintained +automatically. +\fBTk_UnmaintainGeometry\fR need not be called by a geometry +manager if the slave, the master, or any of the master's ancestors +is destroyed: Tk will call it automatically. +.PP +If \fBTk_MaintainGeometry\fR is called repeatedly for the same +\fImaster\fR\-\fIslave\fR pair, the information from the most +recent call supersedes any older information. +If \fBTk_UnmaintainGeometry\fR is called for a \fImaster\fR\-\fIslave\fR +pair that is isn't currently managed, the call has no effect. + +.SH KEYWORDS +geometry manager, map, master, parent, position, slave, unmap diff --git a/doc/ManageGeom.3 b/doc/ManageGeom.3 new file mode 100644 index 0000000..67ca5b4 --- /dev/null +++ b/doc/ManageGeom.3 @@ -0,0 +1,94 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ManageGeom.3 1.18 96/08/27 13:21:30 +'\" +.so man.macros +.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ManageGeometry \- arrange to handle geometry requests for a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) +.SH ARGUMENTS +.AS Tk_GeometryProc clientData +.AP Tk_Window tkwin in +Token for window to be managed. +.AP Tk_GeomMgr *mgrPtr in +Pointer to data structure containing information about the +geometry manager, or NULL to indicate that \fItkwin\fR's geometry +shouldn't be managed anymore. +The data structure pointed to by \fImgrPtr\fR must be static: +Tk keeps a reference to it as long as the window is managed. +.AP ClientData clientData in +Arbitrary one-word value to pass to geometry manager callbacks. +.BE + +.SH DESCRIPTION +.PP +\fBTk_ManageGeometry\fR arranges for a particular geometry manager, +described by the \fImgrPtr\fR argument, to control the geometry +of a particular slave window, given by \fItkwin\fR. +If \fItkwin\fR was previously managed by some other geometry manager, +the previous manager loses control in favor of the new one. +If \fImgrPtr\fR is NULL, geometry management is cancelled for +\fItkwin\fR. +.PP +The structure pointed to by \fImgrPtr\fR contains information about +the geometry manager: +.CS +typedef struct { + char *\fIname\fR; + Tk_GeomRequestProc *\fIrequestProc\fR; + Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; +} Tk_GeomMgr; +.CE +The \fIname\fR field is the textual name for the geometry manager, +such as \fBpack\fR or \fBplace\fR; this value will be returned +by the command \fBwinfo manager\fR. +.PP +\fIrequestProc\fR is a procedure in the geometry manager that +will be invoked whenever \fBTk_GeometryRequest\fR is called by the +slave to change its desired geometry. +\fIrequestProc\fR should have arguments and results that match the +type \fBTk_GeomRequestProc\fR: +.CS +typedef void Tk_GeomRequestProc( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); +.CE +The parameters to \fIrequestProc\fR will be identical to the +corresponding parameters passed to \fBTk_ManageGeometry\fR. +\fIclientData\fR usually points to a data +structure containing application-specific information about +how to manage \fItkwin\fR's geometry. +.PP +The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another +procedure in the geometry manager. +Tk will invoke \fIlostSlaveProc\fR if some other manager +calls \fBTk_ManageGeometry\fR to claim +\fItkwin\fR away from the current geometry manager. +\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is +called with a NULL value for \fImgrPtr\fR (presumably the current +geometry manager has made this call, so it already knows that the +window is no longer managed), nor is it called if \fImgrPtr\fR +is the same as the window's current geometry manager. +\fIlostSlaveProc\fR should have +arguments and results that match the following prototype: +.CS +typedef void Tk_GeomLostSlaveProc( + ClientData \fIclientData\fR, + Tk_Window \fItkwin\fR); +.CE +The parameters to \fIlostSlaveProc\fR will be identical to the +corresponding parameters passed to \fBTk_ManageGeometry\fR. + +.SH KEYWORDS +callback, geometry, managed, request, unmanaged diff --git a/doc/MapWindow.3 b/doc/MapWindow.3 new file mode 100644 index 0000000..802ef7b --- /dev/null +++ b/doc/MapWindow.3 @@ -0,0 +1,53 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MapWindow.3 1.12 97/01/29 08:50:08 +'\" +.so man.macros +.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_MapWindow\fR(\fItkwin\fR) +.sp +\fBTk_UnmapWindow\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. +.BE + +.SH DESCRIPTION +.PP +These procedures may be used to map and unmap windows +managed by Tk. \fBTk_MapWindow\fR maps the window given +by \fItkwin\fR, and also creates an X window corresponding +to \fItkwin\fR if it doesn't already exist. See the +\fBTk_CreateWindow\fR manual entry for information on +deferred window creation. +\fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window +from the screen. +.PP +If \fItkwin\fR is a child window (i.e. \fBTk_CreateChildWindow\fR was +used to create it), then event handlers interested in map and unmap events +are invoked immediately. If \fItkwin\fR isn't an internal window, +then the event handlers will be invoked later, after X has seen +the request and returned an event for it. +.PP +These procedures should be used in place of the X procedures +\fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update +Tk's local data structure for \fItkwin\fR. Applications +using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR +directly. + +.SH KEYWORDS +map, unmap, window diff --git a/doc/MeasureChar.3 b/doc/MeasureChar.3 new file mode 100644 index 0000000..3d54578 --- /dev/null +++ b/doc/MeasureChar.3 @@ -0,0 +1,130 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MeasureChar.3 1.5 97/06/10 17:33:36 +'\" +.so man.macros +.TH Tk_MeasureChars 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_MeasureChars(\fItkfont, string, maxChars, maxPixels, flags, lengthPtr\fB)\fR +.sp +int +\fBTk_TextWidth(\fItkfont, string, numChars\fB)\fR +.sp +void +\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numChars, x, y\fB)\fR +.sp +void +\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstChar, lastChar\fB)\fR +.sp +.SH ARGUMENTS +.AS "const char" firstChar +.AP Tk_Font tkfont in +Token for font in which text is to be drawn or measured. Must have been +returned by a previous call to \fBTk_GetFont\fR. +.AP "const char" *string in +Text to be measured or displayed. Need not be null terminated. Any +non-printing meta-characters in the string (such as tabs, newlines, and +other control characters) will be measured or displayed in a +platform-dependent manner. +.AP int maxChars in +The maximum number of characters to consider when measuring \fIstring\fR. +Must be greater than or equal to 0. +.AP int maxPixels in +If \fImaxPixels\fR is greater than 0, it specifies the longest permissible +line length in pixels. Characters from \fIstring\fR are processed only +until this many pixels have been covered. If \fImaxPixels\fR is <= 0, then +the line length is unbounded and the \fIflags\fR argument is ignored. +.AP int flags in +Various flag bits OR-ed together: TK_PARTIAL_OK means include a character +as long as any part of it fits in the length given by \fImaxPixels\fR; +otherwise, a character must fit completely to be considered. +TK_WHOLE_WORDS means stop on a word boundary, if possible. If +TK_AT_LEAST_ONE is set, it means return at least one character even if no +characters could fit in the length given by \fImaxPixels\fR. If +TK_AT_LEAST_ONE is set and TK_WHOLE_WORDS is also set, it means that if +not even one word fits on the line, return the first few letters of the +word that did fit; if not even one letter of the word fit, then the first +letter will still be returned. +.AP int *lengthPtr out +Filled with the number of pixels occupied by the number of characters +returned as the result of \fBTk_MeasureChars\fR. +.AP int numChars in +The total number of characters to measure or draw from \fIstring\fR. Must +be greater than or equal to 0. +.AP Display *display in +Display on which to draw. +.AP Drawable drawable in +Window or pixmap in which to draw. +.AP GC gc in +Graphics context for drawing characters. The font selected into this GC +must be the same as the \fItkfont\fR. +.AP int "x, y" in +Coordinates at which to place the left edge of the baseline when displaying +\fIstring\fR. +.AP int firstChar in +The index of the first character to underline in the \fIstring\fR. +Underlining begins at the left edge of this character. +.AP int lastChar in +The index of the last character up to which the underline will +be drawn. The character specified by \fIlastChar\fR will not itself be +underlined. +.BE + +.SH DESCRIPTION +.PP +These routines are for measuring and displaying simple single-font, +single-line, strings. To measure and display single-font, multi-line, +justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR. +There is no programming interface in the core of Tk that supports +multi-font, multi-line text; support for that behavior must be built on +top of simpler layers. +.PP +A glyph is the displayable picture of a letter, number, or some other +symbol. Not all character codes in a given font have a glyph. +Characters such as tabs, newlines/returns, and control characters that +have no glyph are measured and displayed by these procedures in a +platform-dependent manner; under X, they are replaced with backslashed +escape sequences, while under Windows and Macintosh hollow or solid boxes +may be substituted. Refer to the documentation for +\fBTk_ComputeTextLayout\fR for a programming interface that supports the +platform-independent expansion of tab characters into columns and +newlines/returns into multi-line text. +.PP +\fBTk_MeasureChars\fR is used both to compute the length of a given +string and to compute how many characters from a string fit in a given +amount of space. The return value is the number of characters from +\fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to +the conditions described by \fIflags\fR. If all characters fit, the return +value will be \fImaxChars\fR. \fI*lengthPtr\fR is filled with the computed +width, in pixels, of the portion of the string that was measured. For +example, if the return value is 5, then \fI*lengthPtr\fR is filled with the +distance between the left edge of \fIstring\fR[0] and the right edge of +\fIstring\fR[4]. +.PP +\fBTk_TextWidth\fR is a wrapper function that provides a simpler interface +to the \fBTk_MeasureChars\fR function. The return value is how much +space in pixels the given \fIstring\fR needs. +.PP +\fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the +given \fIdrawable\fR. +.PP +\fBTk_UnderlineChars\fR underlines the given range of characters in the +given \fIstring\fR. It doesn't draw the characters (which are assumed to +have been displayed previously by \fBTk_DrawChars\fR); it just draws the +underline. This procedure is used to underline a few characters without +having to construct an underlined font. To produce natively underlined +text, the appropriate underlined font should be constructed and used. + +.SH KEYWORDS +font diff --git a/doc/MoveToplev.3 b/doc/MoveToplev.3 new file mode 100644 index 0000000..4aec2b7 --- /dev/null +++ b/doc/MoveToplev.3 @@ -0,0 +1,55 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) MoveToplev.3 1.8 96/03/26 18:16:11 +'\" +.so man.macros +.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_MoveToplevelWindow \- Adjust the position of a top-level window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for top-level window to move. +.AP int x in +New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the +top-left pixel of the decorative border supplied for \fItkwin\fR by the +window manager, if there is one. +.AP int y in +New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the +top-left pixel of the decorative border supplied for \fItkwin\fR by the +window manager, if there is one. +.BE + +.SH DESCRIPTION +.PP +In general, a window should never set its own position; this should be +done only by the geometry manger that is responsible for the window. +For top-level windows the window manager is effectively the geometry +manager; Tk provides interface code between the application and the +window manager to convey the application's desires to the geometry +manager. The desired size for a top-level window is conveyed using +the usual \fBTk_GeometryRequest\fR mechanism. The procedure +\fBTk_MoveToplevelWindow\fR may be used by an application to request +a particular position for a top-level window; this procedure is +similar in function to the \fBwm geometry\fR Tcl command except that +negative offsets cannot be specified. It is invoked by widgets such as +menus that want to appear at a particular place on the screen. +.PP +When \fBTk_MoveToplevelWindow\fR is called it doesn't immediately +pass on the new desired location to the window manager; it defers +this action until all other outstanding work has been completed, +using the \fBTk_DoWhenIdle\fR mechanism. + +.SH KEYWORDS +position, top-level window, window manager diff --git a/doc/Name.3 b/doc/Name.3 new file mode 100644 index 0000000..8a31f4b --- /dev/null +++ b/doc/Name.3 @@ -0,0 +1,82 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Name.3 1.14 97/01/29 08:50:09 +'\" +.so man.macros +.TH Tk_Name 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Uid +\fBTk_Name\fR(\fItkwin\fR) +.sp +char * +\fBTk_PathName\fR(\fItkwin\fR) +.sp +Tk_Window +\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) +.SH ARGUMENTS +.AS Tcl_Interp *pathName +.AP Tk_Window tkwin in +Token for window. +.AP Tcl_Interp *interp out +Interpreter to use for error reporting. +.AP char *pathName in +Character string containing path name of window. +.BE + +.SH DESCRIPTION +.PP +Each window managed by Tk has two names, a short name that identifies +a window among children of the same parent, and a path name that +identifies the window uniquely among all the windows belonging to the +same main window. The path name is used more often in Tk than the +short name; many commands, like \fBbind\fR, expect path names as +arguments. +.PP +The \fBTk_Name\fR macro returns a window's +short name, which is the same as the \fIname\fR argument +passed to \fBTk_CreateWindow\fR when +the window was created. The value is returned +as a Tk_Uid, which may be used just like a string pointer but also has +the properties of a unique identifier (see the manual entry for +\fBTk_GetUid\fR for details). +.PP +The \fBTk_PathName\fR macro returns a +hierarchical name for \fItkwin\fR. +Path names have a structure similar to file names in Unix but with +dots between elements instead of slashes: the main window for +an application has the path name ``.''; its children have names like +``.a'' and ``.b''; their children have names like ``.a.aa'' and +``.b.bb''; and so on. A window is considered to be be a child of +another window for naming purposes if the second window was named +as the first window's \fIparent\fR when the first window was created. +This is not always the same as the X window hierarchy. For +example, a pop-up +is created as a child of the root window, but its logical parent will +usually be a window within the application. +.PP +The procedure \fBTk_NameToWindow\fR returns the token for a window +given its path name (the \fIpathName\fR argument) and another window +belonging to the same main window (\fItkwin\fR). It normally +returns a token for the named window, but if no such window exists +\fBTk_NameToWindow\fR leaves an error message in \fIinterp->result\fR +and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR +is needed because path names are only unique within a single +application hierarchy. If, for example, a single process has opened +two main windows, each will have a separate naming hierarchy and the +same path name might appear in each of the hierarchies. Normally +\fItkwin\fR is the main window of the desired hierarchy, but this +need not be the case: any window in the desired hierarchy may be used. + +.SH KEYWORDS +name, path name, token, window diff --git a/doc/NameOfImg.3 b/doc/NameOfImg.3 new file mode 100644 index 0000000..4fd814c --- /dev/null +++ b/doc/NameOfImg.3 @@ -0,0 +1,34 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) NameOfImg.3 1.4 96/03/26 18:16:37 +'\" +.so man.macros +.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_NameOfImage \- Return name of image. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +char * +\fBTk_NameOfImage\fR(\fItypePtr\fR) +.SH ARGUMENTS +.AS Tk_ImageMaster *masterPtr +.AP Tk_ImageMaster *masterPtr in +Token for image, which was passed to image manager's \fIcreateProc\fR when +the image was created. +.BE + +.SH DESCRIPTION +.PP +This procedure is invoked by image managers to find out the name +of an image. Given the token for the image, it returns the +string name for the image. + +.SH KEYWORDS +image manager, image name diff --git a/doc/OwnSelect.3 b/doc/OwnSelect.3 new file mode 100644 index 0000000..9473c76 --- /dev/null +++ b/doc/OwnSelect.3 @@ -0,0 +1,52 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) OwnSelect.3 1.16 96/08/27 13:21:31 +'\" +.so man.macros +.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_OwnSelection \- make a window the owner of the primary selection +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) +.SH ARGUMENTS +.AS Tk_LostSelProc clientData +.AP Tk_Window tkwin in +Window that is to become new selection owner. +.AP Atom selection in +The name of the selection to be owned, such as XA_PRIMARY. +.AP Tk_LostSelProc *proc in +Procedure to invoke when \fItkwin\fR loses selection ownership later. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the +new owner of the selection specified by the atom +\fIselection\fR. After this call completes, future requests +for the selection will be directed to handlers created for +\fItkwin\fR using \fBTk_CreateSelHandler\fR. When \fItkwin\fR +eventually loses the selection ownership, \fIproc\fR will be +invoked so that the window can clean itself up (e.g. by +unhighlighting the selection). \fIProc\fR should have arguments and +result that match the type \fBTk_LostSelProc\fR: +.CS +typedef void Tk_LostSelProc(ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a copy of the +\fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is +usually a pointer to a data structure containing application-specific +information about \fItkwin\fR. + +.SH KEYWORDS +own, selection owner diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 new file mode 100644 index 0000000..8a1e854 --- /dev/null +++ b/doc/ParseArgv.3 @@ -0,0 +1,351 @@ +'\" +'\" Copyright (c) 1990-1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ParseArgv.3 1.17 97/10/31 12:58:44 +'\" +.so man.macros +.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ParseArgv \- process command-line options +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) +.SH ARGUMENTS +.AS Tk_ArgvInfo *argTable +.AP Tcl_Interp *interp in +Interpreter to use for returning error messages. +.AP Tk_Window tkwin in +Window to use when arguments specify Tk options. If NULL, then +no Tk options will be processed. +.AP int argcPtr in/out +Pointer to number of arguments in argv; gets modified to hold +number of unprocessed arguments that remain after the call. +.AP char **argv in/out +Command line arguments passed to main program. Modified to +hold unprocessed arguments that remain after the call. +.AP Tk_ArgvInfo *argTable in +Array of argument descriptors, terminated by element with +type TK_ARGV_END. +.AP int flags in +If non-zero, then it specifies one or more flags that control the +parsing of arguments. Different flags may be OR'ed together. +The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, +TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. +.BE +.SH DESCRIPTION +.PP +\fBTk_ParseArgv\fR processes an array of command-line arguments according +to a table describing the kinds of arguments that are expected. +Each of the arguments in \fIargv\fR is processed in turn: if it matches +one of the entries in \fIargTable\fR, the argument is processed +according to that entry and discarded. The arguments that do not +match anything in \fIargTable\fR are copied down to the beginning +of \fIargv\fR (retaining their original order) and returned to +the caller. At the end of the call +\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of +arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR +will hold the value NULL. Normally, \fBTk_ParseArgv\fR +assumes that \fIargv[0]\fR is a command name, so it is treated like +an argument that doesn't match \fIargTable\fR and returned to the +caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in +\fIflags\fR then \fIargv[0]\fR will be processed just like the other +elements of \fIargv\fR. +.PP +\fBTk_ParseArgv\fR normally returns the value TCL_OK. If an error +occurs while parsing the arguments, then TCL_ERROR is returned and +\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR +in the standard Tcl fashion. In +the event of an error return, \fI*argvPtr\fR will not have been +modified, but \fIargv\fR could have been partially modified. The +possible causes of errors are explained below. +.PP +The \fIargTable\fR array specifies the kinds of arguments that are +expected; each of its entries has the following structure: +.CS +typedef struct { + char *\fIkey\fR; + int \fItype\fR; + char *\fIsrc\fR; + char *\fIdst\fR; + char *\fIhelp\fR; +} Tk_ArgvInfo; +.CE +The \fIkey\fR field is a string such as ``\-display'' or ``\-bg'' +that is compared with the values in \fIargv\fR. \fIType\fR +indicates how to process an argument that matches \fIkey\fR +(more on this below). \fISrc\fR and \fIdst\fR are additional +values used in processing the argument. Their exact usage +depends on \fItype\fR, but typically \fIsrc\fR indicates +a value and \fIdst\fR indicates where to store the +value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR +are placeholders: the actual types may be different. Lastly, +\fIhelp\fR is a string giving a brief description +of this option; this string is printed when users ask for help +about command-line options. +.PP +When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR +compares the argument to each of the \fIkey\fR's in \fIargTable\fR. +\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches +the argument exactly, if such a specifier exists. Otherwise +\fBTk_ParseArgv\fR selects a specifier for which the argument +is a unique abbreviation. If the argument is a unique abbreviation +for more than one specifier, then an error is returned. If there +is no matching entry in \fIargTable\fR, then the argument is +skipped and returned to the caller. +.PP +Once a matching argument specifier is found, \fBTk_ParseArgv\fR +processes the argument according to the \fItype\fR field of the +specifier. The argument that matched \fIkey\fR is called ``the matching +argument'' in the descriptions below. As part of the processing, +\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR +after the matching argument, which is called ``the following +argument''. The legal values for \fItype\fR, and the processing +that they cause, are as follows: +.TP +\fBTK_ARGV_END\fR +Marks the end of the table. The last entry in \fIargTable\fR +must have this type; all of its other fields are ignored and it +will never match any arguments. +.TP +\fBTK_ARGV_CONSTANT\fR +\fISrc\fR is treated as an integer and \fIdst\fR is treated +as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. +The matching argument is discarded. +.TP +\fBTK_ARGV_INT\fR +The following argument must contain an +integer string in the format accepted by \fBstrtol\fR (e.g. ``0'' +and ``0x'' prefixes may be used to specify octal or hexadecimal +numbers, respectively). \fIDst\fR is treated as a pointer to an +integer; the following argument is converted to an integer value +and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching +and following arguments are discarded from \fIargv\fR. +.TP +\fBTK_ARGV_FLOAT\fR +The following argument must contain a floating-point number in +the format accepted by \fBstrtol\fR. +\fIDst\fR is treated as the address of an double-precision +floating point value; the following argument is converted to a +double-precision value and stored at \fI*dst\fR. The matching +and following arguments are discarded from \fIargv\fR. +.TP +\fBTK_ARGV_STRING\fR +In this form, \fIdst\fR is treated as a pointer to a (char *); +\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following +argument, and discards the matching and following arguments from +\fIargv\fR. \fISrc\fR is ignored. +.TP +\fBTK_ARGV_UID\fR +This form is similar to TK_ARGV_STRING, except that the argument +is turned into a Tk_Uid by calling \fBTk_GetUid\fR. +\fIDst\fR is treated as a pointer to a +Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid +corresponding to the following +argument, and discards the matching and following arguments from +\fIargv\fR. \fISrc\fR is ignored. +.TP +\fBTK_ARGV_CONST_OPTION\fR +This form causes a Tk option to be set (as if the \fBoption\fR +command had been invoked). The \fIsrc\fR field is treated as a +pointer to a string giving the value of an option, and \fIdst\fR +is treated as a pointer to the name of the option. The matching +argument is discarded. If \fItkwin\fR is NULL, then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_OPTION_VALUE\fR +This form is similar to TK_ARGV_CONST_OPTION, except that the +value of the option is taken from the following argument instead +of from \fIsrc\fR. \fIDst\fR is used as the name of the option. +\fISrc\fR is ignored. The matching and following arguments +are discarded. If \fItkwin\fR is NULL, then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_OPTION_NAME_VALUE\fR +In this case the following argument is taken as the name of a Tk +option and the argument after that is taken as the value for that +option. Both \fIsrc\fR and \fIdst\fR are ignored. All three +arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, +then argument +specifiers of this type are ignored (as if they did not exist). +.TP +\fBTK_ARGV_HELP\fR +When this kind of option is encountered, \fBTk_ParseArgv\fR uses the +\fIhelp\fR fields of \fIargTable\fR to format a message describing +all the valid arguments. The message is placed in \fIinterp->result\fR +and \fBTk_ParseArgv\fR returns TCL_ERROR. When this happens, the +caller normally prints the help message and aborts. If the \fIkey\fR +field of a TK_ARGV_HELP specifier is NULL, then the specifier will +never match any arguments; in this case the specifier simply provides +extra documentation, which will be included when some other +TK_ARGV_HELP entry causes help information to be returned. +.TP +\fBTK_ARGV_REST\fR +This option is used by programs or commands that allow the last +several of their options to be the name and/or options for some +other program. If a \fBTK_ARGV_REST\fR argument is found, then +\fBTk_ParseArgv\fR doesn't process any +of the remaining arguments; it returns them all at +the beginning of \fIargv\fR (along with any other unprocessed arguments). +In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an +integer value, and stores at \fI*dst\fR the index of the first of the +\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the +program to distinguish the \fBTK_ARGV_REST\fR options from other +unprocessed options that preceded the \fBTK_ARGV_REST\fR. +.TP +\fBTK_ARGV_FUNC\fR +For this kind of argument, \fIsrc\fR is treated as the address of +a procedure, which is invoked to process the following argument. +The procedure should have the following structure: +.RS +.CS +int +\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) + char *\fIdst\fR; + char *\fIkey\fR; + char *\fInextArg\fR; +{ +} +.CE +The \fIdst\fR and \fIkey\fR parameters will contain the +corresponding fields from the \fIargTable\fR entry, and +\fInextArg\fR will point to the following argument from \fIargv\fR +(or NULL if there aren't any more arguments left in \fIargv\fR). +If \fIfunc\fR uses \fInextArg\fR (so that +\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it +should return 0 and \fBTkParseArgv\fR will process the following +argument in the normal fashion. In either event the matching argument +is discarded. +.RE +.TP +\fBTK_ARGV_GENFUNC\fR +This form provides a more general procedural escape. It treats +\fIsrc\fR as the address of a procedure, and passes that procedure +all of the remaining arguments. The procedure should have the following +form: +.RS +.CS +int +\fIgenfunc\fR(dst, interp, key, argc, argv) + char *\fIdst\fR; + Tcl_Interp *\fIinterp\fR; + char *\fIkey\fR; + int \fIargc\fR; + char **\fIargv\fR; +{ +} +.CE +The \fIdst\fR and \fIkey\fR parameters will contain the +corresponding fields from the \fIargTable\fR entry. \fIInterp\fR +will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. +\fIArgc\fR and \fIargv\fR refer to all of the options after the +matching one. \fIGenfunc\fR should behave in a fashion similar +to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, +then return any that are left by compacting them to the beginning of +\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR +should return a count of how many arguments are left in \fIargv\fR; +\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters +an error then it should leave an error message in \fIinterp->result\fR, +in the usual Tcl fashion, and return -1; when this happens +\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR. +.RE + +.SH "FLAGS" +.TP +\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR +\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program +or command name, and returns it to the caller just as if it +hadn't matched \fIargTable\fR. If this flag is given, then +\fIargv[0]\fR is not given special treatment. +.TP +\fBTK_ARGV_NO_ABBREV\fR +Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for +\fIkey\fR values in \fIargTable\fR. If this flag is given then +only exact matches will be acceptable. +.TP +\fBTK_ARGV_NO_LEFTOVERS\fR +Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the +caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR +will return an error if it encounters any argument that doesn't +match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, +which will be returned to the caller with no errors as +long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. +.TP +\fBTK_ARGV_NO_DEFAULTS\fR +Normally, \fBTk_ParseArgv\fR searches an internal table of +standard argument specifiers in addition to \fIargTable\fR. If +this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will +use only \fIargTable\fR and not its default table. + +.SH EXAMPLE +.PP +Here is an example definition of an \fIargTable\fR and +some sample command lines that use the options. Note the effect +on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR +are eliminated from \fIargv\fR, and \fIargc\fR +is updated to reflect reduced number of arguments. +.CS +/* + * Define and set default values for globals. + */ +int debugFlag = 0; +int numReps = 100; +char defaultFileName[] = "out"; +char *fileName = defaultFileName; +Boolean exec = FALSE; + +/* + * Define option descriptions. + */ +Tk_ArgvInfo argTable[] = { + {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, + "Turn on debugging printfs"}, + {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, + "Number of repetitions"}, + {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, + "Name of file for output"}, + {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, + "File to exec, followed by any arguments (must be last argument)."}, + {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, + (char *) NULL} +}; + +main(argc, argv) + int argc; + char *argv[]; +{ + \&... + + if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { + fprintf(stderr, "%s\en", interp->result); + exit(1); + } + + /* + * Remainder of the program. + */ +} +.CE +.PP +Note that default values can be assigned to variables named in +\fIargTable\fR: the variables will only be overwritten if the +particular arguments are present in \fIargv\fR. +Here are some example command lines and their effects. +.CS +prog -N 200 infile # just sets the numReps variable to 200 +prog -of out200 infile # sets fileName to reference "out200" +prog -XN 10 infile # sets the debug flag, also sets numReps +.CE +In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, +\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'', +and \fIargv\fR[2] will be NULL. + +.SH KEYWORDS +arguments, command line, options diff --git a/doc/QWinEvent.3 b/doc/QWinEvent.3 new file mode 100644 index 0000000..5bbb4f4 --- /dev/null +++ b/doc/QWinEvent.3 @@ -0,0 +1,42 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) QWinEvent.3 1.4 96/03/26 18:17:16 +'\" +.so man.macros +.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_QueueWindowEvent \- Add a window event to the Tcl event queue +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) +.SH ARGUMENTS +.AS Tcl_QueuePosition position +.AP XEvent *eventPtr in +An event to add to the event queue. +.AP Tcl_QueuePosition position in +Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, +\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. +.BE + +.SH DESCRIPTION +.PP +This procedure places a window event on Tcl's +internal event queue for eventual servicing. It creates a +Tcl_Event structure, copies the event into that structure, +and calls \fBTcl_QueueEvent\fR to add the event to the queue. +When the event is eventually removed from the queue it is +processed just like all window events. +.PP +The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has +the same significance as for \fBTcl_QueueEvent\fR; see the +documentation for \fBTcl_QueueEvent\fR for details. + +.SH KEYWORDS +callback, clock, handler, modal timeout diff --git a/doc/Restack.3 b/doc/Restack.3 new file mode 100644 index 0000000..6f86c8e --- /dev/null +++ b/doc/Restack.3 @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Restack.3 1.5 96/03/26 18:17:32 +'\" +.so man.macros +.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_RestackWindow \- Change a window's position in the stacking order +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) +.SH ARGUMENTS +.AS Tk_Window aboveBelow +.AP Tk_Window tkwin in +Token for window to restack. +.AP int aboveBelow in +Indicates new position of \fItkwin\fR relative to \fIother\fR; +must be \fBAbove\fR or \fBBelow\fR. +.AP Tk_Window other in +\fITkwin\fR will be repositioned just above or below this window. +Must be a sibling of \fItkwin\fR or a descendant of a sibling. +If NULL then \fItkwin\fR is restacked above or below all siblings. +.BE + +.SH DESCRIPTION +.PP +\fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative +to its siblings. +If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned +at the top or bottom of its stacking order, depending on whether +\fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR. +If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned +just above or below \fIother\fR. +.PP +The \fIaboveBelow\fR argument must have one of the symbolic values +\fBAbove\fR or \fBBelow\fR. +Both of these values are defined by the include file <X11/Xlib.h>. + +.SH KEYWORDS +above, below, obscure, stacking order diff --git a/doc/RestrictEv.3 b/doc/RestrictEv.3 new file mode 100644 index 0000000..5daaac4 --- /dev/null +++ b/doc/RestrictEv.3 @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) RestrictEv.3 1.13 96/08/27 13:21:55 +'\" +.so man.macros +.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_RestrictEvents \- filter and selectively delay X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_RestrictProc * +\fBTk_RestrictEvents\fR(\fIproc, clientData, prevClientDataPtr\fR) +.SH ARGUMENTS +.AS Tk_RestrictProc **prevClientDataPtr +.AP Tk_RestrictProc *proc in +Predicate procedure to call to filter incoming X events. +NULL means do not restrict events at all. +.AP ClientData clientData in +Arbitrary argument to pass to \fIproc\fR. +.AP ClientData *prevClientDataPtr out +Pointer to place to save argument to previous restrict procedure. +.BE + +.SH DESCRIPTION +.PP +This procedure is useful in certain situations where applications +are only prepared to receive certain X events. After +\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and +hence \fBTk_MainLoop\fR) will filter X input events through +\fIproc\fR. \fIProc\fR indicates whether a +given event is to be processed immediately, deferred until some +later time (e.g. when the event restriction is lifted), or discarded. +\fIProc\fR +is a procedure with arguments and result that match +the type \fBTk_RestrictProc\fR: +.CS +typedef Tk_RestrictAction Tk_RestrictProc( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR argument is a copy of the \fIclientData\fR passed +to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with +information it needs to filter events. The \fIeventPtr\fR points to +an event under consideration. \fIProc\fR returns a restrict action +(enumerated type \fBTk_RestrictAction\fR) that indicates what +\fBTk_DoOneEvent\fR should do with the event. If the return value is +\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. +If the return value is \fBTK_DEFER_EVENT\fR, then the event will be +left on the event queue for later processing. If the return value is +\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event +queue and discarded without being processed. +.PP +\fBTk_RestrictEvents\fR uses its return value and \fIprevClientDataPtr\fR +to return information about the current event restriction procedure +(a NULL return value means there are currently no restrictions). +These values may be used to restore the previous restriction state +when there is no longer any need for the current restriction. +.PP +There are very few places where \fBTk_RestrictEvents\fR is needed. +In most cases, the best way to restrict events is by changing the +bindings with the \fBbind\fR Tcl command or by calling +\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. +The main place where \fBTk_RestrictEvents\fR must be used is when +performing synchronous actions (for example, if you need to wait +for a particular event to occur on a particular window but you don't +want to invoke any handlers for any other events). The ``obvious'' +solution in these situations is to call \fBXNextEvent\fR or +\fBXWindowEvent\fR, but these procedures cannot be used because +Tk keeps its own event queue that is separate from the X event +queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, +then call \fBTk_DoOneEvent\fR to retrieve the desired event(s). +.SH KEYWORDS +delay, event, filter, restriction diff --git a/doc/SetAppName.3 b/doc/SetAppName.3 new file mode 100644 index 0000000..df2ad30 --- /dev/null +++ b/doc/SetAppName.3 @@ -0,0 +1,65 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) SetAppName.3 1.13 97/06/10 17:33:48 +'\" +.so man.macros +.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_SetAppName \- Set the name of an application for ``send'' commands +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +char * +\fBTk_SetAppName\fR(\fItkwin, name\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window in application. Used only to select a particular +application. +.AP char *name in +Name under which to register the application. +.BE + +.SH DESCRIPTION +.PP +\fBTk_SetAppName\fR associates a name with a given application and +records that association on the display containing with the application's +main window. +After this procedure has been invoked, other applications on the +display will be able to use the \fBsend\fR command to invoke operations +in the application. +If \fIname\fR is already in use by some other application on the +display, then a new name will be generated by appending +``\fB #2\fR'' to \fIname\fR; if this name is also in use, +the number will be incremented until an unused name is found. +The return value from the procedure is a pointer to the name actually +used. +.PP +If the application already has a name when \fBTk_SetAppName\fR is +called, then the new name replaces the old name. +.PP +\fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's +interpreter, which can be used to send commands from this application +to others on any of the displays where the application has windows. +.PP +The application's name registration persists until the interpreter is +deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which +point the name is automatically unregistered and the application +becomes inaccessible via \fBsend\fR. +The application can be made accessible again by calling \fBTk_SetAppName\fR. +.PP +\fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR, +so applications don't normally need to call it explicitly. +.PP +The command \fBtk appname\fR provides Tcl-level access to the +functionality of \fBTk_SetAppName\fR. + +.SH KEYWORDS +application, name, register, send command diff --git a/doc/SetClass.3 b/doc/SetClass.3 new file mode 100644 index 0000000..03127b7 --- /dev/null +++ b/doc/SetClass.3 @@ -0,0 +1,61 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) SetClass.3 1.12 96/03/26 18:18:10 +'\" +.so man.macros +.TH Tk_SetClass 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_SetClass, Tk_Class \- set or retrieve a window's class +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_SetClass\fR(\fItkwin, class\fR) +.sp +Tk_Uid +\fBTk_Class\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window parent +.AP Tk_Window tkwin in +Token for window. +.AP char *class in +New class name for window. +.BE + +.SH DESCRIPTION +.PP +\fBTk_SetClass\fR is called to associate a class with a particular +window. The \fIclass\fR string identifies the type of the +window; all windows with the same general class of behavior +(button, menu, etc.) should have the same class. By +convention all class names start with a capital letter, and +there exists a Tcl command with the same name as +each class (except all in lower-case) which can be used to +create and manipulate windows of that class. +A window's class string is initialized to NULL +when the window is created. +.PP +For main windows, Tk automatically propagates the name and class +to the WM_CLASS property used by window managers. This happens +either when a main window is actually created (e.g. in +\fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR +is called, whichever occurs later. If a main window has not been +assigned a class then Tk will not set the WM_CLASS property for +the window. +.PP +\fBTk_Class\fR is a macro that returns the +current value of \fItkwin\fR's class. The value is returned +as a Tk_Uid, which may be used just like a string pointer but also has +the properties of a unique identifier (see the manual entry for +\fBTk_GetUid\fR for details). +If \fItkwin\fR has not yet been given a class, then +\fBTk_Class\fR will return NULL. + +.SH KEYWORDS +class, unique identifier, window, window manager diff --git a/doc/SetGrid.3 b/doc/SetGrid.3 new file mode 100644 index 0000000..b2a3b40 --- /dev/null +++ b/doc/SetGrid.3 @@ -0,0 +1,67 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) SetGrid.3 1.11 96/08/27 13:21:33 +'\" +.so man.macros +.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) +.sp +\fBTk_UnsetGrid\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window heightInc +.AP Tk_Window tkwin in +Token for window. +.AP int reqWidth in +Width in grid units that corresponds to the pixel dimension \fItkwin\fR +has requested via \fBTk_GeometryRequest\fR. +.AP int reqHeight in +Height in grid units that corresponds to the pixel dimension \fItkwin\fR +has requested via \fBTk_GeometryRequest\fR. +.AP int widthInc in +Width of one grid unit, in pixels. +.AP int heightInc in +Height of one grid unit, in pixels. +.BE + +.SH DESCRIPTION +.PP +\fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's +toplevel window and specifies the geometry of the grid. +\fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR +option is true. +It restricts interactive resizing of \fItkwin\fR's toplevel window so +that the space allocated to the toplevel is equal to its requested +size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR. +Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are +passed to the window manager so that it can report the window's +size in grid units during interactive resizes. +If \fItkwin\fR's configuration changes (e.g., the size of a grid unit +changes) then the widget should invoke \fBTk_SetGrid\fR again with the new +information. +.PP +\fBTk_UnsetGrid\fR cancels gridded geometry management for +\fItkwin\fR's toplevel window. +.PP +For each toplevel window there can be at most one internal window +with gridding enabled. +If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some +other window is already controlling gridding for \fItkwin\fR's +toplevel, the calls for the new window have no effect. +.PP +See the \fBwm\fR manual entry for additional information on gridded geometry +management. + +.SH KEYWORDS +grid, window, window manager diff --git a/doc/SetVisual.3 b/doc/SetVisual.3 new file mode 100644 index 0000000..f76c467 --- /dev/null +++ b/doc/SetVisual.3 @@ -0,0 +1,54 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) SetVisual.3 1.10 96/03/26 18:18:39 +'\" +.so man.macros +.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_SetWindowVisual \- change visual characteristics of window +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) +.SH ARGUMENTS +.AS "Tk_Window int" colormap +.AP Tk_Window tkwin in +Token for window. +.AP Visual *visual in +New visual type to use for \fItkwin\fR. +.AP "int" depth in +Number of bits per pixel desired for \fItkwin\fR. +.AP Colormap colormap in +New colormap for \fItkwin\fR, which must be compatible with +\fIvisual\fR and \fIdepth\fR. +.BE + +.SH DESCRIPTION +.PP +When Tk creates a new window it assigns it the default visual +characteristics (visual, depth, and colormap) for its screen. +\fBTk_SetWindowVisual\fR may be called to change them. +\fBTk_SetWindowVisual\fR must be called before the window has +actually been created in X (e.g. before \fBTk_MapWindow\fR or +\fBTk_MakeWindowExist\fR has been invoked for the window). +The safest thing is to call \fBTk_SetWindowVisual\fR immediately +after calling \fBTk_CreateWindow\fR. +If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR +is called then it returns 0 and doesn't make any changes; otherwise +it returns 1 to signify that the operation +completed successfully. +.PP +Note: \fBTk_SetWindowVisual\fR should not be called if you just want +to change a window's colormap without changing its visual or depth; +call \fBTk_SetWindowColormap\fR instead. + +.SH KEYWORDS +colormap, depth, visual diff --git a/doc/StrictMotif.3 b/doc/StrictMotif.3 new file mode 100644 index 0000000..6ba5b60 --- /dev/null +++ b/doc/StrictMotif.3 @@ -0,0 +1,41 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) StrictMotif.3 1.4 96/03/26 18:18:52 +'\" +.so man.macros +.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_StrictMotif \- Return value of tk_strictMotif variable +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_StrictMotif\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for window. +.BE + +.SH DESCRIPTION +.PP +This procedure returns the current value of the \fBtk_strictMotif\fR +variable in the interpreter associated with \fItkwin\fR's application. +The value is returned as an integer that is either 0 or 1. +1 means that strict Motif compliance has been requested, so anything +that is not part of the Motif specification should be avoided. +0 means that ``Motif-like'' is good enough, and extra features +are welcome. +.PP +This procedure uses a link to the Tcl variable to provide much +faster access to the variable's value than could be had by calling +\fBTcl_GetVar\fR. + +.SH KEYWORDS +Motif compliance, tk_strictMotif variable diff --git a/doc/TextLayout.3 b/doc/TextLayout.3 new file mode 100644 index 0000000..d4a8399 --- /dev/null +++ b/doc/TextLayout.3 @@ -0,0 +1,270 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) TextLayout.3 1.6 96/12/16 16:48:12 +'\" +.so man.macros +.TH Tk_ComputeTextLayout 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_TextLayout +\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR +.sp +void +\fBTk_FreeTextLayout(\fIlayout\fB)\fR +.sp +void +\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR +.sp +void +\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR +.sp +int +\fBTk_PointToChar(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR +.sp +int +\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR +.sp +int +\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR +.sp +void +\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR + +.SH ARGUMENTS +.AS Tk_TextLayout "*xPtr, *yPtr" +.AP Tk_Font tkfont in +Font to use when constructing and displaying a text layout. The +\fItkfont\fR must remain valid for the lifetime of the text layout. Must +have been returned by a previous call to \fBTk_GetFont\fR. +.AP "const char" *string in +Potentially multi-line string whose dimensions are to be computed and +stored in the text layout. The \fIstring\fR must remain valid for the +lifetime of the text layout. +.AP int numChars in +The number of characters to consider from \fIstring\fR. If +\fInumChars\fR is less than 0, then assumes \fIstring\fR is null +terminated and uses \fBstrlen(\fIstring\fB)\fR. +.AP int wrapLength in +Longest permissible line length, in pixels. Lines in \fIstring\fR will +automatically be broken at word boundaries and wrapped when they reach +this length. If \fIwrapLength\fR is too small for even a single +character to fit on a line, it will be expanded to allow one character to +fit on each line. If \fIwrapLength\fR is <= 0, there is no automatic +wrapping; lines will get as long as they need to be and only wrap if a +newline/return character is encountered. +.AP Tk_Justify justify in +How to justify the lines in a multi-line text layout. Possible values +are TK_JUSTIFY_LEFT, TK_JUSTIFY_CENTER, or TK_JUSTIFY_RIGHT. If the text +layout only occupies a single line, then \fIjustify\fR is irrelevant. +.AP int flags in +Various flag bits OR-ed together. TK_IGNORE_TABS means that tab characters +should not be expanded to the next tab stop. TK_IGNORE_NEWLINES means that +newline/return characters should not cause a line break. If either tabs or +newlines/returns are ignored, then they will be treated as regular +characters, being measured and displayed in a platform-dependent manner as +described in \fBTk_MeasureChars\fR, and will not have any special behaviors. +.AP int *widthPtr out +If non-NULL, filled with either the width, in pixels, of the widest +line in the text layout, or the width, in pixels, of the bounding box for the +character specified by \fIindex\fR. +.AP int *heightPtr out +If non-NULL, filled with either the total height, in pixels, of all +the lines in the text layout, or the height, in pixels, of the bounding +box for the character specified by \fIindex\fR. +.AP Tk_TextLayout layout in +A token that represents the cached layout information about the single-font, +multi-line, justified piece of text. This token is returned by +\fBTk_ComputeTextLayout\fR. +.AP Display *display in +Display on which to draw. +.AP Drawable drawable in +Window or pixmap in which to draw. +.AP GC gc in +Graphics context to use for drawing text layout. The font selected in +this GC must correspond to the \fItkfont\fR used when constructing the +text layout. +.AP int "x, y" in +Point, in pixels, at which to place the upper-left hand corner of the +text layout when it is being drawn, or the coordinates of a point (with +respect to the upper-left hand corner of the text layout) to check +against the text layout. +.AP int firstChar in +The index of the first character to draw from the given text layout. +The number 0 means to draw from the beginning. +.AP int lastChar in +The index of the last character up to which to draw. The character +specified by \fIlastChar\fR itself will not be drawn. A number less +than 0 means to draw all characters in the text layout. +.AP int underline in +Index of the single character to underline in the text layout, or a number +less than 0 for no underline. +.AP int index in +The index of the character whose bounding box is desired. The bounding +box is computed with respect to the upper-left hand corner of the text layout. +.AP int "*xPtr, *yPtr" out +Filled with the upper-left hand corner, in pixels, of the bounding box +for the character specified by \fIindex\fR. Either or both \fIxPtr\fR +and \fIyPtr\fR may be NULL, in which case the corresponding value +is not calculated. +.AP int "width, height" in +Specifies the width and height, in pixels, of the rectangular area to +compare for intersection against the text layout. +.AP Tcl_Interp *interp out +Postscript code that will print the text layout is appended to +\fIinterp->result\fR. +.BE + +.SH DESCRIPTION +.PP +These routines are for measuring and displaying single-font, multi-line, +justified text. To measure and display simple single-font, single-line +strings, refer to the documentation for \fBTk_MeasureChars\fR. There is +no programming interface in the core of Tk that supports multi-font, +multi-line text; support for that behavior must be built on top of +simpler layers. +.PP +The routines described here are built on top of the programming interface +described in the \fBTk_MeasureChars\fR documentation. Tab characters and +newline/return characters may be treated specially by these procedures, +but all other characters are passed through to the lower level. +.PP +\fBTk_ComputeTextLayout\fR computes the layout information needed to +display a single-font, multi-line, justified \fIstring\fR of text and +returns a Tk_TextLayout token that holds this information. This token is +used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, +\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The +\fIstring\fR and \fItkfont\fR used when computing the layout must remain +valid for the lifetime of this token. +.PP +\fBTk_FreeTextLayout\fR is called to release the storage associated with +\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used +in any other text layout procedures once it has been released. +.PP +\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a +single-font, multi-line, justified string of text at the specified location. +.PP +\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to +display an underline below an individual character. This procedure does +not draw the text, just the underline. To produce natively underlined +text, an underlined font should be constructed and used. All characters, +including tabs, newline/return characters, and spaces at the ends of +lines, can be underlined using this method. However, the underline will +never be drawn outside of the computed width of \fIlayout\fR; the +underline will stop at the edge for any character that would extend +partially outside of \fIlayout\fR, and the underline will not be visible +at all for any character that would be located completely outside of the +layout. +.PP +\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the +character closest to the given point. The point is specified with respect +to the upper-left hand corner of the \fIlayout\fR, which is considered to be +located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be +considered closest to the first character in the text layout; any point +whose \fIy\fR-value is greater than the height of the text layout will be +considered closest to the last character in the text layout. Any point +whose \fIx\fR-value is less than 0 will be considered closest to the first +character on that line; any point whose \fIx\fR-value is greater than the +width of the text layout will be considered closest to the last character on +that line. The return value is the index of the character that was closest +to the point. Given a \fIlayout\fR with no characters, the value 0 will +always be returned, referring to a hypothetical zero-width placeholder +character. +.PP +\fBTk_CharBBox\fR uses the information in \fIlayout\fR to return the +bounding box for the character specified by \fIindex\fR. The width of the +bounding box is the advance width of the character, and does not include any +left or right bearing. Any character that extends partially outside of +\fIlayout\fR is considered to be truncated at the edge. Any character +that would be located completely outside of \fIlayout\fR is considered to +be zero-width and pegged against the edge. The height of the bounding +box is the line height for this font, extending from the top of the +ascent to the bottom of the descent; information about the actual height +of individual letters is not available. For measurement purposes, a +\fIlayout\fR that contains no characters is considered to contain a +single zero-width placeholder character at index 0. If \fIindex\fR was +not a valid character index, the return value is 0 and \fI*xPtr\fR, +\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. +Otherwise, if \fIindex\fR did specify a valid, the return value is +non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and +\fI*heightPtr\fR are filled with the bounding box information for the +character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or +\fIheightPtr\fR are NULL, the corresponding value is not calculated or +stored. +.PP +\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from +the given point (\fIx, y\fR) to the characters in \fIlayout\fR. +Newline/return characters and non-displaying space characters that occur at +the end of individual lines in the text layout are ignored for hit detection +purposes, but tab characters are not. The return value is 0 if the point +actually hits the \fIlayout\fR. If the point didn't hit the \fIlayout\fR +then the return value is the distance in pixels from the point to the +\fIlayout\fR. +.PP +\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies +entirely inside, entirely outside, or overlaps a given rectangle. +Newline/return characters and non-displaying space characters that occur +at the end of individual lines in the \fIlayout\fR are ignored for +intersection calculations. The return value is \-1 if the \fIlayout\fR is +entirely outside of the rectangle, 0 if it overlaps, and 1 if it is +entirely inside of the rectangle. +.PP +\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript +array of strings that represent the individual lines in \fIlayout\fR. It +is the responsibility of the caller to take the Postscript array of +strings and add some Postscript function operate on the array to render +each of the lines. The code that represents the Postscript array of +strings is appended to \fIinterp->result\fR. +.PP +.SH DISPLAY MODEL +When measuring a text layout, space characters that occur at the end of a +line are ignored. The space characters still exist and the insertion point +can be positioned amongst them, but their additional width is ignored when +justifying lines or returning the total width of a text layout. All +end-of-line space characters are considered to be attached to the right edge +of the line; this behavior is logical for left-justified text and reasonable +for center-justified text, but not very useful when editing right-justified +text. Spaces are considered variable width characters; the first space that +extends past the edge of the text layout is clipped to the edge, and any +subsequent spaces on the line are considered zero width and pegged against +the edge. Space characters that occur in the middle of a line of text are +not suppressed and occupy their normal space width. +.PP +Tab characters are not ignored for measurement calculations. If wrapping +is turned on and there are enough tabs on a line, the next tab will wrap +to the beginning of the next line. There are some possible strange +interactions between tabs and justification; tab positions are calculated +and the line length computed in a left-justified world, and then the +whole resulting line is shifted so it is centered or right-justified, +causing the tab columns not to align any more. +.PP +When wrapping is turned on, lines may wrap at word breaks (space or tab +characters) or newline/returns. A dash or hyphen character in the middle +of a word is not considered a word break. \fBTk_ComputeTextLayout\fR +always attempts to place at least one word on each line. If it cannot +because the \fIwrapLength\fR is too small, the word will be broken and as +much as fits placed on the line and the rest on subsequent line(s). If +\fIwrapLength\fR is so small that not even one character can fit on a +given line, the \fIwrapLength\fR is ignored for that line and one +character will be placed on the line anyhow. When wrapping is turned +off, only newline/return characters may cause a line break. +.PP +When a text layout has been created using an underlined \fItkfont\fR, +then any space characters that occur at the end of individual lines, +newlines/returns, and tabs will not be displayed underlined when +\fBTk_DrawTextLayout\fR is called, because those characters are never +actually drawn \- they are merely placeholders maintained in the +\fIlayout\fR. +.SH KEYWORDS +font diff --git a/doc/Tk_Init.3 b/doc/Tk_Init.3 new file mode 100644 index 0000000..20ed41d --- /dev/null +++ b/doc/Tk_Init.3 @@ -0,0 +1,47 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Tk_Init.3 1.3 96/03/26 18:19:08 +'\" +.so man.macros +.TH Tk_Init 3 4.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_Init \- add Tk to an interpreter and make a new Tk application. +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +int +\fBTk_Init\fR(\fIinterp\fR) +.SH ARGUMENTS +.AS Tcl_Interp *interp +.AP Tcl_Interp *interp in +Interpreter in which to load Tk. Tk should not already be loaded +in this interpreter. +.BE + +.SH DESCRIPTION +.PP +\fBTk_Init\fR is the package initialization procedure for Tk. +It is normally invoked by the \fBTcl_AppInit\fR procedure +for an application or by the \fBload\fR command. +\fBTk_Init\fR adds all of Tk's commands to \fIinterp\fR +and creates a new Tk application, including its main window. +If the initialization is successful \fBTk_Init\fR returns +\fBTCL_OK\fR; if there is an error it returns \fBTCL_ERROR\fR. +\fBTk_Init\fR also leaves a result or error message +in \fIinterp->result\fR. +.PP +If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR +treats the contents of this variable as a list of options for the +new Tk application. +The options may have any of the forms documented for the +\fBwish\fR application (in fact, \fBwish\fR uses Tk_Init to process +its command-line arguments). + +.SH KEYWORDS +application, initialization, load, main window diff --git a/doc/Tk_Main.3 b/doc/Tk_Main.3 new file mode 100644 index 0000000..7565aae --- /dev/null +++ b/doc/Tk_Main.3 @@ -0,0 +1,61 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Tk_Main.3 1.7 96/03/26 18:19:21 +'\" +.so man.macros +.TH Tk_Main 3 4.0 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_Main \- main program for Tk-based applications +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +\fBTk_Main\fR(\fIargc, argv, appInitProc\fR) +.SH ARGUMENTS +.AS Tcl_AppInitProc *appInitProc +.AP int argc in +Number of elements in \fIargv\fR. +.AP char *argv[] in +Array of strings containing command-line arguments. +.AP Tcl_AppInitProc *appInitProc in +Address of an application-specific initialization procedure. +The value for this argument is usually \fBTcl_AppInit\fR. +.BE + +.SH DESCRIPTION +.PP +\fBTk_Main\fR acts as the main program for most Tk-based applications. +Starting with Tk 4.0 it is not called \fBmain\fR anymore because it +is part of the Tk library and having a function \fBmain\fR +in a library (particularly a shared library) causes problems on many +systems. +Having \fBmain\fR in the Tk library would also make it hard to use +Tk in C++ programs, since C++ programs must have special C++ +\fBmain\fR functions. +.PP +Normally each application contains a small \fBmain\fR function that does +nothing but invoke \fBTk_Main\fR. +\fBTk_Main\fR then does all the work of creating and running a +\fBwish\fR-like application. +.PP +When it is has finished its own initialization, but before +it processes commands, \fBTk_Main\fR calls the procedure given by +the \fIappInitProc\fR argument. This procedure provides a ``hook'' +for the application to perform its own initialization, such as defining +application-specific commands. The procedure must have an interface +that matches the type \fBTcl_AppInitProc\fR: +.CS +typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); +.CE +\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; +for more details on this procedure, see the documentation +for \fBTcl_AppInit\fR. + +.SH KEYWORDS +application-specific initialization, command-line arguments, main program diff --git a/doc/WindowId.3 b/doc/WindowId.3 new file mode 100644 index 0000000..3de27b0 --- /dev/null +++ b/doc/WindowId.3 @@ -0,0 +1,151 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) WindowId.3 1.16 97/01/29 08:50:10 +'\" +.so man.macros +.TH Tk_WindowId 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, Tk_Visual, Tk_Depth, Tk_Colormap \- retrieve information from Tk's local data structure +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Window +\fBTk_WindowId\fR(\fItkwin\fR) +.sp +Tk_Window +\fBTk_Parent\fR(\fItkwin\fR) +.sp +Display * +\fBTk_Display\fR(\fItkwin\fR) +.sp +char * +\fBTk_DisplayName\fR(\fItkwin\fR) +.sp +int +\fBTk_ScreenNumber\fR(\fItkwin\fR) +.sp +Screen * +\fBTk_Screen\fR(\fItkwin\fR) +.sp +int +\fBTk_X\fR(\fItkwin\fR) +.sp +int +\fBTk_Y\fR(\fItkwin\fR) +.sp +int +\fBTk_Width\fR(\fItkwin\fR) +.sp +int +\fBTk_Height\fR(\fItkwin\fR) +.sp +XWindowChanges * +\fBTk_Changes\fR(\fItkwin\fR) +.sp +XSetWindowAttributes * +\fBTk_Attributes\fR(\fItkwin\fR) +.sp +int +\fBTk_IsMapped\fR(\fItkwin\fR) +.sp +int +\fBTk_IsTopLevel\fR(\fItkwin\fR) +.sp +int +\fBTk_ReqWidth\fR(\fItkwin\fR) +.sp +int +\fBTk_ReqHeight\fR(\fItkwin\fR) +.sp +int +\fBTk_InternalBorderWidth\fR(\fItkwin\fR) +.sp +Visual * +\fBTk_Visual\fR(\fItkwin\fR) +.sp +int +\fBTk_Depth\fR(\fItkwin\fR) +.sp +Colormap +\fBTk_Colormap\fR(\fItkwin\fR) +.SH ARGUMENTS +.AS Tk_Window tkwin +.AP Tk_Window tkwin in +Token for window. +.BE + +.SH DESCRIPTION +.PP +\fBTk_WindowID\fR and the other names listed above are +all macros that return fields from Tk's local data structure +for \fItkwin\fR. None of these macros requires any +interaction with the server; it is safe to assume that +all are fast. +.PP +\fBTk_WindowId\fR returns the X identifier for \fItkwin\fR, +or \fBNULL\fR if no X window has been created for \fItkwin\fR +yet. +.PP +\fBTk_Parent\fR returns Tk's token for the logical parent of +\fItkwin\fR. The parent is the token that was specified when +\fItkwin\fR was created, or NULL for main windows. +.PP +\fBTk_Display\fR returns a pointer to the Xlib display structure +corresponding to \fItkwin\fR. \fBTk_DisplayName\fR returns an +ASCII string identifying \fItkwin\fR's display. \fBTk_ScreenNumber\fR +returns the index of \fItkwin\fR's screen among all the screens +of \fItkwin\fR's display. \fBTk_Screen\fR returns a pointer to +the Xlib structure corresponding to \fItkwin\fR's screen. +.PP +\fBTk_X\fR, \fBTk_Y\fR, \fBTk_Width\fR, and \fBTk_Height\fR +return information about \fItkwin's\fR location within its +parent and its size. The location information refers to the +upper-left pixel in the window, or its border if there is one. +The width and height information refers to the interior size +of the window, not including any border. \fBTk_Changes\fR +returns a pointer to a structure containing all of the above +information plus a few other fields. \fBTk_Attributes\fR +returns a pointer to an XSetWindowAttributes structure describing +all of the attributes of the \fItkwin\fR's window, such as background +pixmap, event mask, and so on (Tk keeps track of all this information +as it is changed by the application). Note: it is essential that +applications use Tk procedures like \fBTk_ResizeWindow\fR instead +of X procedures like \fBXResizeWindow\fR, so that Tk can keep its +data structures up-to-date. +.PP +\fBTk_IsMapped\fR returns a non-zero value if \fItkwin\fR +is mapped and zero if \fItkwin\fR isn't mapped. +.PP +\fBTk_IsTopLevel\fR returns a non-zero value if \fItkwin\fR +is a top-level window (its X parent is the root window of the +screen) and zero if \fItkwin\fR isn't a top-level window. +.PP +\fBTk_ReqWidth\fR and \fBTk_ReqHeight\fR return information about +the window's requested size. These values correspond to the last +call to \fBTk_GeometryRequest\fR for \fItkwin\fR. +.PP +\fBTk_InternalBorderWidth\fR returns the width of internal border +that has been requested for \fItkwin\fR, or 0 if no internal border +was requested. The return value is simply the last value passed +to \fBTk_SetInternalBorder\fR for \fItkwin\fR. +.PP +\fBTk_Visual\fR, \fBTk_Depth\fR, and \fBTk_Colormap\fR return +information about the visual characteristics of a window. +\fBTk_Visual\fR returns the visual type for +the window, \fBTk_Depth\fR returns the number of bits per pixel, +and \fBTk_Colormap\fR returns the current +colormap for the window. The visual characteristics are +normally set from the defaults for the window's screen, but +they may be overridden by calling \fBTk_SetWindowVisual\fR. + +.SH KEYWORDS +attributes, colormap, depth, display, height, geometry manager, +identifier, mapped, requested size, screen, top-level, +visual, width, window, x, y diff --git a/doc/bell.n b/doc/bell.n new file mode 100644 index 0000000..03c7452 --- /dev/null +++ b/doc/bell.n @@ -0,0 +1,34 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) bell.n 1.8 96/03/26 18:19:55 +'\" +.so man.macros +.TH bell n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +bell \- Ring a display's bell +.SH SYNOPSIS +\fBbell \fR?\fB\-displayof \fIwindow\fR? +.BE + +.SH DESCRIPTION +.PP +This command rings the bell on the display for \fIwindow\fR and +returns an empty string. +If the \fB\-displayof\fR option is omitted, the display of the +application's main window is used by default. +The command uses the current bell-related settings for the display, which +may be modified with programs such as \fBxset\fR. +.PP +This command also resets the screen saver for the screen. Some +screen savers will ignore this, but others will reset so that the +screen becomes visible again. + +.SH KEYWORDS +beep, bell, ring diff --git a/doc/bind.n b/doc/bind.n new file mode 100644 index 0000000..e621c94 --- /dev/null +++ b/doc/bind.n @@ -0,0 +1,474 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) bind.n 1.41 96/10/03 18:27:05 +'\" +.so man.macros +.TH bind n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +bind \- Arrange for X events to invoke Tcl scripts +.SH SYNOPSIS +\fBbind\fI tag\fR +.sp +\fBbind\fI tag sequence\fR +.sp +\fBbind\fI tag sequence script\fR +.sp +\fBbind\fI tag sequence \fB+\fIscript\fR +.BE + +.SH INTRODUCTION +.PP +The \fBbind\fR command associates Tcl scripts with X events. +If all three arguments are specified, \fBbind\fR will +arrange for \fIscript\fR (a Tcl 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, +\fBbind\fR returns an empty string. +.PP +If \fIsequence\fR is specified without a \fIscript\fR, then the +script currently bound to \fIsequence\fR is returned, or +an empty string is returned if there is no binding for \fIsequence\fR. +If neither \fIsequence\fR nor \fIscript\fR is specified, then the +return value is a list whose elements are all the sequences +for which there exist bindings for \fItag\fR. +.PP +The \fItag\fR argument determines which window(s) the binding applies to. +If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must +be the path name for a window; otherwise it may be an arbitrary +string. +Each window has an associated list of tags, and a binding applies +to a particular window if its tag is among those specified for +the window. +Although the \fBbindtags\fR command may be used to assign an +arbitrary set of binding tags to a window, the default binding +tags provide the following behavior: +.IP +If a tag is the name of an internal window the binding applies +to that window. +.IP +If the tag is the name of a toplevel window the binding applies +to the toplevel window and all its internal windows. +.IP +If the tag is the name of a class of widgets, such as \fBButton\fR, +the binding applies to all widgets in that class; +.IP +If \fItag\fR has the value \fBall\fR, +the binding applies to all windows in the application. + +.SH "EVENT PATTERNS" +.PP +The \fIsequence\fR argument specifies a sequence of one or more +event patterns, with optional white space between the patterns. Each +.VS +event pattern may +take one of three forms. In the simplest case it is a single +.VE +printing ASCII character, such as \fBa\fR or \fB[\fR. The character +may not be a space character or the character \fB<\fR. This form of +pattern matches a \fBKeyPress\fR event for the particular +character. The second form of pattern is longer but more general. +It has the following syntax: +.CS +\fB<\fImodifier-modifier-type-detail\fB>\fR +.CE +The entire event pattern is surrounded by angle brackets. +Inside the angle brackets are zero or more modifiers, an event +type, and an extra piece of information (\fIdetail\fR) identifying +a particular button or keysym. Any of the fields may be omitted, +as long as at least one of \fItype\fR and \fIdetail\fR is present. +The fields must be separated by white space or dashes. +.VS +.PP +The third form of pattern is used to specify a user-defined, named virtual +event. It has the following syntax: +.CS +\fB<<\fIname\fB>>\fR +.CE +The entire virtual event pattern is surrounded by double angle brackets. +Inside the angle brackets is the user-defined name of the virtual event. +Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a +virtual event to modify it. Bindings on a virtual event may be created +before the virtual event is defined, and if the definition of a virtual +event changes dynamically, all windows bound to that virtual event will +respond immediately to the new definition. +.VE +.SH "MODIFIERS" +.PP +Modifiers consist of any of the following values: +.DS +.ta 6c +\fBControl\fR \fBMod2, M2\fR +\fBShift\fR \fBMod3, M3\fR +\fBLock\fR \fBMod4, M4\fR +\fBButton1, B1\fR \fBMod5, M5\fR +\fBButton2, B2\fR \fBMeta, M\fR +\fBButton3, B3\fR \fBAlt\fR +\fBButton4, B4\fR \fBDouble\fR +\fBButton5, B5\fR \fBTriple\fR +\fBMod1, M1\fR +.DE +Where more than one value is listed, separated by commas, the values +are equivalent. +Most of the modifiers have the obvious X meanings. +For example, \fBButton1\fR requires that +button 1 be depressed when the event occurs. +For a binding to match a given event, the modifiers in the event +must include all of those specified in the event pattern. +An event may also contain additional modifiers not specified in +the binding. +For example, if button 1 is pressed while the shift and control keys +are down, the pattern \fB<Control-Button-1>\fR will match +the event, but \fB<Mod1-Button-1>\fR will not. +If no modifiers are specified, then any combination of modifiers may +be present in the event. +.PP +\fBMeta\fR and \fBM\fR refer to whichever of the +\fBM1\fR through \fBM5\fR modifiers is associated with the meta +key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). +If there are no meta keys, or if they are not associated with any +modifiers, then \fBMeta\fR and \fBM\fR will not match any events. +Similarly, the \fBAlt\fR modifier refers to whichever modifier +is associated with the alt key(s) on the keyboard (keysyms +\fBAlt_L\fR and \fBAlt_R\fR). +.PP +The \fBDouble\fR and \fBTriple\fR modifiers are a convenience +for specifying double mouse clicks and other repeated +events. They cause a particular event pattern to be +repeated 2 or 3 times, and also place a time and space requirement +on the sequence: for a sequence of events to match a \fBDouble\fR +or \fBTriple\fR pattern, all of the events must occur close together +in time and without substantial mouse motion in between. +For example, \fB<Double-Button-1>\fR +is equivalent to \fB<Button-1><Button-1>\fR with the extra +time and space requirement. + +.SH "EVENT TYPES" +.PP +The \fItype\fR field may be any of the standard X event types, with a +few extra abbreviations. Below is a list of all the valid types; +where two names appear together, they are synonyms. +.DS C +.ta 5c 10c +\fBButtonPress, Button Expose Map +ButtonRelease FocusIn Motion +Circulate FocusOut Property +Colormap Gravity Reparent +Configure KeyPress, Key Unmap +Destroy KeyRelease Visibility +Enter Leave Activate +Deactivate\fR +.DE +.PP +The last part of a long event specification is \fIdetail\fR. In the +case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the +number of a button (1-5). If a button number is given, then only an +event on that particular button will match; if no button number is +given, then an event on any button will match. Note: giving a +specific button number is different than specifying a button modifier; +in the first case, it refers to a button being pressed or released, +while in the second it refers to some other button that is already +depressed when the matching event occurs. If a button +number is given then \fItype\fR may be omitted: if will default +to \fBButtonPress\fR. For example, the specifier \fB<1>\fR +is equivalent to \fB<ButtonPress-1>\fR. +.PP +If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then +\fIdetail\fR may be specified in the form of an X keysym. Keysyms +are textual specifications for particular keys on the keyboard; +they include all the alphanumeric ASCII characters (e.g. ``a'' is +the keysym for the ASCII character ``a''), plus descriptions for +non-alphanumeric characters (``comma'' is the keysym for the comma +character), plus descriptions for all the non-ASCII keys on the +keyboard (``Shift_L'' is the keysm for the left shift key, and +``F1'' is the keysym for the F1 function key, if it exists). The +complete list of keysyms is not presented here; it is +available in other X documentation and may vary from system to +system. +If necessary, you can use the \fB%K\fR notation described below +to print out the keysym name for a particular key. +If a keysym \fIdetail\fR is given, then the +\fItype\fR field may be omitted; it will default to \fBKeyPress\fR. +For example, \fB<Control-comma>\fR is equivalent to +\fB<Control-KeyPress-comma>\fR. + +.SH "BINDING SCRIPTS AND SUBSTITUTIONS" +.PP +The \fIscript\fR argument to \fBbind\fR is a Tcl script, +which will be executed whenever the given event sequence occurs. +\fICommand\fR will be executed in the same interpreter that the +\fBbind\fR command was executed in, and it will run at global +level (only global variables will be accessible). +If \fIscript\fR contains +any \fB%\fR characters, then the script will not be +executed directly. Instead, a new script will be +generated by replacing each \fB%\fR, and the character following +it, with information from the current event. The replacement +depends on the character following the \fB%\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 \fB%%\fR 5 +Replaced with a single percent. +.IP \fB%#\fR 5 +The number of the last client request processed by the server +(the \fIserial\fR field from the event). Valid for all event +types. +.IP \fB%a\fR 5 +The \fIabove\fR field from the event, +formatted as a hexadecimal number. +Valid only for \fBConfigure\fR events. +.IP \fB%b\fR 5 +The number of the button that was pressed or released. Valid only +for \fBButtonPress\fR and \fBButtonRelease\fR events. +.IP \fB%c\fR 5 +The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. +.IP \fB%d\fR 5 +The \fIdetail\fR field from the event. The \fB%d\fR is replaced by +a string identifying the detail. For \fBEnter\fR, +\fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, +the string will be one of the following: +.RS +.DS +.ta 6c +\fBNotifyAncestor NotifyNonlinearVirtual +NotifyDetailNone NotifyPointer +NotifyInferior NotifyPointerRoot +NotifyNonlinear NotifyVirtual\fR +.DE +For events other than these, the substituted string is undefined. +.RE +.IP \fB%f\fR 5 +The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only +for \fBEnter\fR and \fBLeave\fR events. +.IP \fB%h\fR 5 +.VS +The \fIheight\fR field from the event. Valid only for \fBConfigure\fR and +\fBExpose\fR events. +.VE +.IP \fB%k\fR 5 +The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR +and \fBKeyRelease\fR events. +.IP \fB%m\fR 5 +The \fImode\fR field from the event. The substituted string is one of +\fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or +.VS +\fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR, +\fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events. +.VE +.IP \fB%o\fR 5 +The \fIoverride_redirect\fR field from the event. Valid only for +\fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. +.IP \fB%p\fR 5 +The \fIplace\fR field from the event, substituted as one of the +strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only +for \fBCirculate\fR events. +.IP \fB%s\fR 5 +The \fIstate\fR field from the event. For \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR, +\fBLeave\fR, and \fBMotion\fR events, a decimal string +is substituted. For \fBVisibility\fR, one of the strings +\fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, +and \fBVisibilityFullyObscured\fR is substituted. +.IP \fB%t\fR 5 +The \fItime\fR field from the event. Valid only for events that +contain a \fItime\fR field. +.IP \fB%w\fR 5 +The \fIwidth\fR field from the event. Valid only for +.VS +\fBConfigure\fR and \fBExpose\fR events. +.VE +.IP \fB%x\fR 5 +The \fIx\fR field from the event. Valid only for events containing +an \fIx\fR field. +.IP \fB%y\fR 5 +The \fIy\fR field from the event. Valid only for events containing +a \fIy\fR field. +.IP \fB%A\fR 5 +Substitutes the ASCII character corresponding to the event, or +the empty string if the event doesn't correspond to an ASCII character +(e.g. the shift key was pressed). \fBXLookupString\fR does all the +work of translating from the event to an ASCII character. +Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +.IP \fB%B\fR 5 +The \fIborder_width\fR field from the event. Valid only for +\fBConfigure\fR events. +.IP \fB%E\fR 5 +The \fIsend_event\fR field from the event. Valid for all event types. +.IP \fB%K\fR 5 +The keysym corresponding to the event, substituted as a textual +string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +.IP \fB%N\fR 5 +The keysym corresponding to the event, substituted as a decimal +number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. +.IP \fB%R\fR 5 +The \fIroot\fR window identifier from the event. Valid only for +events containing a \fIroot\fR field. +.IP \fB%S\fR 5 +The \fIsubwindow\fR window identifier from the event, +formatted as a hexadecimal number. +Valid only for events containing a \fIsubwindow\fR field. +.IP \fB%T\fR 5 +The \fItype\fR field from the event. Valid for all event types. +.IP \fB%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 \fB%X\fR 5 +The \fIx_root\fR field from the event. +If a virtual-root window manager is being used then the substituted +value is the corresponding x-coordinate in the virtual root. +Valid only for +\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, +and \fBMotion\fR events. +.IP \fB%Y\fR 5 +The \fIy_root\fR field from the event. +If a virtual-root window manager is being used then the substituted +value is the corresponding y-coordinate in the virtual root. +Valid only for +\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, +and \fBMotion\fR events. +.LP +The replacement string for a %-replacement is formatted as a proper +Tcl list element. +This means that it will be surrounded with braces +if it contains spaces, or special characters such as \fB$\fR and +\fB{\fR may be preceded by backslashes. +This guarantees that the string will be passed through the Tcl +parser when the binding script is evaluated. +Most replacements are numbers or well-defined strings such +as \fBAbove\fR; for these replacements no special formatting +is ever necessary. +The most common case where reformatting occurs is for the \fB%A\fR +substitution. For example, if \fIscript\fR is +.CS +\fBinsert\0%A\fR +.CE +and the character typed is an open square bracket, then the script +actually executed will be +.CS +\fBinsert\0\e[\fR +.CE +This will cause the \fBinsert\fR to receive the original replacement +string (open square bracket) as its first argument. +If the extra backslash hadn't been added, Tcl would not have been +able to parse the script correctly. + +.SH MULTIPLE MATCHES +.PP +It is possible for several bindings to match a given X event. +If the bindings are associated with different \fItag\fR's, +then each of the bindings will be executed, in order. +By default, a binding for the widget will be executed first, followed +by a class binding, a binding for its toplevel, and +an \fBall\fR binding. +The \fBbindtags\fR command may be used to change this order for +a particular window or to associate additional binding tags with +the window. +.PP +The \fBcontinue\fR and \fBbreak\fR commands may be used inside a +binding script to control the processing of matching scripts. +If \fBcontinue\fR is invoked, then the current binding script +is terminated but Tk will continue processing binding scripts +associated with other \fItag\fR's. +If the \fBbreak\fR command is invoked within a binding script, +then that script terminates and no other scripts will be invoked +for the event. +.VS +.PP +If more than one binding matches a particular event and they +have the same \fItag\fR, then the most specific binding +is chosen and its script is evaluated. +The following tests are applied, in order, to determine which of +several matching sequences is more specific: +(a) an event pattern that specifies a specific button or key is more specific +than one that doesn't; +(b) a longer sequence (in terms of number +of events matched) is more specific than a shorter sequence; +(c) if the modifiers specified in one pattern are a subset of the +modifiers in another pattern, then the pattern with more modifiers +is more specific. +.VS +(d) a virtual event whose physical pattern matches the sequence is less +specific than the same physical pattern that is not associated with a +virtual event. +(e) given a sequence that matches two or more virtual events, one +of the virtual events will be chosen, but the order is undefined. +.PP +If the matching sequences contain more than one event, then tests +(c)-(e) are applied in order from the most recent event to the least recent +event in the sequences. If these tests fail to determine a winner, then the +most recently registered sequence is the winner. +.PP +If there are two (or more) virtual events that are both triggered by the +same sequence, and both of those virtual events are bound to the same window +tag, then only one of the virtual events will be triggered, and it will +be picked at random: +.CS +event add <<Paste>> <Control-y> +event add <<Paste>> <Button-2> +event add <<Scroll>> <Button-2> +bind Entry <<Paste>> {puts Paste} +bind Entry <<Scroll>> {puts Scroll} +.CE +If the user types Control-y, the \fB<<Paste>>\fR binding +will be invoked, but if the user presses button 2 then one of +either the \fB<<Paste>>\fR or the \fB<<Scroll>>\fR bindings will +be invoked, but exactly which one gets invoked is undefined. +.VE +.PP +If an X event does not match any of the existing bindings, then the +event is ignored. +An unbound event is not considered to be an error. + +.SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" +.PP +When a \fIsequence\fR specified in a \fBbind\fR command contains +more than one event pattern, then its script is executed whenever +the recent events (leading up to and including the current event) +match the given sequence. This means, for example, that if button 1 is +clicked repeatedly the sequence \fB<Double-ButtonPress-1>\fR will match +each button press but the first. +If extraneous events that would prevent a match occur in the middle +of an event sequence then the extraneous events are +ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events. +For example, \fB<Double-ButtonPress-1>\fR will match a sequence of +presses of button 1, even though there will be \fBButtonRelease\fR +events (and possibly \fBMotion\fR events) between the +\fBButtonPress\fR events. +Furthermore, a \fBKeyPress\fR event may be preceded by any number +of other \fBKeyPress\fR events for modifier keys without the +modifier keys preventing a match. +For example, the event sequence \fBaB\fR will match a press of the +\fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR +key, and a press of the \fBb\fR key: the press of \fBShift\fR is +ignored because it is a modifier key. +Finally, if several \fBMotion\fR events occur in a row, only +the last one is used for purposes of matching binding sequences. + +.SH ERRORS +.PP +If an error occurs in executing the script for a binding then the +\fBbgerror\fR mechanism is used to report the error. +The \fBbgerror\fR command will be executed at global level +(outside the context of any Tcl procedure). + +.SH "SEE ALSO" +bgerror + +.SH KEYWORDS +form, manual diff --git a/doc/bindtags.n b/doc/bindtags.n new file mode 100644 index 0000000..c93bb63 --- /dev/null +++ b/doc/bindtags.n @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) bindtags.n 1.9 96/11/30 14:54:49 +'\" +.so man.macros +.TH bindtags n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +bindtags \- Determine which bindings apply to a window, and order of evaluation +.SH SYNOPSIS +\fBbindtags \fIwindow \fR?\fItagList\fR? +.BE + +.SH DESCRIPTION +.PP +When a binding is created with the \fBbind\fR command, it is +associated either with a particular window such as \fB.a.b.c\fR, +a class name such as \fBButton\fR, the keyword \fBall\fR, or any +other string. +All of these forms are called \fIbinding tags\fR. +Each window contains a list of binding tags that determine how +events are processed for the window. +When an event occurs in a window, it is applied to each of the +window's tags in order: for each tag, the most specific binding +that matches the given tag and event is executed. +See the \fBbind\fR command for more information on the matching +process. +.PP +By default, each window has four binding tags consisting of the +name of the window, the window's class name, the name of the window's +nearest toplevel ancestor, and \fBall\fR, in that order. +Toplevel windows have only three tags by default, since the toplevel +name is the same as that of the window. +The \fBbindtags\fR command allows the binding tags for a window to be +read and modified. +.PP +If \fBbindtags\fR is invoked with only one argument, then the +current set of binding tags for \fIwindow\fR is returned as a list. +If the \fItagList\fR argument is specified to \fBbindtags\fR, +then it must be a proper list; the tags for \fIwindow\fR are changed +to the elements of the list. +The elements of \fItagList\fR may be arbitrary strings; however, +any tag starting with a dot is treated as the name of a window; if +no window by that name exists at the time an event is processed, +then the tag is ignored for that event. +The order of the elements in \fItagList\fR determines the order in +which binding scripts are executed in response to events. +For example, the command +.CS +\fBbindtags .b {all . Button .b}\fR +.CE +reverses the order in which binding scripts will be evaluated for +a button named \fB.b\fR so that \fBall\fR bindings are invoked +first, following by bindings for \fB.b\fR's toplevel (``.''), followed by +class bindings, followed by bindings for \fB.b\fR. +If \fItagList\fR is an empty list then the binding tags for \fIwindow\fR +are returned to the default state described above. +.PP +The \fBbindtags\fR command may be used to introduce arbitrary +additional binding tags for a window, or to remove standard tags. +For example, the command +.CS +\fBbindtags .b {.b TrickyButton . all}\fR +.CE +replaces the \fBButton\fR tag for \fB.b\fR with \fBTrickyButton\fR. +This means that the default widget bindings for buttons, which are +associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR, +but any bindings associated with \fBTrickyButton\fR (perhaps some +new button behavior) will apply. + +.SH "SEE ALSO" +bind + +.SH KEYWORDS +binding, event, tag diff --git a/doc/bitmap.n b/doc/bitmap.n new file mode 100644 index 0000000..8ede15a --- /dev/null +++ b/doc/bitmap.n @@ -0,0 +1,114 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) bitmap.n 1.10 96/03/29 14:48:41 +'\" +.so man.macros +.TH bitmap n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +bitmap \- Images that display two colors +.SH SYNOPSIS +\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? +.BE + +.SH DESCRIPTION +.PP +A bitmap is an image whose pixels can display either of two colors +or be transparent. +A bitmap image is defined by four things: a background color, +a foreground color, and two bitmaps, called the \fIsource\fR +and the \fImask\fR. +Each of the bitmaps specifies 0/1 values for a rectangular +array of pixels, and the two bitmaps must have the same +dimensions. +For pixels where the mask is zero, the image displays nothing, +producing a transparent effect. +For other pixels, the image displays the foreground color if +the source data is one and the background color if the source +data is zero. + +.SH "CREATING BITMAPS" +.PP +Like all images, bitmaps are created using the \fBimage create\fR +command. +Bitmaps support the following \fIoptions\fR: +.TP +\fB\-background \fIcolor\fR +Specifies a background color for the image in any of the standard +ways accepted by Tk. If this option is set to an empty string +then the background pixels will be transparent. This effect +is achieved by using the source bitmap as the mask bitmap, ignoring +any \fB\-maskdata\fR or \fB\-maskfile\fR options. +.TP +\fB\-data \fIstring\fR +Specifies the contents of the source bitmap as a string. +The string must adhere to X11 bitmap format (e.g., as generated +by the \fBbitmap\fR program). +If both the \fB\-data\fR and \fB\-file\fR options are specified, +the \fB\-data\fR option takes precedence. +.TP +\fB\-file \fIname\fR +\fIname\fR gives the name of a file whose contents define the +source bitmap. +The file must adhere to X11 bitmap format (e.g., as generated +by the \fBbitmap\fR program). +.TP +\fB\-foreground \fIcolor\fR +Specifies a foreground color for the image in any of the standard +ways accepted by Tk. +.TP +\fB\-maskdata \fIstring\fR +Specifies the contents of the mask as a string. +The string must adhere to X11 bitmap format (e.g., as generated +by the \fBbitmap\fR program). +If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, +the \fB\-maskdata\fR option takes precedence. +.TP +\fB\-maskfile \fIname\fR +\fIname\fR gives the name of a file whose contents define the +mask. +The file must adhere to X11 bitmap format (e.g., as generated +by the \fBbitmap\fR program). + +.SH "IMAGE COMMAND" +.PP +When a bitmap image is created, Tk also creates a new command +whose name is the same as the image. +This command may be used to invoke various operations +on the image. +It has the following general form: +.CS +\fIimageName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for bitmap images: +.TP +\fIimageName \fBcget\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 +\fBimage create bitmap\fR command. +.TP +\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options for the image. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the +\fBimage create bitmap\fR command. + +.SH KEYWORDS +bitmap, image diff --git a/doc/button.n b/doc/button.n new file mode 100644 index 0000000..776929f --- /dev/null +++ b/doc/button.n @@ -0,0 +1,176 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) button.n 1.40 97/10/31 12:58:48 +'\" +.so man.macros +.TH button n 4.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +button \- Create and manipulate button widgets +.SH SYNOPSIS +\fBbutton\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-cursor \-highlightthickness \-takefocus +\-activeforeground \-disabledforeground \-image \-text +\-anchor \-font \-justify \-textvariable +\-background \-foreground \-padx \-underline +\-bitmap \-highlightbackground \-pady \-wraplength +\-borderwidth \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +Specifies a Tcl command to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. +.OP \-default default Default +.VS +Specifies one of three states for the default ring: \fBnormal\fR, +\fBactive\fR, or \fBdisabled\fR. In active state, the button is drawn +with the platform specific appearance for a default button. In normal +state, the button is drawn with the platform specific appearance for a +non-default button, leaving enough space to draw the default button +appearance. The normal and active states will result in buttons of +the same size. In disabled state, the button is drawn with the +non-default button appearance without leaving space for the default +appearance. The disabled state may result in a smaller button than +the active state. +ring. +.VE +.OP \-height height Height +Specifies a desired height for the button. +If an image or bitmap is being displayed in the button then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in lines of text. +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. +.OP \-state state State +Specifies one of three states for the button: \fBnormal\fR, \fBactive\fR, +or \fBdisabled\fR. In normal state the button is displayed using the +\fBforeground\fR and \fBbackground\fR options. The active state is +typically used when the pointer is over the button. In active state +the button is displayed using the \fBactiveForeground\fR and +\fBactiveBackground\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 \fBdisabledForeground\fR and +\fBbackground\fR options determine how the button is displayed. +.OP \-width width Width +Specifies a desired width for the button. +If an image or bitmap is being displayed in the button then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in characters. +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. +.BE + +.SH DESCRIPTION +.PP +The \fBbutton\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 +or in the option database +to configure aspects of the button such as its colors, font, +text, and initial relief. The \fBbutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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 +or if wrapping occurs because of the \fBwrapLength\fR option) and +one of the characters may optionally be underlined using the +\fBunderline\fR option. +It can display itself in either of three different ways, according +to +the \fBstate\fR option; +it can be made to appear raised, sunken, or flat; +and it can be made to flash. When a user invokes the +button (by pressing mouse button 1 with the cursor over the +button), then the Tcl command specified in the \fB\-command\fR +option is invoked. + +.SH "WIDGET COMMAND" +.PP +The \fBbutton\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for button widgets: +.TP +\fIpathName \fBcget\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 \fBbutton\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBbutton\fR +command. +.TP +\fIpathName \fBflash\fR +Flash the button. This is accomplished by redisplaying the button +several times, alternating between active and normal colors. At +the end of the flash the button is left in the same normal/active +state as when the command was invoked. +This command is ignored if the button's state is \fBdisabled\fR. +.TP +\fIpathName \fBinvoke\fR +Invoke the Tcl command associated with the button, if there is one. +The return value is the return value from the Tcl command, or an +empty string if there is no command associated with the button. +This command is ignored if the button's state is \fBdisabled\fR. + +.SH "DEFAULT BINDINGS" +.PP +Tk automatically creates class bindings for buttons that give them +default behavior: +.IP [1] +A button activates whenever the mouse passes over it and deactivates +whenever the mouse leaves the button. +.VS +Under Windows, this binding is only active when mouse button 1 has +been pressed over the button. +.VE +.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] +When a button has the input focus, the space key causes the button +to be invoked. +.PP +If the button's state is \fBdisabled\fR then none of the above +actions occur: the button is completely non-responsive. +.PP +The behavior of buttons can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +button, widget diff --git a/doc/canvas.n b/doc/canvas.n new file mode 100644 index 0000000..4e1c779 --- /dev/null +++ b/doc/canvas.n @@ -0,0 +1,1576 @@ +'\" +'\" Copyright (c) 1992-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) canvas.n 1.58 97/10/31 12:58:45 +'\" +.so man.macros +.TH canvas n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +canvas \- Create and manipulate canvas widgets +.SH SYNOPSIS +\fBcanvas\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-background \-highlightthickness \-insertwidth \-takefocus +\-borderwidth \-insertbackground \-relief \-xscrollcommand +\-cursor \-insertborderwidth \-selectbackground \-yscrollcommand +\-highlightbackground \-insertofftime \-selectborderwidth +\-highlightcolor \-insertontime \-selectforeground +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-closeenough closeEnough CloseEnough +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. +.OP \-confine confine Confine +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 +\fBscrollRegion\fR argument. +Defaults to true, which means that the view will +be constrained within the scroll region. +.OP \-height height Height +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. +.OP \-scrollregion scrollRegion ScrollRegion +Specifies a list with four 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. +.OP \-width width width +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 +.OP \-xscrollincrement xScrollIncrement ScrollIncrement +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 \fBxScrollIncrement\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 \fBxScrollIncrement\fR. If the value of +this option is less than or equal to zero, then horizontal scrolling +is unconstrained. +.OP \-yscrollincrement yScrollIncrement ScrollIncrement +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 \fByScrollIncrement\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 \fByScrollIncrement\fR. If the value of +this option is less than or equal to zero, then vertical scrolling +is unconstrained. +.BE + +.SH INTRODUCTION +.PP +The \fBcanvas\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 or in the option database +to configure aspects of the canvas such as its colors and 3-D relief. +The \fBcanvas\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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-colored) and commands may +be associated with items in much the same way that the \fBbind\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 behaviors defined by +the Tcl scripts bound to them. + +.SH "DISPLAY LIST" +.PP +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. +.PP +Window items are an exception to the above rules. The underlying +window systems require them always to be drawn on top of other items. +In addition, the stacking order of window items +is not affected by any of the canvas widget commands; you must use +the \fBraise\fR and \fBlower\fR Tk commands instead. + +.SH "ITEM IDS AND TAGS" +.PP +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 \fBall\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 \fBcurrent\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 \fBcurrent\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 behavior 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" +.PP +All coordinates related to canvases are stored as floating-point +numbers. +Coordinates and distances are specified in screen units, +which are floating-point numbers optionally followed +by one of several letters. +If no letter is supplied then the distance is in pixels. +If the letter is \fBm\fR then the distance is in millimeters on +the screen; if it is \fBc\fR then the distance is in centimeters; +\fBi\fR means inches, and \fBp\fR means printers points (1/72 inch). +Larger y-coordinates refer to points lower on the screen; larger +x-coordinates refer to points farther to the right. + +.SH TRANSFORMATIONS +.PP +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 +\fBxview\fR and \fByview\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" +.PP +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; if you +define new types of text-like items, it would be advisable to +support as many of these forms as practical. +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 +\fBend\fR +Refers to the character just after the last one in the item +(same as the number of characters in the item). +.TP 10 +\fBinsert\fR +Refers to the character just before which the insertion cursor +is drawn in this item. +.TP 10 +\fBsel.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 +\fBsel.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 +\fB@\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" +.PP +The \fBcanvas\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +The following widget commands are possible for canvas widgets: +.TP +\fIpathName \fBaddtag \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\fR 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 +\fBabove \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 +\fBall\fR +Selects all the items in the canvas. +.TP +\fBbelow \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 +\fBclosest \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 +\fBenclosed\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 +\fBoverlapping\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 +\fBwithtag \fItagOrId\fR +Selects all the items given by \fItagOrId\fR. +.RE +.TP +\fIpathName \fBbbox \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 \fBbind \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 \fBbind\fR command except that +it operates on items in a canvas rather than entire widgets. +See the \fBbind\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 +.VS +The only events for which bindings may be specified are those related to +the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, +\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. +The handling of events in canvases uses the current item defined in ITEM +IDS AND TAGS above. \fBEnter\fR and \fBLeave\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 \fBEnter\fR and \fBLeave\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 \fBfocus\fR widget command below for more on this). If a +virtual event is used in a binding, that binding can trigger only if the +virtual event is defined by an underlying mouse-related or +keyboard-related event. +.VE +.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 \fBall\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 \fBcontinue\fR command in a binding script terminates that +script, and a \fBbreak\fR command terminates that script +and skips any remaining scripts for the event, just as for the +\fBbind\fR command. +.PP +If bindings have been created for a canvas window using the \fBbind\fR +command, then they are invoked in addition to bindings created for +the canvas's items using the \fBbind\fR widget command. +The bindings for items will be invoked before any of the bindings +for the window as a whole. +.RE +.TP +\fIpathName \fBcanvasx \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 \fBcanvasy \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 \fBcget\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 \fBcanvas\fR +command. +.TP +\fIpathName \fBconfigure ?\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBcanvas\fR +command. +.TP +\fIpathName\fR \fBcoords \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 \fBcreate \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 \fBtype\fR depends +on \fBtype\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 \fBdchars \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 \fBdelete \fR?\fItagOrId tagOrId ...\fR? +Delete each of the items given by each \fItagOrId\fR, and return +an empty string. +.TP +\fIpathName \fBdtag \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 \fBfind \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 \fBaddtag\fR command. +The items are returned in stacking order, with the lowest item first. +.TP +\fIpathName \fBfocus \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 \fBfocus\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 \fBfocus\fR widget +command with the \fBfocus\fR command to set the focus window to +the canvas (if it wasn't there already). +.RE +.TP +\fIpathName \fBgettags\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, or if the item +contains no tags, then an empty string is returned. +.TP +\fIpathName \fBicursor \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 \fBfocus\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 \fBindex \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 \fBinsert \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 \fBitemcget\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 \fBcget\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 \fBcreate\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 \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \fBconfigure\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 no \fIoption\fR is specified, returns a list describing all of +the available options for the first item given by \fItagOrId\fR +(see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBcreate\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 \fBlower \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. +Note: this command has no effect on window items. Window items always +obscure other item types, and the stacking order of window items is +determined by the \fBraise\fR and \fBlower\fR commands, not the +\fBraise\fR and \fBlower\fR widget commands for canvases. +This command returns an empty string. +.TP +\fIpathName \fBmove \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 \fBpostscript \fR?\fIoption value option value ...\fR? +Generate a Postscript representation for part or all of the canvas. +If the \fB\-file\fR option is specified then the Postscript is written +to a file and an empty string is returned; otherwise the Postscript +is returned as the result of the command. +.VS +If the interpreter that owns the canvas is marked as safe, the operation +will fail because safe interpreters are not allowed to write files. +If the \fB\-channel\fR option is specified, the argument denotes the name +of a channel already opened for writing. The Postscript is written to +that channel, and the channel is left open for further writing at the end +of the operation. +.VE +The Postscript is created in Encapsulated Postscript form using +version 3.0 of the Document Structuring Conventions. +Note: by default Postscript is only generated for information that +appears in the canvas's window on the screen. If the canvas is +freshly created it may still have its initial size of 1x1 pixel +so nothing will appear in the Postscript. To get around this problem +either invoke the "update" command to wait for the canvas window +to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR +options to specify the area of the canvas to print. +The \fIoption\fR\-\fIvalue\fR argument pairs provide additional +information to control the generation of Postscript. The following +options are supported: +.RS +.TP +\fB\-colormap \fIvarName\fR +\fIVarName\fR must be the name of an array variable +that specifies a color mapping to use in the Postscript. +Each element of \fIvarName\fR must consist of Postscript +code to set a particular color value (e.g. ``\fB1.0 1.0 0.0 setrgbcolor\fR''). +When outputting color information in the Postscript, Tk checks +to see if there is an element of \fIvarName\fR with the same +name as the color. +If so, Tk uses the value of the element as the Postscript command +to set the color. +If this option hasn't been specified, or if there isn't an entry +in \fIvarName\fR for a given color, then Tk uses the red, green, +and blue intensities from the X color. +.TP +\fB\-colormode \fImode\fR +Specifies how to output color information. \fIMode\fR must be either +\fBcolor\fR (for full color output), \fBgray\fR (convert all colors +to their gray-scale equivalents) or \fBmono\fR (convert all colors +to black or white). +.TP +\fB\-file \fIfileName\fR +Specifies the name of the file in which to write the Postscript. +If this option isn't specified then the Postscript is returned as the +result of the command instead of being written to a file. +.TP +\fB\-fontmap \fIvarName\fR +\fIVarName\fR must be the name of an array variable +that specifies a font mapping to use in the Postscript. +Each element of \fIvarName\fR must consist of a Tcl list with +two elements, which are the name and point size of a Postscript font. +When outputting Postscript commands for a particular font, Tk +checks to see if \fIvarName\fR contains an element with the same +name as the font. +If there is such an element, then the font information contained in +that element is used in the Postscript. +Otherwise Tk attempts to guess what Postscript font to use. +Tk's guesses generally only work for well-known fonts such as +Times and Helvetica and Courier, and only if the X font name does not +omit any dashes up through the point size. +For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but +\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to +parse the font name). +.TP +\fB\-height \fIsize\fR +Specifies the height of the area of the canvas to print. +Defaults to the height of the canvas window. +.TP +\fB\-pageanchor \fIanchor\fR +Specifies which point of the printed area of the canvas should appear over +the positioning point on the page (which is given by the \fB\-pagex\fR +and \fB\-pagey\fR options). +For example, \fB\-pageanchor n\fR means that the top center of the +area of the canvas being printed (as it appears in the canvas window) +should be over the positioning point. Defaults to \fBcenter\fR. +.TP +\fB\-pageheight \fIsize\fR +Specifies that the Postscript should be scaled in both x and y so +that the printed area is \fIsize\fR high on the Postscript page. +\fISize\fR consists of a floating-point number followed by +\fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, +or \fBp\fR or nothing for printer's points (1/72 inch). +Defaults to the height of the printed area on the screen. +If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then +the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling +is not implemented). +.TP +\fB\-pagewidth \fIsize\fR +Specifies that the Postscript should be scaled in both x and y so +that the printed area is \fIsize\fR wide on the Postscript page. +\fISize\fR has the same form as for \fB\-pageheight\fR. +Defaults to the width of the printed area on the screen. +If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then +the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling +is not implemented). +.TP +\fB\-pagex \fIposition\fR +\fIPosition\fR gives the x-coordinate of the positioning point on +the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. +Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options +to determine where the printed area appears on the Postscript page. +Defaults to the center of the page. +.TP +\fB\-pagey \fIposition\fR +\fIPosition\fR gives the y-coordinate of the positioning point on +the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. +Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options +to determine where the printed area appears on the Postscript page. +Defaults to the center of the page. +.TP +\fB\-rotate \fIboolean\fR +\fIBoolean\fR specifies whether the printed area is to be rotated 90 +degrees. +In non-rotated output the x-axis of the printed area runs along +the short dimension of the page (``portrait'' orientation); +in rotated output the x-axis runs along the long dimension of the +page (``landscape'' orientation). +Defaults to non-rotated. +.TP +\fB\-width \fIsize\fR +Specifies the width of the area of the canvas to print. +Defaults to the width of the canvas window. +.TP +\fB\-x \fIposition\fR +Specifies the x-coordinate of the left edge of the area of the +canvas that is to be printed, in canvas coordinates, not window +coordinates. +Defaults to the coordinate of the left edge of the window. +.TP +\fB\-y \fIposition\fR +Specifies the y-coordinate of the top edge of the area of the +canvas that is to be printed, in canvas coordinates, not window +coordinates. +Defaults to the coordinate of the top edge of the window. +.RE +.TP +\fIpathName \fBraise \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. +Note: this command has no effect on window items. Window items always +obscure other item types, and the stacking order of window items is +determined by the \fBraise\fR and \fBlower\fR commands, not the +\fBraise\fR and \fBlower\fR widget commands for canvases. +This command returns an empty string. +.TP +\fIpathName \fBscale \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 \fBscan\fR \fIoption args\fR +This command is used to implement scanning on canvases. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark \fIx y\fR +Records \fIx\fR and \fIy\fR and the canvas's current view; used +in conjunction with later \fBscan dragto\fR commands. +Typically this command is associated with a mouse button press in +the widget and \fIx\fR and \fIy\fR are the coordinates of the +mouse. It returns an empty string. +.TP +\fIpathName \fBscan dragto \fIx y\fR. +This command computes the difference between its \fIx\fR and \fIy\fR +arguments (which are typically mouse coordinates) and the \fIx\fR and +\fIy\fR arguments to the last \fBscan 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 canvas at high speed through its window. The return +value is an empty string. +.RE +.TP +\fIpathName \fBselect \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 \fBselect 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 \fBselect to\fR commands. +If the selection isn't currently in \fItagOrId\fR then +this command behaves the same as the \fBselect to\fR widget +command. +Returns an empty string. +.TP +\fIpathName \fBselect 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 \fBselect 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 \fBselect to\fR +commands. +Returns an empty string. +.TP +\fIpathName \fBselect 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 \fBselect 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 \fBselect adjust\fR +or \fBselect 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 \fBtype\fI tagOrId\fR +Returns the type of the item given by \fItagOrId\fR, such as +\fBrectangle\fR or \fBtext\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 \fBxview \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 \fBxview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the horizontal span that is visible in the window. +For example, if the first element is .2 and the second element is .6, +20% of the canvas's area (as defined by the \fB\-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 \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview 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 \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units +of the \fBxScrollIncrement\fR option, if it is greater than zero, +or in units of one-tenth the window's width otherwise. +If \fIwhat is \fBpages\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 \fByview \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 \fByview\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 \fB\-scrollregion\fR +option) is visible in the window. +These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR +option. +.TP +\fIpathName \fByview 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 \fByview 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 \fBunits\fR or \fBpages\fR. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units +of the \fByScrollIncrement\fR option, if it is greater than zero, +or in units of one-tenth the window's height otherwise. +If \fIwhat\fR is \fBpages\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" +.PP +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 \fBcreate\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 +\fBcreate\fR and \fBitemconfigure\fR widget commands. +Most items don't support indexing or selection or the commands +related to them, such as \fBindex\fR and \fBinsert\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" +.PP +Items of type \fBarc\fR appear on the display as arc-shaped regions. +An arc is a section of an oval delimited by two angles (specified +by the \fB\-start\fR and \fB\-extent\fR options) and displayed in +one of several ways (specified by the \fB\-style\fR option). +Arcs are created with widget commands of the following form: +.CS +\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for arcs: +.TP +\fB\-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 \fB\-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 +\fB\-fill \fIcolor\fR +Fill the region of the arc with \fIcolor\fR. +\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. +If \fIcolor\fR is an empty string (the default), then +then the arc will not be filled. +.TP +\fB\-outline \fIcolor\fR +\fIColor\fR specifies a color to use for drawing the arc's +outline; it may have any of the forms accepted by \fBTk_GetColor\fR. +This option defaults to \fBblack\fR. If \fIcolor\fR is specified +as an empty string then no outline is drawn for the arc. +.TP +\fB\-outlinestipple \fIbitmap\fR +Indicates that the outline for the arc should be drawn with a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If the \fB\-outline\fR option hasn't been specified then this option +has no effect. +If \fIbitmap\fR is an empty string (the default), then the outline is drawn +in a solid fashion. +.TP +\fB\-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 +\fB\-stipple \fIbitmap\fR +Indicates that the arc should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If the \fB\-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. +.TP +\fB\-style \fItype\fR +Specifies how to draw the arc. If \fItype\fR is \fBpieslice\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 \fBchord\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. +If \fItype\fR is \fBarc\fR then the arc's region consists of +a section of the perimeter alone. +In this last case the \fB\-fill\fR option is ignored. +.TP +\fB\-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 +\fB\-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 \fB\-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" +.PP +Items of type \fBbitmap\fR appear on the display as images with +two colors, foreground and background. +Bitmaps are created with widget commands of the following form: +.CS +\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR? +.CE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the bitmap on the display (see the \fB\-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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for bitmaps: +.TP +\fB\-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the bitmap relative to the +positioning point for the item; it may have any of the forms +accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR +is \fBcenter\fR then the bitmap is centered on the point; if +\fIanchorPos\fR is \fBn\fR then the bitmap will be drawn so that +its top center point is at the positioning point. +This option defaults to \fBcenter\fR. +.TP +\fB\-background \fIcolor\fR +Specifies a color to use for each of the bitmap pixels +whose value is 0. +\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. +If this option isn't specified, or if it is specified as an empty +string, then nothing is displayed where the bitmap pixels are 0; this +produces a transparent effect. +.TP +\fB\-bitmap \fIbitmap\fR +Specifies the bitmap to display in the item. +\fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR. +.TP +\fB\-foreground \fIcolor\fR +Specifies a color to use for each of the bitmap pixels +whose value is 1. +\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and +defaults to \fBblack\fR. +.TP +\fB\-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" +.PP +Items of type \fBimage\fR are used to display images on a +canvas. +Images are created with widget commands of the following form: +.CS +\fIpathName \fBcreate image \fIx y \fR?\fIoption value option value ...\fR? +.CE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the image on the display (see the \fB\-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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for images: +.TP +\fB\-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the image relative to the +positioning point for the item; it may have any of the forms +accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR +is \fBcenter\fR then the image is centered on the point; if +\fIanchorPos\fR is \fBn\fR then the image will be drawn so that +its top center point is at the positioning point. +This option defaults to \fBcenter\fR. +.TP +\fB\-image \fIname\fR +Specifies the name of the image to display in the item. +This image must have been created previously with the +\fBimage create\fR command. +.TP +\fB\-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" +.PP +Items of type \fBline\fR appear on the display as one or more connected +line segments or curves. +Lines are created with widget commands of the following form: +.CS +\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for lines: +.TP +\fB\-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 \fBnone\fR (for no arrowheads), +\fBfirst\fR (for an arrowhead at the first point of the line), +\fBlast\fR (for an arrowhead at the last point of the line), or +\fBboth\fR (for arrowheads at both ends). +This option defaults to \fBnone\fR. +.TP +\fB\-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 +\fB\-capstyle \fIstyle\fR +Specifies the ways in which caps are to be drawn at the endpoints +of the line. +\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR +(\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). +If this option isn't specified then it defaults to \fBbutt\fR. +Where arrowheads are drawn the cap style is ignored. +.TP +\fB\-fill \fIcolor\fR +\fIColor\fR specifies a color to use for drawing the line; it may have +any of the forms acceptable to \fBTk_GetColor\fR. It may also be an +empty string, in which case the line will be transparent. +This option defaults to \fBblack\fR. +.TP +\fB\-joinstyle \fIstyle\fR +Specifies the ways in which joints are to be drawn at the vertices +of the line. +\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR +(\fBbevel\fR, \fBmiter\fR, or \fBround\fR). +If this option isn't specified then it defaults to \fBmiter\fR. +If the line only contains two points then this option is +irrelevant. +.TP +\fB\-smooth \fIboolean\fR +\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR. +It indicates whether or not the line should be drawn as a curve. +If so, the line is rendered as a set of parabolic 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 +\fB\-splinesteps \fInumber\fR +Specifies the degree of smoothness desired for curves: each spline +will be approximated with \fInumber\fR line segments. This +option is ignored unless the \fB\-smooth\fR option is true. +.TP +\fB\-stipple \fIbitmap\fR +Indicates that the line should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If \fIbitmap\fR is an empty string (the default), then filling is +done in a solid fashion. +.TP +\fB\-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 +\fB\-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" +.PP +Items of type \fBoval\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: +.CS +\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for ovals: +.TP +\fB\-fill \fIcolor\fR +Fill the area of the oval with \fIcolor\fR. +\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. +If \fIcolor\fR is an empty string (the default), then +then the oval will not be filled. +.TP +\fB\-outline \fIcolor\fR +\fIColor\fR specifies a color to use for drawing the oval's +outline; it may have any of the forms accepted by \fBTk_GetColor\fR. +This option defaults to \fBblack\fR. +If \fIcolor\fR is an empty string then no outline will be +drawn for the oval. +.TP +\fB\-stipple \fIbitmap\fR +Indicates that the oval should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If the \fB\-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. +.TP +\fB\-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 +\fB\-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 \fB\-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" +.PP +Items of type \fBpolygon\fR appear as polygonal or curved filled regions +on the display. +Polygons are created with widget commands of the following form: +.CS +\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for polygons: +.TP +\fB\-fill \fIcolor\fR +\fIColor\fR specifies a color to use for filling the area of the +polygon; it may have any of the forms acceptable to \fBTk_GetColor\fR. +If \fIcolor\fR is an empty string then the polygon will be +transparent. +This option defaults to \fBblack\fR. +.TP +\fB\-outline \fIcolor\fR +\fIColor\fR specifies a color to use for drawing the polygon's +outline; it may have any of the forms accepted by \fBTk_GetColor\fR. +If \fIcolor\fR is an empty string then no outline will be +drawn for the polygon. +This option defaults to empty (no outline). +.TP +\fB\-smooth \fIboolean\fR +\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR +It indicates whether or not the polygon should be drawn with a +curved perimeter. +If so, the outline of the polygon becomes a set of parabolic 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 +\fB\-splinesteps \fInumber\fR +Specifies the degree of smoothness desired for curves: each spline +will be approximated with \fInumber\fR line segments. This +option is ignored unless the \fB\-smooth\fR option is true. +.TP +\fB\-stipple \fIbitmap\fR +Indicates that the polygon should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If \fIbitmap\fR is an empty string (the default), then filling is +done in a solid fashion. +.TP +\fB\-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 +\fB\-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 \fB\-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 \fBfind closest\fR and +\fBfind 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" +.PP +Items of type \fBrectangle\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: +.CS +\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for rectangles: +.TP +\fB\-fill \fIcolor\fR +Fill the area of the rectangle with \fIcolor\fR, which may be +specified in any of the forms accepted by \fBTk_GetColor\fR. +If \fIcolor\fR is an empty string (the default), +then the rectangle will not be filled. +.TP +\fB\-outline \fIcolor\fR +Draw an outline around the edge of the rectangle in \fIcolor\fR. +\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. +This option defaults to \fBblack\fR. +If \fIcolor\fR is an empty string then no outline will be +drawn for the rectangle. +.TP +\fB\-stipple \fIbitmap\fR +Indicates that the rectangle should be filled in a stipple pattern; +\fIbitmap\fR specifies the stipple pattern to use, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If the \fB\-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. +.TP +\fB\-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 +\fB\-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 \fB\-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" +.PP +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: \fBdchars\fR, +\fBfocus\fR, \fBicursor\fR, \fBindex\fR, \fBinsert\fR, +\fBselect\fR. +Text items are created with widget commands of the following +form: +.CS +\fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR? +.CE +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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for text items: +.TP +\fB\-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the text relative to the +positioning point for the text; it may have any of the forms +accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR +is \fBcenter\fR then the text is centered on the point; if +\fIanchorPos\fR is \fBn\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 \fBcenter\fR. +.TP +\fB\-fill \fIcolor\fR +\fIColor\fR specifies a color to use for filling the text characters; +it may have any of the forms accepted by \fBTk_GetColor\fR. +If this option isn't specified then it defaults to \fBblack\fR. +.TP +\fB\-font \fIfontName\fR +Specifies the font to use for the text item. +\fIFontName\fR may be any string acceptable to \fBTk_GetFontStruct\fR. +If this option isn't specified, it defaults to a system-dependent +font. +.TP +\fB\-justify \fIhow\fR +Specifies how to justify the text within its bounding region. +\fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, +or \fBcenter\fR. +This option will only matter if the text is displayed as multiple +lines. +If the option is omitted, it defaults to \fBleft\fR. +.TP +\fB\-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, in any of the +forms accepted by \fBTk_GetBitmap\fR. +If \fIbitmap\fR is an empty string (the default) then the text +is drawn in a solid fashion. +.TP +\fB\-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 +\fB\-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 +\fBinsert\fR and \fBdelete\fR widget commands. +This option defaults to an empty string. +.TP +\fB\-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" +.PP +Items of type \fBwindow\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: +.CS +\fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR? +.CE +The arguments \fIx\fR and \fIy\fR specify the coordinates of a +point used to position the window on the display (see the \fB\-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 \fBitemconfigure\fR widget commands to change the item's +configuration. +The following options are supported for window items: +.TP +\fB\-anchor \fIanchorPos\fR +\fIAnchorPos\fR tells how to position the window relative to the +positioning point for the item; it may have any of the forms +accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR +is \fBcenter\fR then the window is centered on the point; if +\fIanchorPos\fR is \fBn\fR then the window will be drawn so that +its top center point is at the positioning point. +This option defaults to \fBcenter\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the height to assign to the item's window. +\fIPixels\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 +\fB\-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 +\fB\-width \fIpixels\fR +Specifies the width to assign to the item's window. +\fIPixels\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 +\fB\-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. +.PP +Note: due to restrictions in the ways that windows are managed, it is not +possible to draw other graphical items (such as lines and images) on top +of window items. A window item always obscures any graphics that +overlap it, regardless of their order in the display list. + +.SH "APPLICATION-DEFINED ITEM TYPES" +.PP +It is possible for individual applications to define new item +types for canvas widgets using C code. +See the documentation for \fBTk_CreateItemType\fR. + +.SH BINDINGS +.PP +In the current implementation, new canvases are not given any +default behavior: you'll have to execute explicit Tcl commands +to give the canvas its behavior. + +.SH CREDITS +.PP +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 KEYWORDS +canvas, widget diff --git a/doc/checkbutton.n b/doc/checkbutton.n new file mode 100644 index 0000000..b06e7fc --- /dev/null +++ b/doc/checkbutton.n @@ -0,0 +1,238 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) checkbutton.n 1.40 96/11/20 12:51:21 +'\" +.so man.macros +.TH checkbutton n 4.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +checkbutton \- Create and manipulate checkbutton widgets +.SH SYNOPSIS +\fBcheckbutton\fI pathName \fR?\fIoptions\fR? +.SO +\-activebackground \-cursor \-highlightthickness \-takefocus +\-activeforeground \-disabledforeground \-image \-text +\-anchor \-font \-justify \-textvariable +\-background \-foreground \-padx \-underline +\-bitmap \-highlightbackground \-pady \-wraplength +\-borderwidth \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +Specifies a Tcl 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 (\fB\-variable\fR option) will +be updated before the command is invoked. +.OP \-height height Height +Specifies a desired height for the button. +If an image or bitmap is being displayed in the button then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in lines of text. +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. +.OP \-indicatoron indicatorOn IndicatorOn +Specifies whether or not the indicator should be drawn. Must be a +proper boolean value. If false, the \fBrelief\fR option is +ignored and the widget's relief is always sunken if the widget is +selected and raised otherwise. +.OP \-offvalue offValue Value +Specifies value to store in the button's associated variable whenever +this button is deselected. Defaults to ``0''. +.OP \-onvalue onValue Value +Specifies value to store in the button's associated variable whenever +this button is selected. Defaults to ``1''. +.OP \-selectcolor selectColor Background +Specifies a background color to use when the button is selected. +If \fBindicatorOn\fR is true then the color applies to the indicator. +Under Windows, this color is used as the background for the indicator +regardless of the select state. +If \fBindicatorOn\fR is false, this color is used as the background +for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, +whenever the widget is selected. +If specified as an empty string then no special color is used for +displaying when the widget is selected. +.OP \-selectimage selectImage SelectImage +Specifies an image to display (in place of the \fBimage\fR option) +when the checkbutton is selected. +This option is ignored unless the \fBimage\fR option has been +specified. +.OP \-state state State +Specifies one of three states for the checkbutton: \fBnormal\fR, \fBactive\fR, +or \fBdisabled\fR. In normal state the checkbutton is displayed using the +\fBforeground\fR and \fBbackground\fR options. The active state is +typically used when the pointer is over the checkbutton. In active state +the checkbutton is displayed using the \fBactiveForeground\fR and +\fBactiveBackground\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 \fBdisabledForeground\fR and +\fBbackground\fR options determine how the checkbutton is displayed. +.OP \-variable variable Variable +Specifies name of global variable to set to indicate whether +or not this button is selected. Defaults to the name of the +button within its parent (i.e. the last element of the button +window's path name). +.OP \-width width Width +Specifies a desired width for the button. +If an image or bitmap is being displayed in the button then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in characters. +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. +.BE + +.SH DESCRIPTION +.PP +The \fBcheckbutton\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 +or in the option database +to configure aspects of the checkbutton such as its colors, font, +text, and initial relief. The \fBcheckbutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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 +or if wrapping occurs because of the \fBwrapLength\fR option) and +one of the characters may optionally be underlined using the +\fBunderline\fR option. +A checkbutton has +all of the behavior of a simple button, including the +following: it can display itself in either of three different +ways, according to the \fBstate\fR option; +it can be made to appear +raised, sunken, or flat; it can be made to flash; and it invokes +a Tcl 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 +.VS +drawn with a selected appearance, and +a Tcl variable associated with the checkbutton is set to a particular +value (normally 1). +Under Unix, the indicator is drawn with a sunken relief and a special +color. Under Windows, the indicator is drawn with a check mark inside. +If the checkbutton is not selected, then the indicator is drawn with a +deselected appearance, and the associated variable is +set to a different value (typically 0). +Under Unix, the indicator is drawn with a raised relief and no special +color. Under Windows, the indicator is drawn without a check mark inside. +.VE +By default, the name of the variable associated with a checkbutton is the +same as the \fIname\fR used to create the checkbutton. +The variable name, and the ``on'' and ``off'' values stored in it, +may be modified with options on the command line or in the option +database. +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. +In addition, each checkbutton monitors its associated variable and +automatically selects and deselects itself when the variables value +changes to and from the button's ``on'' value. + +.SH "WIDGET COMMAND" +.PP +The \fBcheckbutton\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for checkbutton widgets: +.TP +\fIpathName \fBcget\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 \fBcheckbutton\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBcheckbutton\fR +command. +.TP +\fIpathName \fBdeselect\fR +Deselects the checkbutton and sets the associated variable to its ``off'' +value. +.TP +\fIpathName \fBflash\fR +Flashes the checkbutton. This is accomplished by redisplaying the checkbutton +several times, alternating between active and normal colors. At +the end of the flash the checkbutton is left in the same normal/active +state as when the command was invoked. +This command is ignored if the checkbutton's state is \fBdisabled\fR. +.TP +\fIpathName \fBinvoke\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 Tcl command associated with the checkbutton, if there is one. +The return value is the return value from the Tcl command, or an +empty string if there is no command associated with the checkbutton. +This command is ignored if the checkbutton's state is \fBdisabled\fR. +.TP +\fIpathName \fBselect\fR +Selects the checkbutton and sets the associated variable to its ``on'' +value. +.TP +\fIpathName \fBtoggle\fR +Toggles the selection state of the button, redisplaying it and +modifying its associated variable to reflect the new state. + +.SH BINDINGS +.PP +Tk automatically creates class bindings for checkbuttons that give them +the following default behavior: +.VS +.IP [1] +On Unix systems, a checkbutton activates whenever the mouse passes +over it and deactivates whenever the mouse leaves the checkbutton. On +Mac and Windows systems, when mouse button 1 is pressed over a +checkbutton, the button activates whenever the mouse pointer is inside +the button, and deactivates whenever the mouse pointer leaves the +button. +.VE +.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). +.VS +.IP [3] +When a checkbutton has the input focus, the space key causes the checkbutton +to be invoked. Under Windows, there are additional key bindings; plus +(+) and equal (=) select the button, and minus (-) deselects the button. +.VE +.PP +If the checkbutton's state is \fBdisabled\fR then none of the above +actions occur: the checkbutton is completely non-responsive. +.PP +The behavior of checkbuttons can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +checkbutton, widget diff --git a/doc/chooseColor.n b/doc/chooseColor.n new file mode 100644 index 0000000..8e4f210 --- /dev/null +++ b/doc/chooseColor.n @@ -0,0 +1,49 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) chooseColor.n 1.4 96/09/19 17:01:44 +'\" +.so man.macros +.TH tk_chooseColor n 4.2 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_chooseColor \- pops up a dialog box for the user to select a color. +.PP +.SH SYNOPSIS +\fBtk_chooseColor \fR?\fIoption value ...\fR? +.BE + +.SH DESCRIPTION +.PP +The procedure \fBtk_chooseColor\fR pops up a dialog box for the +user to select a color. The following \fIoption\-value\fR pairs are +possible as command line arguments: +.TP +\fB\-initialcolor\fR \fIcolor\fR +Specifies the color to display in the color dialog when it pops +up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR +function. +.TP +\fB\-parent\fR \fIwindow\fR +Makes \fIwindow\fR the logical parent of the color dialog. The color +dialog is displayed on top of its parent window. +.TP +\fB\-title\fR \fItitleString\fR +Specifies a string to display as the title of the dialog box. If this +option is not specified, then a default title will be displayed. +.LP +If the user selects a color, \fBtk_chooseColor\fR will return the +name of the color in a form acceptable to \fBTk_GetColor\fR. If the +user cancels the operation, both commands will return the empty +string. +.SH EXAMPLE +.CS +button .b \-fg [tk_chooseColor \-initialcolor gray \-title "Choose color"] +.CE + +.SH KEYWORDS +color selection dialog diff --git a/doc/clipboard.n b/doc/clipboard.n new file mode 100644 index 0000000..770463d --- /dev/null +++ b/doc/clipboard.n @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) clipboard.n 1.9 96/03/26 18:21:12 +'\" +.so man.macros +.TH clipboard n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +clipboard \- Manipulate Tk clipboard +.SH SYNOPSIS +\fBclipboard \fIoption\fR ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command provides a Tcl interface to the Tk clipboard, +which stores data for later retrieval using the selection mechanism. +In order to copy data into the clipboard, \fBclipboard clear\fR must +be called, followed by a sequence of one or more calls to \fBclipboard +append\fR. To ensure that the clipboard is updated atomically, all +appends should be completed before returning to the event loop. +.PP +The first argument to \fBclipboard\fR determines the format of the +rest of the arguments and the behavior of the command. The following +forms are currently supported: +.PP +.TP +\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR? +Claims ownership of the clipboard on \fIwindow\fR's display and removes +any previous contents. \fIWindow\fR defaults to ``.''. Returns an +empty string. +.TP +\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR +Appends \fIdata\fR to the clipboard on \fIwindow\fR's +display in the form given by \fItype\fR with the representation given +by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's +display. +.RS +.PP +\fIType\fR specifies the form in which the selection is to be returned +(the desired ``target'' for conversion, in ICCCM terminology), and +should be an atom name such as STRING or FILE_NAME; see the +Inter-Client Communication Conventions Manual for complete details. +\fIType\fR defaults to STRING. +.PP +The \fIformat\fR argument specifies the representation that should be +used to transmit the selection to the requester (the second column of +Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is +STRING, the selection is transmitted as 8-bit ASCII characters. If +\fIformat\fR is ATOM, then the \fIdata\fR is +divided into fields separated by white space; each field is converted +to its atom value, and the 32-bit atom value is transmitted instead of +the atom name. For any other \fIformat\fR, \fIdata\fR is divided +into fields separated by white space and each +field is converted to a 32-bit integer; an array of integers is +transmitted to the selection requester. Note that strings passed to +\fBclipboard append\fR are concatenated before conversion, so the +caller must take care to ensure appropriate spacing across string +boundaries. All items appended to the clipboard with the same +\fItype\fR must have the same \fIformat\fR. +.PP +The \fIformat\fR argument is needed only for compatibility with +clipboard requesters that don't use Tk. If the Tk toolkit is being +used to retrieve the CLIPBOARD selection then the value is converted back to +a string at the requesting end, so \fIformat\fR is +irrelevant. +.PP +A \fB\-\|\-\fR argument may be specified to mark the end of options: the +next argument will always be used as \fIdata\fR. +This feature may be convenient if, for example, \fIdata\fR starts +with a \fB\-\fR. +.RE + +.SH KEYWORDS +clear, format, clipboard, append, selection, type diff --git a/doc/destroy.n b/doc/destroy.n new file mode 100644 index 0000000..9bcdc5c --- /dev/null +++ b/doc/destroy.n @@ -0,0 +1,34 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) destroy.n 1.14 96/12/12 17:54:59 +'\" +.so man.macros +.TH destroy n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +destroy \- Destroy one or more windows +.SH SYNOPSIS +\fBdestroy \fR?\fIwindow window ...\fR? +.BE + +.SH DESCRIPTION +.VS +.PP +This command deletes the windows given by the +\fIwindow\fR arguments, plus all of their descendants. +If a \fIwindow\fR ``.'' is deleted then the entire application +will be destroyed. +The \fIwindow\fRs are destroyed in order, and if an error occurs +in destroying a window the command aborts without destroying the +remaining windows. +No error is returned if \fIwindow\fR does not exist. +.VE + +.SH KEYWORDS +application, destroy, window diff --git a/doc/dialog.n b/doc/dialog.n new file mode 100644 index 0000000..06dc0e9 --- /dev/null +++ b/doc/dialog.n @@ -0,0 +1,65 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) dialog.n 1.9 96/09/06 09:20:58 +'\" +.so man.macros +.TH tk_dialog n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_dialog \- Create modal dialog and wait for response +.SH SYNOPSIS +\fBtk_dialog \fIwindow title text bitmap default string string ...\fR +.BE + +.SH DESCRIPTION +.PP +This procedure is part of the Tk script library. +Its arguments describe a dialog box: +.TP +\fIwindow\fR +Name of top-level window to use for dialog. Any existing window +by this name is destroyed. +.TP +\fItitle\fR +Text to appear in the window manager's title bar for the dialog. +.TP +\fItext\fR +Message to appear in the top portion of the dialog box. +.TP +\fIbitmap\fR +If non-empty, specifies a bitmap to display in the top portion of +the dialog, to the left of the text. +If this is an empty string then no bitmap is displayed in the dialog. +.TP +\fIdefault\fR +If this is an integer greater than or equal to zero, then it gives +the index of the button that is to be the default button for the dialog +(0 for the leftmost button, and so on). +If less than zero or an empty string then there won't be any default +button. +.TP +\fIstring\fR +There will be one button for each of these arguments. +Each \fIstring\fR specifies text to display in a button, +in order from left to right. +.PP +After creating a dialog box, \fBtk_dialog\fR waits for the user to +select one of the buttons either by clicking on the button with the +mouse or by typing return to invoke the default button (if any). +Then it returns the index of the selected button: 0 for the leftmost +button, 1 for the button next to it, and so on. +If the dialog's window is destroyed before the user selects one +of the buttons, then -1 is returned. +.PP +While waiting for the user to respond, \fBtk_dialog\fR sets a local +grab. This prevents the user from interacting with the application +in any way except to invoke the dialog box. + +.SH KEYWORDS +bitmap, dialog, modal diff --git a/doc/entry.n b/doc/entry.n new file mode 100644 index 0000000..7a8e718 --- /dev/null +++ b/doc/entry.n @@ -0,0 +1,417 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) entry.n 1.41 97/10/31 12:58:44 +'\" +.so man.macros +.TH entry n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +entry \- Create and manipulate entry widgets +.SH SYNOPSIS +\fBentry\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-background \-highlightbackground \-insertontime \-selectforeground +\-borderwidth \-highlightcolor \-insertwidth \-takefocus +\-cursor \-highlightthickness \-justify \-textvariable +\-exportselection \-insertbackground \-relief \-xscrollcommand +\-font \-insertborderwidth \-selectbackground +\-foreground \-insertofftime \-selectborderwidth +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-show show Show +If this option is specified, then the true contents of the entry +are not displayed in the window. +Instead, each character in the entry's value will be displayed as +the first character in the value of this option, such as ``*''. +This is useful, for example, if the entry is to be used to enter +a password. +If characters in the entry are selected and copied elsewhere, the +information copied will be what is displayed, not the true contents +of the entry. +.OP \-state state State +Specifies one of two states for the entry: \fBnormal\fR or \fBdisabled\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. +.OP \-width width Width +Specifies an integer value indicating the desired width of the entry window, +in average-size characters of the widget's font. +If the value is less than or equal to zero, the widget picks a +size just large enough to hold its current text. +.BE + +.SH DESCRIPTION +.PP +The \fBentry\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 or in the option database +to configure aspects of the entry such as its colors, font, +and relief. The \fBentry\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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. +If an entry is exporting its selection (see the \fBexportSelection\fR +option), then it will observe the standard X11 protocols for handling the +selection; entry selections are available as type \fBSTRING\fR. +Entries also observe the standard Tk rules for dealing with the +input focus. When an entry has the input focus it displays an +\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 \fBxScrollCommand\fR mechanism for interacting with +scrollbars (see the description of the \fBxScrollCommand\fR option +for details). They also support scanning, as described below. + +.SH "WIDGET COMMAND" +.PP +The \fBentry\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior 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 +\fBanchor\fR +Indicates the anchor point for the selection, which is set with the +\fBselect from\fR and \fBselect adjust\fR widget commands. +.TP 12 +\fBend\fR +Indicates the character just after the last one in the entry's string. +This is equivalent to specifying a numerical index equal to the length +of the entry's string. +.TP 12 +\fBinsert\fR +Indicates the character adjacent to and immediately following the +insertion cursor. +.TP 12 +\fBsel.first\fR +Indicates the first character in the selection. It is an error to +use this form if the selection isn't in the entry window. +.TP 12 +\fBsel.last\fR +Indicates the character just after the last one in the selection. +It is an error to use this form if the selection isn't in the +entry window. +.TP 12 +\fB@\fInumber\fR +In this form, \fInumber\fR is treated as an x-coordinate in the +entry's window; the character spanning that x-coordinate is used. +For example, ``\fB@0\fR'' indicates the left-most character in the +window. +.LP +Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' +or ``\fBsel.f\fR''. In general, out-of-range indices are automatically +rounded to the nearest legal value. +.PP +The following commands are possible for entry widgets: +.TP +\fIpathName \fBbbox \fIindex\fR +Returns a list of four numbers describing the bounding box of the +character given by \fIindex\fR. +The first two elements of the list give the x and y coordinates of +the upper-left corner of the screen area covered by the character +(in pixels relative to the widget) and the last two elements give +the width and height of the character, in pixels. +The bounding box may refer to a region outside the visible area +of the window. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBentry\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBentry\fR +command. +.TP +\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +Delete one or more elements of the entry. +\fIFirst\fR is the index of the first character to delete, and +\fIlast\fR is the index of the character just after the last +one to delete. +If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, +i.e. a single character is deleted. +This command returns an empty string. +.TP +\fIpathName \fBget\fR +Returns the entry's string. +.TP +\fIpathName \fBicursor \fIindex\fR +Arrange for the insertion cursor to be displayed just before the character +given by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \fBindex\fI index\fR +Returns the numerical index corresponding to \fIindex\fR. +.TP +\fIpathName \fBinsert \fIindex string\fR +Insert the characters of \fIstring\fR just before the character +indicated by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \fBscan\fR \fIoption args\fR +This command is used to implement scanning on entries. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark \fIx\fR +Records \fIx\fR and the current view in the entry window; used in +conjunction with later \fBscan dragto\fR commands. Typically this +command is associated with a mouse button press in the widget. It +returns an empty string. +.TP +\fIpathName \fBscan dragto \fIx\fR +This command computes the difference between its \fIx\fR argument +and the \fIx\fR argument to the last \fBscan mark\fR command for +the widget. It then adjusts the view left or right by 10 times the +difference in x-coordinates. This command is typically associated +with mouse motion events in the widget, to produce the effect of +dragging the entry at high speed through the window. The return +value is an empty string. +.RE +.TP +\fIpathName \fBselection \fIoption arg\fR +This command is used to adjust the selection within an entry. It +has several forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBselection 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 +\fBselect 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 \fBselection clear\fR +Clear the selection if it is currently in this widget. If the +selection isn't in this widget then the command has no effect. +Returns an empty string. +.TP +\fIpathName \fBselection 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 \fBselection present\fR +Returns 1 if there is are characters selected in the entry, +0 if nothing is selected. +.TP +\fIpathName \fBselection range \fIstart\fR \fIend\fR +Sets the selection to include the characters starting with +the one indexed by \fIstart\fR and ending with the one just +before \fIend\fR. +If \fIend\fR refers to the same character as \fIstart\fR or an +earlier one, then the entry's selection is cleared. +.TP +\fIpathName \fBselection 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 \fBselect from\fR +or \fBselect 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 \fBxview \fIargs\fR +This command is used to query and change the horizontal position of the +text in the widget's window. It can take any of the following +forms: +.RS +.TP +\fIpathName \fBxview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the horizontal span that is visible in the window. +For example, if the first element is .2 and the second element is .6, +20% of the entry's text is off-screen to the left, the middle 40% is visible +in the window, and 40% of the text is off-screen to the right. +These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview\fR \fIindex\fR +Adjusts the view in the window so that the character given by \fIindex\fR +is displayed at the left edge of the window. +.TP +\fIpathName \fBxview moveto\fI fraction\fR +Adjusts the view in the window so that the character \fIfraction\fR of the +way through the text appears at the left edge of the window. +\fIFraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then characters farther to the left +become visible; if it is positive then characters farther to the right +become visible. +.RE + +.SH "DEFAULT BINDINGS" +.PP +Tk automatically creates class bindings for entries that give them +the following default behavior. +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 will stroke out a selection consisting +of whole words. +.IP [3] +Triple-clicking with mouse button 1 selects all of the text in the +entry and positions the insertion cursor before the first character. +.IP [4] +The ends of the selection can be adjusted by dragging with mouse +button 1 while the Shift key is down; this will adjust the end +of the selection that was nearest to the mouse cursor when button +1 was pressed. +If the button is double-clicked before dragging then the selection +will be adjusted in units of whole words. +.IP [5] +Clicking mouse button 1 with the Control key down will position the +insertion cursor in the entry without affecting the selection. +.IP [6] +If any normal printing characters are typed in an entry, they are +inserted at the point of the insertion cursor. +.IP [7] +The view in the entry can be adjusted by dragging with mouse button 2. +If mouse button 2 is clicked without moving the mouse, the selection +is copied into the entry at the position of the mouse cursor. +.IP [8] +If the mouse is dragged out of the entry on the left or right sides +while button 1 is pressed, the entry will automatically scroll to +make more text visible (if there is more text off-screen on the side +where the mouse left the window). +.IP [9] +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. +If Left or Right is typed with the Shift key down, then the insertion +cursor moves and the selection is extended to include the new character. +Control-Left and Control-Right move the insertion cursor by words, and +Control-Shift-Left and Control-Shift-Right move the insertion cursor +by words and also extend the selection. +Control-b and Control-f behave the same as Left and Right, respectively. +Meta-b and Meta-f behave the same as Control-Left and Control-Right, +respectively. +.IP [10] +The Home key, or Control-a, will move the insertion cursor to the +beginning of the entry and clear any selection in the entry. +Shift-Home moves the insertion cursor to the beginning of the entry +and also extends the selection to that point. +.IP [11] +The End key, or Control-e, will move the insertion cursor to the +end of the entry and clear any selection in the entry. +Shift-End moves the cursor to the end and extends the selection +to that point. +.IP [12] +The Select key and Control-Space set the selection anchor to the position +of the insertion cursor. They don't affect the current selection. +Shift-Select and Control-Shift-Space adjust the selection to the +current position of the insertion cursor, selecting from the anchor +to the insertion cursor if there was not any selection previously. +.IP [13] +Control-/ selects all the text in the entry. +.IP [14] +Control-\e clears any selection in the entry. +.IP [15] +The F16 key (labelled Copy on many Sun workstations) or Meta-w +copies the selection in the widget to the clipboard, if there is a selection. +.IP [16] +The F20 key (labelled Cut on many Sun workstations) or Control-w +copies the selection in the widget to the clipboard and deletes +the selection. +If there is no selection in the widget then these keys have no effect. +.IP [17] +The F18 key (labelled Paste on many Sun workstations) or Control-y +inserts the contents of the clipboard at the position of the +insertion cursor. +.IP [18] +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 [19] +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 [20] +Control-d deletes the character to the right of the insertion cursor. +.IP [21] +Meta-d deletes the word to the right of the insertion cursor. +.IP [22] +Control-k deletes all the characters to the right of the insertion +cursor. +.IP [23] +Control-t reverses the order of the two characters to the right of +the insertion cursor. +.PP +If the entry is disabled using the \fB\-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 behavior of entries can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +entry, widget diff --git a/doc/event.n b/doc/event.n new file mode 100644 index 0000000..a7d12b5 --- /dev/null +++ b/doc/event.n @@ -0,0 +1,338 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) event.n 1.6 97/10/31 12:58:54 +'\" +.so man.macros +.TH event n 4.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +event \- Miscellaneous event facilities: define virtual events and generate events +.SH SYNOPSIS +\fBevent\fI option \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBevent\fR command provides several facilities for dealing with +window system events, such as defining virtual events and synthesizing +events. The command has several different forms, determined by the +first argument. The following forms are currently supported: +.TP +\fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? +Associates the virtual event \fIvirtual\fR with the physical +event sequence(s) given by the \fIsequence\fR arguments, so that +the virtual event will trigger whenever any one of the \fIsequence\fRs +occurs. +\fIVirtual\fR may be any string value and \fIsequence\fR may have +any of the values allowed for the \fIsequence\fR argument to the +\fBbind\fR command. +If \fIvirtual\fR is already defined, the new physical event sequences +add to the existing sequences for the event. +.TP +\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\fR? +Deletes each of the \fIsequence\fRs from those associated with +the virtual event given by \fIvirtual\fR. +\fIVirtual\fR may be any string value and \fIsequence\fR may have +any of the values allowed for the \fIsequence\fR argument to the +\fBbind\fR command. +Any \fIsequence\fRs not currently associated with \fIvirtual\fR +are ignored. +If no \fIsequence\fR argument is provided, all physical event sequences +are removed for \fIvirtual\fR, so that the virtual event will not +trigger anymore. +.TP +\fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? +Generates a window event and arranges for it to be processed just as if +it had come from the window system. +\fIWindow\fR gives the path name of the window for which the event +.VS +will be generated; it may also be an identifier (such as returned by +\fBwinfo id\fR) as long as it is for a window in the current application. +.VE +\fIEvent\fR provides a basic description of +the event, such as \fB<Shift-Button-2>\fR or \fB<<Paste>>\fR. +\fIEvent\fR may have any of the forms allowed for the \fIsequence\fR +argument of the \fBbind\fR command except that it must consist +of a single event pattern, not a sequence. +\fIOption-value\fR pairs may be used to specify additional +attributes of the event, such as the x and y mouse position; see +EVENT FIELDS below. If the \fB\-when\fR option is not specified, the +event is processed immediately: all of the handlers for the event +will complete before the \fBevent generate\fR command returns. +If the \fB\-when\fR option is specified then it determines when the +event is processed. +.TP +\fBevent info \fR?<<\fIvirtual\fB>>\fR? +Returns information about virtual events. +If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value +is a list of all the virtual events that are currently defined. +If \fB<<\fIvirtual\fB>>\fR is specified then the return value is +a list whose elements are the physical event sequences currently +defined for the given virtual event; if the virtual event is +not defined then an empty string is returned. + +.SH "EVENT FIELDS" +.PP +The following options are supported for the \fBevent generate\fR +command. These correspond to the ``%'' expansions +allowed in binding scripts for the \fBbind\fR command. +.TP +\fB\-above\fI window\fR +\fIWindow\fR specifies the \fIabove\fR field for the event, +either as a window path name or as an integer window id. +Valid for \fBConfigure\fR events. +Corresponds to the \fB%a\fR substitution for binding scripts. +.TP +\fB\-borderwidth\fI size\fR +\fISize\fR must be a screen distance; it specifies the +\fIborder_width\fR field for the event. +Valid for \fBConfigure\fR events. +Corresponds to the \fB%B\fR substitution for binding scripts. +.TP +\fB\-button\fI number\fR +\fINumber\fR must be an integer; it specifies the \fIdetail\fR field +for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding +any button number provided in the base \fIevent\fR argument. +Corresponds to the \fB%b\fR substitution for binding scripts. +.TP +\fB\-count\fI number\fR +\fINumber\fR must be an integer; it specifies the \fIcount\fR field +for the event. Valid for \fBExpose\fR events. +Corresponds to the \fB%c\fR substitution for binding scripts. +.TP +\fB\-detail\fI detail\fR +\fIDetail\fR specifies the \fIdetail\fR field for the event +and must be one of the following: +.RS +.DS +.ta 6c +\fBNotifyAncestor NotifyNonlinearVirtual +NotifyDetailNone NotifyPointer +NotifyInferior NotifyPointerRoot +NotifyNonlinear NotifyVirtual\fR +.DE +Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and +\fBFocusOut\fR events. +Corresponds to the \fB%d\fR substitution for binding scripts. +.RE +.TP +\fB\-focus\fI boolean\fR +\fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR +field for the event. +Valid for \fBEnter\fR and \fBLeave\fR events. +Corresponds to the \fB%f\fR substitution for binding scripts. +.TP +\fB\-height\fI size\fR +\fISize\fR must be a screen distance; it specifies the \fIheight\fR +field for the event. Valid for \fBConfigure\fR events. +Corresponds to the \fB%h\fR substitution for binding scripts. +.TP +\fB\-keycode\fI number\fR +\fINumber\fR must be an integer; it specifies the \fIkeycode\fR +field for the event. +Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. +Corresponds to the \fB%k\fR substitution for binding scripts. +.TP +\fB\-keysym\fI name\fR +\fIName\fR must be the name of a valid keysym, such as \fBg\fR, +\fBspace\fR, or \fBReturn\fR; its corresponding +keycode value is used as the \fIkeycode\fR field for event, overriding +any detail specified in the base \fIevent\fR argument. +Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. +Corresponds to the \fB%K\fR substitution for binding scripts. +.TP +\fB\-mode\fI notify\fR +\fINotify\fR specifies the \fImode\fR field for the event and must be +one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or +\fBNotifyWhileGrabbed\fR. +Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and +\fBFocusOut\fR events. +Corresponds to the \fB%m\fR substitution for binding scripts. +.TP +\fB\-override\fI boolean\fR +\fIBoolean\fR must be a boolean value; it specifies the +\fIoverride_redirect\fR field for the event. +Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. +Corresponds to the \fB%o\fR substitution for binding scripts. +.TP +\fB\-place\fI where\fR +\fIWhere\fR specifies the \fIplace\fR field for the event; it must be +either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. +Valid for \fBCirculate\fR events. +Corresponds to the \fB%p\fR substitution for binding scripts. +.TP +\fB\-root\fI window\fR +\fIWindow\fR must be either a window path name or an integer window +identifier; it specifies the \fIroot\fR field for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR +events. +Corresponds to the \fB%R\fR substitution for binding scripts. +.TP +\fB\-rootx\fI coord\fR +\fICoord\fR must be a screen distance; it specifies the \fIx_root\fR +field for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR +events. Corresponds to the \fB%X\fR substitution for binding scripts. +.TP +\fB\-rooty\fI coord\fR +\fICoord\fR must be a screen distance; it specifies th \fIy_root\fR +field for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR +events. +Corresponds to the \fB%Y\fR substitution for binding scripts. +.TP +\fB\-sendevent\fI boolean\fR +\fBBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR +field for the event. Valid for all events. Corresponds to the +\fB%E\fR substitution for binding scripts. +.TP +\fB\-serial\fI number\fR +\fINumber\fR must be an integer; it specifies the \fIserial\fR field +for the event. Valid for all events. +Corresponds to the \fB%#\fR substitution for binding scripts. +.TP +\fB\-state\fI state\fR +\fIState\fR specifies the \fIstate\fR field for the event. +For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events +it must be an integer value. +For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, +\fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. +This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR +specified in the base \fIevent\fR. +Corresponds to the \fB%s\fR substitution for binding scripts. +.TP +\fB\-subwindow\fI window\fR +\fIWindow\fR specifies the \fIsubwindow\fR field for the event, either +as a path name for a Tk widget or as an integer window identifier. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. +Similar to \fB%S\fR substitution for binding scripts. +.TP +\fB\-time\fI integer\fR +\fIInteger\fR must be an integer value; it specifies the \fItime\fR field +for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, +and \fBProperty\fR events. +Corresponds to the \fB%t\fR substitution for binding scripts. +.TP +\fB\-width\fI size\fR +\fISize\fR must be a screen distance; it specifies the \fIwidth\fR field +for the event. +Valid for \fBConfigure\fR events. +Corresponds to the \fB%w\fR substitution for binding scripts. +.TP +\fB\-when\fI when\fR +\fIWhen\fR determines when the event will be processed; it must have one +of the following values: +.RS +.IP \fBnow\fR 10 +Process the event immediately, before the command returns. +This also happens if the \fB\-when\fR option is omitted. +.IP \fBtail\fR 10 +Place the event on Tcl's event queue behind any events already +queued for this application. +.IP \fBhead\fR 10 +Place the event at the front of Tcl's event queue, so that it +will be handled before any other events already queued. +.IP \fBmark\fR 10 +Place the event at the front of Tcl's event queue but behind any +other events already queued with \fB\-when mark\fR. +This option is useful when generating a series of events that should +be processed in order but at the front of the queue. +.RE +.TP +\fB\-x\fI coord\fR +\fICoord\fR must be a screen distance; it specifies the \fIx\fR field +for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, +\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR +events. +Corresponds to the the \fB%x\fR substitution for binding scripts. +.TP +\fB\-y\fI coord\fR +\fICoord\fR must be a screen distance; it specifies the \fIy\fR +field for the event. +Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, +\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, +\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR +events. +Corresponds to the the \fB%y\fR substitution for binding scripts. +.PP +Any options that are not specified when generating an event are filled +with the value 0, except for \fIserial\fR, which is filled with the +next X event serial number. + +.SH "VIRTUAL EVENT EXAMPLES" +.PP +In order for a virtual event binding to trigger, two things must +happen. First, the virtual event must be defined with the +\fBevent add\fR command. Second, a binding must be created for +the virtual event with the \fBbind\fR command. +Consider the following virtual event definitions: +.CS +event add <<Paste>> <Control-y> +event add <<Paste>> <Button-2> +event add <<Save>> <Control-X><Control-S> +event add <<Save>> <Shift-F12> +.CE +In the \fBbind\fR command, a virtual event can be bound like any other +builtin event type as follows: +.CS +bind Entry <<Paste>> {%W insert [selection get]} +.CE +The double angle brackets are used to specify that a virtual event is being +bound. If the user types Control-y or presses button 2, or if +a \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR, +then the \fB<<Paste>>\fR binding will be invoked. +.PP +If a virtual binding has the exact same sequence as a separate +physical binding, then the physical binding will take precedence. +Consider the following example: +.CS +event add <<Paste>> <Control-y> <Meta-Control-y> +bind Entry <Control-y> {puts Control-y} +bind Entry <<Paste>> {puts Paste} +.CE +When the user types Control-y the \fB<Control-y>\fR binding +will be invoked, because a physical event is considered +more specific than a virtual event, all other things being equal. +However, when the user types Meta-Control-y the +\fB<<Paste>>\fR binding will be invoked, because the +\fBMeta\fR modifier in the physical pattern associated with the +virtual binding is more specific than the \fB<Control-y\fR> sequence for +the physical event. +.PP +Bindings on a virtual event may be created before the virtual event exists. +Indeed, the virtual event never actually needs to be defined, for instance, +on platforms where the specific virtual event would meaningless or +ungeneratable. +.PP +When a definition of a virtual event changes at run time, all windows +will respond immediately to the new definition. +Starting from the preceding example, if the following code is executed: +.CS +bind <Entry> <Control-y> {} +event add <<Paste>> <Key-F6> +.CE +the behavior will change such in two ways. First, the shadowed +\fB<<Paste>>\fR binding will emerge. +Typing Control-y will no longer invoke the \fB<Control-y>\fR binding, +but instead invoke the virtual event \fB<<Paste>>\fR. Second, +pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding. + +.SH "SEE ALSO" +bind + +.SH KEYWORDS +event, binding, define, handle, virtual event diff --git a/doc/focus.n b/doc/focus.n new file mode 100644 index 0000000..8bf4897 --- /dev/null +++ b/doc/focus.n @@ -0,0 +1,113 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) focus.n 1.22 96/08/27 13:21:42 +'\" +.so man.macros +.TH focus n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +focus \- Manage the input focus +.SH SYNOPSIS +\fBfocus\fR +.sp +\fBfocus \fIwindow\fR +.sp +\fBfocus \fIoption\fR ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBfocus\fR command is used to manage the Tk input focus. +At any given time, one window on each display is designated as +the \fIfocus window\fR; any key press or key release events for the +display are sent to that window. +It is normally up to the window manager to redirect the focus among the +top-level windows of a display. For example, some window managers +automatically set the input focus to a top-level window whenever +the mouse enters it; others redirect the input focus only when +the user clicks on a window. +Usually the window manager will set the focus +only to top-level windows, leaving it up to the application to +redirect the focus among the children of the top-level. +.PP +Tk remembers one focus window for each top-level (the most recent +descendant of that top-level to receive the focus); when the window +manager gives the focus +to a top-level, Tk automatically redirects it to the remembered +window. Within a top-level Tk uses an \fIexplicit\fR focus model +by default. Moving the mouse within a top-level does not normally +change the focus; the focus changes only when a widget +decides explicitly to claim the focus (e.g., because of a button +click), or when the user types a key such as Tab that moves the +focus. +.PP +The Tcl procedure \fBtk_focusFollowsMouse\fR may be invoked to +create an \fIimplicit\fR focus model: it reconfigures Tk so that +the focus is set to a window whenever the mouse enters it. +The Tcl procedures \fBtk_focusNext\fR and \fBtk_focusPrev\fR +implement a focus order among the windows of a top-level; they +are used in the default bindings for Tab and Shift-Tab, among other +things. +.PP +The \fBfocus\fR command can take any of the following forms: +.TP +\fBfocus\fR +Returns the path name of the focus window on the display containing +the application's main window, or an empty string if no window in +this application has the focus on that display. Note: it is +better to specify the display explicitly using \fB\-displayof\fR +(see below) so that the code will work in applications using multiple +displays. +.TP +\fBfocus \fIwindow\fR +If the application currently has the input focus on \fIwindow\fR's +display, this command resets the input focus for \fIwindow\fR's display +to \fIwindow\fR and returns an empty string. +If the application doesn't currently have the input focus on +\fIwindow\fR's display, \fIwindow\fR will be remembered as the focus +for its top-level; the next time the focus arrives at the top-level, +Tk will redirect it to \fIwindow\fR. +If \fIwindow\fR is an empty string then the command does nothing. +.TP +\fBfocus \-displayof\fR \fIwindow\fR +Returns the name of the focus window on the display containing \fIwindow\fR. +If the focus window for \fIwindow\fR's display isn't in this +application, the return value is an empty string. +.TP +\fBfocus \-force \fIwindow\fR +Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if +the application doesn't currently have the input focus for the display. +This command should be used sparingly, if at all. +In normal usage, an application should not claim the focus for +itself; instead, it should wait for the window manager to give it +the focus. +If \fIwindow\fR is an empty string then the command does nothing. +.TP +\fBfocus \-lastfor\fR \fIwindow\fR +Returns the name of the most recent window to have the input focus +among all the windows in the same top-level as \fIwindow\fR. +If no window in that top-level has ever had the input focus, or +if the most recent focus window has been deleted, then the name +of the top-level is returned. The return value is the window that +will receive the input focus the next time the window manager gives +the focus to the top-level. + +.SH "QUIRKS" +.PP +When an internal window receives the input focus, Tk doesn't actually +set the X focus to that window; as far as X is concerned, the focus +will stay on the top-level window containing the window with the focus. +However, Tk generates FocusIn and FocusOut events just as if the X +focus were on the internal window. This approach gets around a +number of problems that would occur if the X focus were actually moved; +the fact that the X focus is on the top-level is invisible unless +you use C code to query the X server directly. + +.SH KEYWORDS +events, focus, keyboard, top-level, window manager diff --git a/doc/focusNext.n b/doc/focusNext.n new file mode 100644 index 0000000..e1f8fe7 --- /dev/null +++ b/doc/focusNext.n @@ -0,0 +1,60 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) focusNext.n 1.10 96/03/26 18:22:23 +'\" +.so man.macros +.TH tk_focusNext n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus. +.SH SYNOPSIS +\fBtk_focusNext \fIwindow\fR +.sp +\fBtk_focusPrev \fIwindow\fR +.sp +\fBtk_focusFollowsMouse\fR +.BE + +.SH DESCRIPTION +.PP +\fBtk_focusNext\fR is a utility procedure used for keyboard traversal. +It returns the ``next'' window after \fIwindow\fR in focus order. +The focus order is determined by +the stacking order of windows and the structure of the window hierarchy. +Among siblings, the focus order is the same as the stacking order, with the +lowest window being first. +If a window has children, the window is visited first, followed by +its children (recursively), followed by its next sibling. +Top-level windows other than \fIwindow\fR are skipped, so that +\fBtk_focusNext\fR never returns a window in a different top-level +from \fIwindow\fR. +.PP +After computing the next window, \fBtk_focusNext\fR examines the +window's \fB\-takefocus\fR option to see whether it should be skipped. +If so, \fBtk_focusNext\fR continues on to the next window in the focus +order, until it eventually finds a window that will accept the focus +or returns back to \fIwindow\fR. +.PP +\fBtk_focusPrev\fR is similar to \fBtk_focusNext\fR except that it +returns the window just before \fIwindow\fR in the focus order. +.PP +\fBtk_focusFollowsMouse\fR changes the focus model for the application +to an implicit one where the window under the mouse gets the focus. +After this procedure is called, whenever the mouse enters a window +Tk will automatically give it the input focus. +The \fBfocus\fR command may be used to move the focus to a window +other than the one under the mouse, but as soon as the mouse moves +into a new window the focus will jump to that window. +Note: at present there is no built-in support for returning the +application to an explicit focus model; to do this you'll have +to write a script that deletes the bindings created by +\fBtk_focusFollowsMouse\fR. + +.SH KEYWORDS +focus, keyboard traversal, top-level diff --git a/doc/font.n b/doc/font.n new file mode 100644 index 0000000..d3e5878 --- /dev/null +++ b/doc/font.n @@ -0,0 +1,285 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) font.n 1.10 97/08/22 18:52:18 +'\" +.so man.macros +.TH font n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +font \- Create and inspect fonts. +.SH SYNOPSIS +\fBfont\fI option \fR?\fIarg arg ...\fR? +.BE +.SH DESCRIPTION +.PP +The \fBfont\fR command provides several facilities for dealing with +fonts, such as defining named fonts and inspecting the actual attributes of +a font. The command has several different forms, determined by the +first argument. The following forms are currently supported: +.TP +\fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? +. +Returns information about the the actual attributes that are obtained when +\fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained +may differ from the attributes requested due to platform-dependant +limitations, such as the availability of font families and pointsizes. +\fIfont\fR is a font description; see FONT DESCRIPTIONS below. If the +\fIwindow\fR argument is omitted, it defaults to the main window. If +\fIoption\fR is specified, returns the value of that attribute; if it is +omitted, the return value is a list of all the attributes and their values. +See FONT OPTIONS below for a list of the possible attributes. +.TP +\fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. +Query or modify the desired attributes for the named font called +\fIfontname\fR. If no \fIoption\fR is specified, returns a list describing +all the options and their values for \fIfontname\fR. If a single \fIoption\fR +is specified with no \fIvalue\fR, then returns the current value of that +attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, +then the command modifies the given named font to have the given values; in +this case, all widgets using that font will redisplay themselves using the +new attributes for the font. See FONT OPTIONS below for a list of the +possible attributes. +.TP +\fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? +. +Creates a new named font and returns its name. \fIfontname\fR specifies the +name for the font; if it is omitted, then Tk generates a new name of the +form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number +of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for +the new named font. See FONT OPTIONS below for a list of the possible +attributes. +.TP +\fBfont delete\fR \fIfontname\fR ?\fIfontname ...\fR? +. +Delete the specified named fonts. If there are widgets using the named font, +the named font won't actually be deleted until all the instances are +released. Those widgets will continue to display using the last known values +for the named font. If a deleted named font is subsequently recreated with +another call to \fBfont create\fR, the widgets will use the new named font +and redisplay themselves using the new attributes of that font. +.TP +\fBfont families\fR ?\fB\-displayof \fIwindow\fR? +. +The return value is a list of the case-insensitive names of all font families +that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is +omitted, it defaults to the main window. +.TP +\fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR +. +Measures the amount of space the string \fItext\fR would use in the given +\fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; +see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is omitted, it +defaults to the main window. The return value is the total width in pixels +of \fItext\fR, not including the extra pixels used by highly exagerrated +characters such as cursive ``f''. If the string contains newlines or tabs, +those characters are not expanded or treated specially when measuring the +string. +.TP +\fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? +. +Returns information about the metrics (the font-specific data), for +\fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font +description; see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is +omitted, it defaults to the main window. If \fIoption\fR is specified, +returns the value of that metric; if it is omitted, the return value is a +list of all the metrics and their values. See FONT METRICS below for a list +of the possible metrics. +.TP +\fBfont names\fR +The return value is a list of all the named fonts that are currently defined. +.SH "FONT DESCRIPTION" +.PP +The following formats are accepted as a font description anywhere +\fIfont\fR is specified as an argument above; these same forms are also +permitted when specifying the \fB\-font\fR option for widgets. +.TP +[1] \fIfontname\fR +. +The name of a named font, created using the \fBfont create\fR command. When +a widget uses a named font, it is guaranteed that this will never cause an +error, as long as the named font exists, no matter what potentially invalid +or meaningless set of attributes the named font has. If the named font +cannot be displayed with exactly the specified attributes, some other close +font will be substituted automatically. +.TP +[2] \fIsystemfont\fR +. +The platform-specific name of a font, interpreted by the graphics server. +This also includes, under X, an XLFD (see [4]) for which a single ``\fB*\fR'' +character was used to elide more than one field in the middle of the +name. See PLATFORM-SPECIFIC issues for a list of the system fonts. +.VS 8.0 br +.TP +[3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? +. +A properly formed list whose first element is the desired font +\fIfamily\fR and whose optional second element is the desired \fIsize\fR. +The interpretation of the \fIsize\fR attribute follows the same rules +described for \fB\-size\fR in FONT OPTIONS below. Any additional optional +arguments following the \fIsize\fR are font \fIstyle\fRs. Possible values +for the \fIstyle\fR arguments are as follows: +.RS +.DS +.ta 3c 6c 9c +\fBnormal bold roman italic +underline overstrike\fR +.DE +.RE +.TP +[4] X-font names (XLFD) +. +A Unix-centric font name of the form +\fI-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding\fR. +The ``\fB*\fR'' character may be used to skip individual fields that the +user does not care about. There must be exactly one ``\fB*\fR'' for each +field skipped, except that a ``\fB*\fR'' at the end of the XLFD skips any +remaining fields; the shortest valid XLFD is simply ``\fB*\fR'', signifying +all fields as defaults. Any fields that were skipped are given default +values. For compatibility, an XLFD always chooses a font of the specified +pixel size (not point size); although this interpretation is not strictly +correct, all existing applications using XLFDs assumed that one ``point'' +was in fact one pixel and would display incorrectly (generally larger) if +the correct size font were actually used. +.VE +.TP +[5] \fIoption value \fR?\fIoption value ...\fR? +. +A properly formed list of \fIoption\fR\-\fIvalue\fR pairs that specify +the desired attributes of the font, in the same format used when defining +a named font; see FONT OPTIONS below. +.LP +When font description \fIfont\fR is used, the system attempts to parse the +description according to each of the above five rules, in the order specified. +Cases [1] and [2] must match the name of an existing named font or of a +system font. Cases [3], [4], and [5] are accepted on all +platforms and the closest available font will be used. In some situations +it may not be possible to find any close font (e.g., the font family was +a garbage value); in that case, some system-dependant default font is +chosen. If the font description does not match any of the above patterns, +an error is generated. +.SH "FONT METRICS" +. +The following options are used by the \fBfont metrics\fR command to query +font-specific data determined when the font was created. These properties are +for the whole font itself and not for individual characters drawn in that +font. In the following definitions, the ``baseline'' of a font is the +horizontal line where the bottom of most letters line up; certain letters, +such as lower-case ``g'' stick below the baseline. +.TP +\fB\-ascent \0\fR +. +The amount in pixels that the tallest letter sticks up above the baseline of +the font, plus any extra blank space added by the designer of the font. +.TP +\fB\-descent \0\fR +. +The largest amount in pixels that any letter sticks down below the baseline +of the font, plus any extra blank space added by the designer of the font. +.TP +\fB\-linespace\fR +. +Returns how far apart vertically in pixels two lines of text using the same +font should be placed so that none of the characters in one line overlap any +of the characters in the other line. This is generally the sum of the ascent +above the baseline line plus the descent below the baseline. +.TP +\fB\-fixed \0\fR +. +Returns a boolean flag that is ``\fB1\fR'' if this is a fixed-width font, +where each normal character is the the same width as all the other +characters, or is ``\fB0\fR'' if this is a proportionally-spaced font, where +individual characters have different widths. The widths of control +characters, tab characters, and other non-printing characters are not +included when calculating this value. +.SH "FONT OPTIONS" +The following options are supported on all platforms, and are used when +constructing a named font or when specifying a font using style [5] as +above: +.TP +\fB\-family \fIname\fR +. +The case-insensitive font family name. Tk guarantees to support the font +families named \fBCourier\fR (a monospaced ``typewriter'' font), \fBTimes\fR +(a serifed ``newspaper'' font), and \fBHelvetica\fR (a sans-serif +``European'' font). The most closely matching native font family will +automatically be substituted when one of the above font families is used. +The \fIname\fR may also be the name of a native, platform-specific font +family; in that case it will work as desired on one platform but may not +display correctly on other platforms. If the family is unspecified or +unrecognized, a platform-specific default font will be chosen. +.VS +.TP +\fB\-size \fIsize\fR +. +The desired size of the font. If the \fIsize\fR argument is a positive +number, it is interpreted as a size in points. If \fIsize\fR is a negative +number, its absolute value is interpreted as a size in pixels. If a +font cannot be displayed at the specified size, a nearby size will be +chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default +size will be chosen. +.RS +.PP +Sizes should normally be specified in points so the application will remain +the same ruler size on the screen, even when changing screen resolutions or +moving scripts across platforms. However, specifying pixels is useful in +certain circumstances such as when a piece of text must line up with respect +to a fixed-size bitmap. The mapping between points and pixels is set when +the application starts, based on properties of the installed monitor, but it +can be overridden by calling the \fBtk scaling\fR command. +.RE +.VE +.TP +\fB\-weight \fIweight\fR +. +The nominal thickness of the characters in the font. The value +\fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a +bold font. The closest available weight to the one specified will +be chosen. The default weight is \fBnormal\fR. +.TP +\fB\-slant \fIslant\fR +The amount the characters in the font are slanted away from the +vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. +A roman font is the normal, upright appearance of a font, while +an italic font is one that is tilted some number of degrees from upright. +The closest available slant to the one specified will be chosen. +The default slant is \fBroman\fR. +.TP +\fB\-underline \fIboolean\fR +The value is a boolean flag that specifies whether characters in this +font should be underlined. The default value for underline is \fBfalse\fR. +.TP +\fB\-overstrike \fIboolean\fR +The value is a boolean flag that specifies whether a horizontal line should +be drawn through the middle of characters in this font. The default value +for overstrike is \fBfalse\fR. + +.SH "PLATFORM-SPECIFIC ISSUES" +.LP +The following named system fonts are supported: +.RS +.TP +X Windows: +All valid X font names, including those listed by xlsfonts(1), are available. +.TP +MS Windows: +.DS +\fBsystem ansi device +systemfixed ansifixed oemfixed\fR +.DE +.TP +Macintosh: +.DS +\fBsystem application\fR +.DE +.RE +.SH "SEE ALSO" +options + +.SH KEYWORDS +font diff --git a/doc/frame.n b/doc/frame.n new file mode 100644 index 0000000..c9a3340 --- /dev/null +++ b/doc/frame.n @@ -0,0 +1,134 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" +'\" SCCS: @(#) frame.n 1.30 97/10/31 12:58:48 +'\" +.so man.macros +.TH frame n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +frame \- Create and manipulate frame widgets +.SH SYNOPSIS +\fBframe\fR \fIpathName\fR ?\fIoptions\fR? +.SO +\-borderwidth \-highlightbackground \-highlightthickness \-takefocus +\-cursor \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-background background Background +This option is the same as the standard \fBbackground\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 colors will be consumed from its colormap for its background +and border. +.OP \-class class Class +Specifies a class for the window. +This class will be used when querying the option database for +the window's other options, and it will also be used later for +other purposes such as bindings. +The \fBclass\fR option may not be changed with the \fBconfigure\fR +widget command. +.OP \-colormap colormap Colormap +Specifies a colormap to use for the window. +The value may be either \fBnew\fR, in which case a new colormap is +created for the window and its children, or the name of another +window (which must be on the same screen and have the same visual +as \fIpathName\fR), in which case the new window will use the colormap +from the specified window. +If the \fBcolormap\fR option is not specified, the new window +uses the same colormap as its parent. +This option may not be changed with the \fBconfigure\fR +widget command. +.VS "" br +.OP \-container container Container +The value must be a boolean. If true, it means that this window will +be used as a container in which some other application will be embedded +(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). +The window will support the appropriate window manager protocols for +things like geometry requests. The window should not have any +children of its own in this application. +This option may not be changed with the \fBconfigure\fR +widget command. +.VE +.OP \-height height Height +Specifies the desired height for the window in any of the forms +acceptable to \fBTk_GetPixels\fR. +If this option is less than or equal to zero then the window will +not request any size at all. +.OP \-visual visual Visual +Specifies visual information for the new window in any of the +forms accepted by \fBTk_GetVisual\fR. +If this option is not specified, the new window will use the same +visual as its parent. +The \fBvisual\fR option may not be modified with the \fBconfigure\fR +widget command. +.OP \-width width Width +Specifies the desired width for the window in any of the forms +acceptable to \fBTk_GetPixels\fR. +If this option is less than or equal to zero then the window will +not request any size at all. +.BE + +.SH DESCRIPTION +.PP +The \fBframe\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 +or in the option database +to configure aspects of the frame such as its background color +and relief. The \fBframe\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 color and an optional 3-D border to make the +frame appear raised or sunken. + +.SH "WIDGET COMMAND" +.PP +The \fBframe\fR command creates a new Tcl command whose +name is the same as the path name of the frame's window. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\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 behavior of the command. The following +commands are possible for frame widgets: +.TP +\fIpathName \fBcget\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 \fBframe\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBframe\fR +command. + +.SH BINDINGS +.PP +When a new frame is created, it has no default event bindings: +frames are not intended to be interactive. + +.SH KEYWORDS +frame, widget diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n new file mode 100644 index 0000000..f8a8b72 --- /dev/null +++ b/doc/getOpenFile.n @@ -0,0 +1,155 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) getOpenFile.n 1.8 96/12/08 21:14:31 +'\" +.so man.macros +.TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_getOpenFile, tk_getSaveFile \- pop up a dialog box for the user to select a file to open or save. +.PP +.PP +.SH SYNOPSIS +\fBtk_getOpenFile \fR?\fIoption value ...\fR? +.br +\fBtk_getSaveFile \fR?\fIoption value ...\fR? +.BE + +.SH DESCRIPTION +.PP +The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a +dialog box for the user to select a file to open or save. The +\fBtk_getOpenFile\fR command is usually associated with the \fBOpen\fR +command in the \fBFile\fR menu. Its purpose is for the user to select an +existing file \fIonly\fR. If the user enters an non-existent file, the +dialog box gives the user an error prompt and requires the user to give +an alternative selection. If an application allows the user to create +new files, it should do so by providing a separate \fBNew\fR menu command. +.PP +The \fBtk_getSaveFile\fR command is usually associated with the \fBSave +as\fR command in the \fBFile\fR menu. If the user enters a file that +already exists, the dialog box prompts the user for confirmation +whether the existing file should be overwritten or not. +.PP +The following \fIoption\-value\fR pairs are possible as command line +arguments to these two commands: +.TP +\fB\-defaultextension\fR \fIextension\fR +Specifies a string that will be appended to the filename if the user +enters a filename without an extension. The defaut value is the empty +string, which means no extension will be appended to the filename in +any case. This option is ignored on the Macintosh platform, which +does not require extensions to filenames. +.TP +\fB\-filetypes\fR \fIfilePatternList\fR +If a \fBFile types\fR listbox exists in the file dialog on the particular +platform, this option gives the \fIfiletype\fRs in this listbox. When +the user choose a filetype in the listbox, only the files of that type +are listed. If this option is unspecified, or if it is set to the +empty list, or if the \fBFile types\fR listbox is not supported by the +particular platform then all files are listed regardless of their +types. See the section SPECIFYING FILE PATTERNS below for a +discussion on the contents of \fIfilePatternList\fR. +.TP +\fB\-initialdir\fR \fIdirectory\fR +Specifies that the files in \fIdirectory\fR should be displayed +when the dialog pops up. If this parameter is not specified, then +the files in the current working directory are displayed. This +option may not always work on the Macintosh. This is not a bug. +Rather, the \fIGeneral Controls\fR control panel on the Mac allows the +end user to override the application default directory. +.TP +\fB\-initialfile\fR \fIfilename\fR +Specifies a filename to be displayed in the dialog when it pops +up. This option is ignored by the \fBtk_getOpenFile\fR command. +.TP +\fB\-parent\fR \fIwindow\fR +Makes \fIwindow\fR the logical parent of the file dialog. The file +dialog is displayed on top of its parent window. +.TP +\fB\-title\fR \fItitleString\fR +Specifies a string to display as the title of the dialog box. If this +option is not specified, then a default title is displayed. This +option is ignored on the Macintosh platform. +.PP +If the user selects a file, both \fBtk_getOpenFile\fR and +\fBtk_getSaveFile\fR return the full pathname of this file. If the +user cancels the operation, both commands return the empty string. +.SH "SPECIFYING FILE PATTERNS" + +The \fIfilePatternList\fR value given by the \fB\-filetypes\fR option +is a list of file patterns. Each file pattern is a list of the +form +.CS +\fItypeName\fR {\fIextension\fR ?\fIextension ...\fR?} ?{\fImacType\fR ?\fImacType ...\fR?}? +.CE +\fItypeName\fR is the name of the file type described by this +file pattern and is the text string that appears in the \fBFile types\fR +listbox. \fIextension\fR is a file extension for this file pattern. +\fImacType\fR is a four-character Macintosh file type. The list of +\fImacType\fRs is optional and may be omitted for applications that do +not need to execute on the Macintosh platform. +.PP +Several file patterns may have the same \fItypeName,\fR in which case +they refer to the same file type and share the same entry in the +listbox. When the user selects an entry in the listbox, all the files +that match at least one of the file patterns corresponding +to that entry are listed. Usually, each file pattern corresponds to a +distinct type of file. The use of more than one file patterns for one +type of file is necessary on the Macintosh platform only. +.PP +On the Macintosh platform, a file matches a file pattern if its +name matches at least one of the \fIextension\fR(s) AND it +belongs to at least one of the \fImacType\fR(s) of the +file pattern. For example, the \fBC Source Files\fR file pattern in the +sample code matches with files that have a \fB\.c\fR extension AND +belong to the \fImacType\fR \fBTEXT\fR. To use the OR rule instead, +you can use two file patterns, one with the \fIextensions\fR only and +the other with the \fImacType\fR only. The \fBGIF Files\fR file type +in the sample code matches files that EITHER have a \fB\.gif\fR +extension OR belong to the \fImacType\fR \fBGIFF\fR. +.PP +On the Unix and Windows platforms, a file matches a file pattern +if its name matches at at least one of the \fIextension\fR(s) of +the file pattern. The \fImacType\fRs are ignored. +.SH "SPECIFYING EXTENSIONS" +.PP +On the Unix and Macintosh platforms, extensions are matched using +glob-style pattern matching. On the Windows platforms, extensions are +matched by the underlying operating system. The types of possible +extensions are: (1) the special extension * matches any +file; (2) the special extension "" matches any files that +do not have an extension (i.e., the filename contains no full stop +character); (3) any character string that does not contain any wild +card characters (* and ?). +.PP +Due to the different pattern matching rules on the various platforms, +to ensure portability, wild card characters are not allowed in the +extensions, except as in the special extension *. Extensions +without a full stop character (e.g, ~) are allowed but may not +work on all platforms. + +.SH EXAMPLE +.CS +set types { + {{Text Files} {.txt} } + {{TCL Scripts} {.tcl} } + {{C Source Files} {.c} TEXT} + {{GIF Files} {.gif} } + {{GIF Files} {} GIFF} + {{All Files} * } +} +set filename [tk_getOpenFile -filetypes $types] + +if {$filename != ""} { + # Open the file ... +} +.CE + +.SH KEYWORDS +file selection dialog diff --git a/doc/grab.n b/doc/grab.n new file mode 100644 index 0000000..4b36134 --- /dev/null +++ b/doc/grab.n @@ -0,0 +1,122 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) grab.n 1.15 96/03/26 18:22:48 +'\" +.so man.macros +.TH grab n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +grab \- Confine pointer and keyboard events to a window sub-tree +.SH SYNOPSIS +\fBgrab \fR?\fB\-global\fR? \fIwindow\fR +.sp +\fBgrab \fIoption \fR?\fIarg arg \fR...? +.BE + +.SH DESCRIPTION +.PP +This command implements simple pointer and keyboard grabs for Tk. +Tk's grabs are different than the grabs +described in the Xlib documentation. +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 +Two forms of grabs are possible: local and global. +A local grab affects only the grabbing application: events will +be reported to other applications as if the grab had never occurred. +Grabs are local by default. +A global 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 global grabs the window manager will not receive pointer +events either. +.PP +During local grabs, keyboard events (key presses and key releases) +are delivered as usual: the window +manager controls which application receives keyboard events, and +if they are sent to any window in the grabbing application then they are +redirected to the focus window. +During a global grab Tk grabs the keyboard so that all keyboard events +are always sent to the grabbing application. +The \fBfocus\fR command is still used to determine which window in the +application receives the keyboard events. +The keyboard grab is released when the grab is released. +.PP +Grabs apply to particular displays. If an application has windows +on multiple displays then it can establish a separate grab on each +display. +The grab on a particular display affects only the windows on +that display. +It is possible for different applications on a single display to have +simultaneous local grabs, but only one application can have a global +grab on a given display at once. +.PP +The \fBgrab\fR command can take any of the following forms: +.TP +\fBgrab \fR?\fB\-global\fR? \fIwindow\fR +Same as \fBgrab set\fR, described below. +.TP +\fBgrab current \fR?\fIwindow\fR? +If \fIwindow\fR is specified, returns the name of the current grab +window in this application for \fIwindow\fR's display, or an empty +string if there is no such window. +If \fIwindow\fR is omitted, the command returns a list whose elements +are all of the windows grabbed by this application for all displays, +or an empty string if the application has no grabs. +.TP +\fBgrab release \fIwindow\fR +Releases the grab on \fIwindow\fR if there is one, otherwise does +nothing. Returns an empty string. +.TP +\fBgrab set \fR?\fB\-global\fR? \fIwindow\fR +Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the +grab is global, otherwise it is local. +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 and it has the same +global/local form as the requested grab, then the command +does nothing. Returns an empty string. +.TP +\fBgrab status \fIwindow\fR +Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, +\fBlocal\fR if a local grab is set on \fIwindow\fR, and +\fBglobal\fR if a global grab is set. + +.SH BUGS +.PP +It took an incredibly complex and gross implementation to produce +the simple grab effect described above. +Given the current implementation, it isn't safe for applications +to use the Xlib grab facilities at all except through the Tk grab +procedures. +If applications try to manipulate X's grab mechanisms directly, +things will probably break. +.PP +If a single process is managing several different Tk applications, +only one of those applications can have a local grab for a given +display at any given time. If the applications are in different +processes, this restriction doesn't exist. + +.SH KEYWORDS +grab, keyboard events, pointer events, window diff --git a/doc/grid.n b/doc/grid.n new file mode 100644 index 0000000..27cc470 --- /dev/null +++ b/doc/grid.n @@ -0,0 +1,337 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) grid.n 1.15 96/12/13 16:46:35 +'\" +.so man.macros +.TH grid n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +grid \- Geometry manager that arranges widgets in a grid +.SH SYNOPSIS +\fBgrid \fIoption arg \fR?\fIarg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBgrid\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 \fBgrid\fR command can have any of several forms, depending +on the \fIoption\fR argument: +.TP +\fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +If the first argument to \fBgrid\fR is a window name (any value +starting with ``.''), then the command is processed in the same +way as \fBgrid configure\fR. +.TP +\fBgrid 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 width and height 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 +\fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR? +Query or set the column properties of the \fIindex\fP column of the +geometry master, \fImaster\fP. +The valid options are \fB\-minsize\fP, \fB\-weight\fP and \fB-pad\fP. +.VS +If one or more options are provided, then \fIindex\fP may be given as +a list of column indeces to which the configuration options will operate on. +.VE +The \fB\-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this column. +The \fB\-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 \fB-pad\fP option specifies the number of screen units that will be +added to the largest window contained completely in that column when the +grid geometry manager requests a size from the containing window. +If only an option is specified, with no value, +the current value of that option is returned. +If only the master window and index is specified, all the current settings +are returned in an list of "-option value" pairs. +.TP +\fBgrid 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. +The characters \fB\-\fP, \fBx\fP and \fB^\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 +\fB\-column \fIn\fR +Insert the slave so that it occupies the \fIn\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 +\fBx\fP that immediately precedes the \fIslave\fP, the column position +is incremented by one. Thus the \fBx\fP represents a blank column +for this row in the grid. +.TP +\fB\-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 +\fB\-\fP, in which case the columnspan is incremented once for each immediately +following \fB\-\fP. +.TP +\fB\-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 +\fB\-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 \fB2\fR or \fB.5c\fR. +It defaults to 0. +.TP +\fB\-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 +\fB\-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 +\fB\-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 +\fB\-row \fIn\fR +Insert the slave so that it occupies the \fIn\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 \fBgrid\fP, or the first unoccupied row if this is the first slave. +.TP +\fB\-rowspan \fIn\fR +Insert the slave so that it occupies \fIn\fP rows in the grid. +The default is one row. If the next \fBgrid\fP command contains +\fB^\fP characters instead of \fIslaves\fP that line up with the columns +of this \fIslave\fP, then the \fBrowspan\fP of this \fIslave\fP is +extended by one. +.TP +\fB\-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 +\fBn\fP, \fBs\fP, \fBe\fP or \fBw\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 \fBn\fP and \fBs\fP (or +\fBe\fP and \fBw\fP) are specified, the slave will be stretched to fill the entire +height (or width) of its cavity. The \fBsticky\fP option subsumes the +combination of \fB\-anchor\fP and \fB\-fill\fP that is used by \fBpack\fP. +The default is \fB{}\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. +.RE +.TP +\fBgrid 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 +\fBgrid 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 \fBgrid configure\fR. +The first two elements of the list are ``\fB\-in \fImaster\fR'' where +\fImaster\fR is the slave's master. +.TP +\fBgrid 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, \fB-1\fP is returned. +.TP +\fBgrid propagate \fImaster\fR ?\fIboolean\fR? +If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\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 \fB0\fR or +\fB1\fR to indicate whether propagation is currently enabled +for \fImaster\fR. +Propagation is enabled by default. +.TP +\fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR? +Query or set the row properties of the \fIindex\fP row of the +geometry master, \fImaster\fP. +The valid options are \fB\-minsize\fP, \fB\-weight\fP and \fB-pad\fP. +.VS +If one or more options are provided, then \fIindex\fP may be given as +a list of row indeces to which the configuration options will operate on. +.VE +The \fB\-minsize\fP option sets the minimum size, in screen units, +that will be permitted for this row. +The \fB\-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 \fB-pad\fP option specifies the number of screen units that will be +added to the largest window contained completely in that row when the +grid geometry manager requests a size from the containing window. +If only an option is specified, with no value, +the current value of that option is returned. +If only the master window and index is specified, all the current settings +are returned in an list of "-option value" pairs. +.TP +\fBgrid remove \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. +However, the configuration options for that window are remembered, +so that if the +slave is managed once more by the grid geometry manager, the previous +values are retained. +.TP +\fBgrid size \fImaster\fR +Returns the size of the grid (in columns then rows) for \fImaster\fP. +The size is determined either by the \fIslave\fP occupying the largest +row or column, or the largest column or row with a \fBminsize\fP, +\fBweight\fP, or \fBpad\fP that is non-zero. +.TP +\fBgrid 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 \fB\-row\fP or \fB\-column\fP which +causes only the slaves in the row (or column) specified by \fIvalue\fP +to be returned. +.SH "RELATIVE PLACEMENT" +.PP +The \fBgrid\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 +\fBcolumn\fP, \fBrow\fP, \fBcolumnspan\fP and \fBrowspan\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 \fB\-\fP, \fB^\fP, and \fB^\fP in \fBgrid\fP +command where \fIslave\fP names are normally expected. +.RS +.TP +\fB\-\fP +This increases the columnspan of the \fIslave\fP to the left. Several +\fB\-\fP's in a row will successively increase the columnspan. A \fB\-\fP +may not follow a \fB^\fP or a \fBx\fP. +.TP +\fBx\fP +This leaves an empty column between the \fIslave\fP on the left and +the \fIslave\fP on the right. +.TP +\fB^\fP +This extends the \fBrowspan\fP of the \fIslave\fP above the \fB^\fP's +in the grid. The number of \fB^\fP's in a row must match the number of +columns spanned by the \fIslave\fP above it. +.RE +.SH "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 there minimum sizes, the layout is +clipped on the bottom and right. +.SH "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 \fBgrid 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. + +.SH "RESTRICTIONS ON MASTER WINDOWS" +.PP +The master for each slave must either be the slave's parent +(the default) or a descendant of the slave's parent. +This restriction is necessary to guarantee that the +slave can be placed over any part of its master that is +visible without danger of the slave being clipped by its parent. +In addition, all slaves in one call to \fBgrid\fP must have the same master. +.SH "STACKING ORDER" +.PP +If the master for a slave is not its parent then you must make sure +that the slave is higher in the stacking order than the master. +Otherwise the master will obscure the slave and it will appear as +if the slave hasn't been managed correctly. +The easiest way to make sure the slave is higher than the master is +to create the master window first: the most recently created window +will be highest in the stacking order. +.SH CREDITS +.PP +The \fBgrid\fP command is based on ideas taken from the \fIGridBag\fP +geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry +manager, written by George Howlett. +.SH KEYWORDS +geometry manager, location, grid, cell, propagation, size, pack diff --git a/doc/image.n b/doc/image.n new file mode 100644 index 0000000..8189838 --- /dev/null +++ b/doc/image.n @@ -0,0 +1,90 @@ +'\" +'\" Copyright (c) 1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) image.n 1.10 96/03/26 18:23:05 +'\" +.so man.macros +.TH image n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +image \- Create and manipulate images +.SH SYNOPSIS +\fBimage\fR \fIoption \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBimage\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 +\fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? +Creates a new image and returns its name. +\fItype\fR specifies the type of the image, which must be one of +the types currently defined (e.g., \fBbitmap\fR). +\fIname\fR specifies the name for the image; if it is omitted then +Tk picks a name of the form \fBimage\fIx\fR, where \fIx\fR is +an integer. +There may be any number of \fIoption\fR\-\fIvalue\fR pairs, +which provide configuration options for the new image. +The legal set of options is defined separately for each image +type; see below for details on the options for built-in image types. +If an image already exists by the given name then it is replaced +with the new image and any instances of that image will redisplay +with the new contents. +.TP +\fBimage delete \fR?\fIname name\fR ...? +Deletes each of the named images and returns an empty string. +If there are instances of the images displayed in widgets, +the images won't actually be deleted until all of the instances +are released. +However, the association between the instances and the image +manager will be dropped. +Existing instances will retain their sizes but redisplay as +empty areas. +If a deleted image is recreated with another call to \fBimage create\fR, +the existing instances will use the new image. +.TP +\fBimage height \fIname\fR +Returns a decimal string giving the height of image \fIname\fR +in pixels. +.TP +\fBimage names\fR +Returns a list containing the names of all existing images. +.TP +\fBimage type \fIname\fR +Returns the type of image \fIname\fR (the value of the \fItype\fR +argument to \fBimage create\fR when the image was created). +.TP +\fBimage types\fR +Returns a list whose elements are all of the valid image types +(i.e., all of the values that may be supplied for the \fItype\fR +argument to \fBimage create\fR). +.TP +\fBimage width \fIname\fR +Returns a decimal string giving the width of image \fIname\fR +in pixels. + +.SH "BUILT-IN IMAGE TYPES" +.PP +The following image types are defined by Tk so they will be available +in any Tk application. +Individual applications or extensions may define additional types. +.TP +\fBbitmap\fR +Each pixel in the image displays a foreground color, a background +color, or nothing. +See the \fBbitmap\fR manual entry for more information. +.TP +\fBphoto\fR +Displays a variety of full-color images, using dithering to +approximate colors on displays with limited color capabilities. +See the \fBphoto\fR manual entry for more information. + +.SH KEYWORDS +height, image, types of images, width diff --git a/doc/label.n b/doc/label.n new file mode 100644 index 0000000..15a948d --- /dev/null +++ b/doc/label.n @@ -0,0 +1,103 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) label.n 1.30 97/10/31 12:58:49 +'\" +.so man.macros +.TH label n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +label \- Create and manipulate label widgets +.SH SYNOPSIS +\fBlabel\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-anchor \-font \-image \-takefocus +\-background \-foreground \-justify \-text +\-bitmap \-highlightbackground \-padx \-textvariable +\-borderwidth \-highlightcolor \-pady \-underline +\-cursor \-highlightthickness \-relief \-wraplength +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-height height Height +Specifies a desired height for the label. +If an image or bitmap is being displayed in the label then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in lines of text. +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. +.OP \-width width Width +Specifies a desired width for the label. +If an image or bitmap is being displayed in the label then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in characters. +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. +.BE + +.SH DESCRIPTION +.PP +The \fBlabel\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 +or in the option database +to configure aspects of the label such as its colors, font, +text, and initial relief. The \fBlabel\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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 +or if wrapping occurs because of the \fBwrapLength\fR option) and +one of the characters may optionally be underlined using the +\fBunderline\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" +.PP +The \fBlabel\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for label widgets: +.TP +\fIpathName \fBcget\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 \fBlabel\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBlabel\fR +command. + +.SH BINDINGS +.PP +When a new label is created, it has no default event bindings: +labels are not intended to be interactive. + +.SH KEYWORDS +label, widget diff --git a/doc/listbox.n b/doc/listbox.n new file mode 100644 index 0000000..56caa62 --- /dev/null +++ b/doc/listbox.n @@ -0,0 +1,491 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) listbox.n 1.38 97/10/31 12:58:47 +'\" +.so man.macros +.TH listbox n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +listbox \- Create and manipulate listbox widgets +.SH SYNOPSIS +\fBlistbox\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-background \-foreground \-relief \-takefocus +\-borderwidth \-height \-selectbackground \-width +\-cursor \-highlightbackground \-selectborderwidth \-xscrollcommand +\-exportselection \-highlightcolor \-selectforeground \-yscrollcommand +\-font \-highlightthickness \-setgrid +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-height height Height +Specifies the desired height for the window, in lines. +If zero or less, then the desired height for the window is made just +large enough to hold all the elements in the listbox. +.OP \-selectmode selectMode SelectMode +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 \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, +or \fBextended\fR; the default value is \fBbrowse\fR. +.OP \-width width Width +Specifies the desired width for the window in characters. +If the font doesn't have a uniform width then the width of the +character ``0'' is used in translating from character units to +screen units. +If zero or less, then the desired width for the window is made just +large enough to hold all the elements in the listbox. +.BE + +.SH DESCRIPTION +.PP +The \fBlistbox\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 +or in the option database +to configure aspects of the listbox such as its colors, font, +text, and relief. The \fBlistbox\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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. +If a listbox is exporting its selection (see \fBexportSelection\fR +option), then it will observe the standard X11 protocols +for handling the selection. +Listbox selections are available as type \fBSTRING\fR; +the value of the selection will be the text of the selected elements, with +newlines separating the elements. +.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 \fBxScrollCommand\fR +and \fByScrollCommand\fR options. +They also support scanning, as described below. + +.SH "INDICES" +.PP +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 +\fBactive\fR +Indicates the element that has the location cursor. This element +will be displayed with an underline when the listbox has the +keyboard focus, and it is specified with the \fBactivate\fR +widget command. +.TP 12 +\fBanchor\fR +Indicates the anchor point for the selection, which is set with the +\fBselection anchor\fR widget command. +.TP 12 +\fBend\fR +Indicates the end of the listbox. +.VS 8.0 +For most commands this refers to the last element in the listbox, +but for a few commands such as \fBindex\fR and \fBinsert\fR +it refers to the element just after the last one. +.VE +.TP 12 +\fB@\fIx\fB,\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" +.PP +The \fBlistbox\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for listbox widgets: +.TP +\fIpathName \fBactivate\fR \fIindex\fR +Sets the active element to the one indicated by \fIindex\fR. +.VS 8.0 +If \fIindex\fR is outside the range of elements in the listbox +then the closest element is activated. +.VE +The active element is drawn with an underline when the widget +has the input focus, and its index may be retrieved with the +index \fBactive\fR. +.TP +\fIpathName \fBbbox\fR \fIindex\fR +Returns a list of four numbers describing the bounding box of +the text in the element 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 text +(specified in pixels relative to the widget) and the last two +elements give the width and height of the area, in pixels. +If no part of the element given by \fIindex\fR is visible on the +screen, +.VS 8.0 +or if \fIindex\fR refers to a non-existent element, +.VE +then the result is an empty string; if the element is +partially visible, the result gives the full area of the element, +including any parts that are not visible. +.TP +\fIpathName \fBcget\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 \fBlistbox\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBlistbox\fR +command. +.TP +\fIpathName \fBcurselection\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 \fBdelete \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 \fBget \fIfirst\fR ?\fIlast\fR? +If \fIlast\fR is omitted, returns the contents of the listbox +element indicated by \fIfirst\fR, +.VS 8.0 +or an empty string if \fIfirst\fR refers to a non-existent element. +.VE +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 \fBindex \fIindex\fR +Returns the integer index value that corresponds to \fIindex\fR. +.VS 8.0 +If \fIindex\fR is \fBend\fR the return value is a count of the number +of elements in the listbox (not the index of the last element). +.VE +.TP +\fIpathName \fBinsert \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 +\fBend\fR then the new elements are added to the end of the +list. Returns an empty string. +.TP +\fIpathName \fBnearest \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 \fBscan\fR \fIoption args\fR +This command is used to implement scanning on listboxes. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark \fIx y\fR +Records \fIx\fR and \fIy\fR and the current view in the listbox +window; used in conjunction with later \fBscan dragto\fR commands. +Typically this command is associated with a mouse button press in +the widget. It returns an empty string. +.TP +\fIpathName \fBscan 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 +\fBscan 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 list at high speed through the window. The return +value is an empty string. +.RE +.TP +\fIpathName \fBsee \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 \fBselection \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 \fBselection anchor \fIindex\fR +Sets the selection anchor to the element given by \fIindex\fR. +.VS 8.0 +If \fIindex\fR refers to a non-existent element, then the closest +element is used. +.VE +The selection anchor is the end of the selection that is fixed +while dragging out a selection with the mouse. +The index \fBanchor\fR may be used to refer to the anchor +element. +.TP +\fIpathName \fBselection 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 \fBselection includes \fIindex\fR +Returns 1 if the element indicated by \fIindex\fR is currently +selected, 0 if it isn't. +.TP +\fIpathName \fBselection 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 \fBsize\fR +Returns a decimal string indicating the total number of elements +in the listbox. +.TP +\fIpathName \fBxview \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 \fBxview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the horizontal span that is visible in the window. +For example, if the first element is .2 and the second element is .6, +20% of the 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 \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview\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 \fB0\fR. +.TP +\fIpathName \fBxview 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 \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR character units (the width of the \fB0\fR character) +on the display; if it is \fBpages\fR then the view adjusts by +\fInumber\fR screenfuls. +If \fInumber\fR is negative then characters farther to the left +become visible; if it is positive then characters farther to the right +become visible. +.RE +.TP +\fIpathName \fByview \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 \fByview\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 \fB\-yscrollcommand\fR +option. +.TP +\fIpathName \fByview\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 \fByview 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 \fByview 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 \fBunits\fR or \fBpages\fR. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by +\fInumber\fR lines; if it is \fBpages\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" +.PP +Tk automatically creates class bindings for listboxes that give them +Motif-like behavior. Much of the behavior of a listbox is determined +by its \fBselectMode\fR option, which selects one of four ways +of dealing with the selection. +.PP +If the selection mode is \fBsingle\fR or \fBbrowse\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 \fBbrowse\fR mode it is also possible to drag the selection +with button 1. +.PP +If the selection mode is \fBmultiple\fR or \fBextended\fR, +any number of elements may be selected at once, including discontiguous +ranges. In \fBmultiple\fR mode, clicking button 1 on an element +toggles its selection state without affecting any other elements. +In \fBextended\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 \fBbrowse\fR mode for +single selections and \fBextended\fR mode for multiple selections; +the other modes appear to be useful only in special situations. +.PP +In addition to the above behavior, the following additional behavior +is defined by the default bindings: +.IP [1] +In \fBextended\fR mode, the selected range can be adjusted by pressing +button 1 with the Shift key down: this modifies the selection to +consist of the elements between the anchor and the element under +the mouse, inclusive. +The un-anchored end of this new selection can also be dragged with +the button down. +.IP [2] +In \fBextended\fR mode, pressing button 1 with the Control key down +starts a toggle operation: the anchor is set to the element under +the mouse, and its selection state is reversed. The selection state +of other elements isn't changed. +If the mouse is dragged with button 1 down, then the selection state +of all elements between the anchor and the element under the mouse +is set to match that of the anchor element; the selection state of +all other elements remains what it was before the toggle operation +began. +.IP [3] +If the mouse leaves the listbox window with button 1 down, the window +scrolls away from the mouse, making information visible that used +to be off-screen on the side of the mouse. +The scrolling continues until the mouse re-enters the window, the +button is released, or the end of the listbox is reached. +.IP [4] +Mouse button 2 may be used for scanning. +If it is pressed and dragged over the listbox, the contents of +the listbox drag at high speed in the direction the mouse moves. +.IP [5] +If the Up or Down key is pressed, the location cursor (active +element) moves up or down one element. +If the selection mode is \fBbrowse\fR or \fBextended\fR then the +new active element is also selected and all other elements are +deselected. +In \fBextended\fR mode the new active element becomes the +selection anchor. +.IP [6] +In \fBextended\fR mode, Shift-Up and Shift-Down move the location +cursor (active element) up or down one element and also extend +the selection to that element in a fashion similar to dragging +with mouse button 1. +.IP [7] +The Left and Right keys scroll the listbox view left and right +by the width of the character \fB0\fR. +Control-Left and Control-Right scroll the listbox view left and +right by the width of the window. +Control-Prior and Control-Next also scroll left and right by +the width of the window. +.IP [8] +The Prior and Next keys scroll the listbox view up and down +by one page (the height of the window). +.IP [9] +The Home and End keys scroll the listbox horizontally to +the left and right edges, respectively. +.IP [10] +Control-Home sets the location cursor to the the first element in +the listbox, selects that element, and deselects everything else +in the listbox. +.IP [11] +Control-End sets the location cursor to the the last element in +the listbox, selects that element, and deselects everything else +in the listbox. +.IP [12] +In \fBextended\fR mode, Control-Shift-Home extends the selection +to the first element in the listbox and Control-Shift-End extends +the selection to the last element. +.IP [13] +In \fBmultiple\fR mode, Control-Shift-Home moves the location cursor +to the first element in the listbox and Control-Shift-End moves +the location cursor to the last element. +.IP [14] +The space and Select keys make a selection at the location cursor +(active element) just as if mouse button 1 had been pressed over +this element. +.IP [15] +In \fBextended\fR mode, Control-Shift-space and Shift-Select +extend the selection to the active element just as if button 1 +had been pressed with the Shift key down. +.IP [16] +In \fBextended\fR mode, the Escape key cancels the most recent +selection and restores all the elements in the selected range +to their previous selection state. +.IP [17] +Control-slash selects everything in the widget, except in +\fBsingle\fR and \fBbrowse\fR modes, in which case it selects +the active element and deselects everything else. +.IP [18] +Control-backslash deselects everything in the widget, except in +\fBbrowse\fR mode where it has no effect. +.IP [19] +The F16 key (labelled Copy on many Sun workstations) or Meta-w +copies the selection in the widget to the clipboard, if there is +a selection. + +.PP +The behavior of listboxes can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +listbox, widget diff --git a/doc/loadTk.n b/doc/loadTk.n new file mode 100644 index 0000000..16e3532 --- /dev/null +++ b/doc/loadTk.n @@ -0,0 +1,86 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) loadTk.n 1.5 97/08/18 17:44:43 +'\" +.so man.macros +.TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +loadTk \- Load Tk into a safe interpreter. +.SH SYNOPSIS +\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? +.BE + +Safe Tk is based on Safe Tcl, which provides a mechanism +that allows restricted and mediated +access to auto-loading and packages for safe interpreters. +Safe Tk adds the ability to configure the interpreter +for safe Tk operations and load Tk into safe +interpreters. + +.SH DESCRIPTION +.PP +The \fB::safe::loadTk\fR command initializes the required data structures +in the named safe interpreter and then loads Tk into it. +The command returns the name of the safe interpreter. +If \fB\-use\fR is specified, the window identified by the specified system +dependent identifier \fIwindowId\fR is used to contain the \fB``.''\fR +window of the safe interpreter; it can be any valid id, eventually +referencing a window belonging to another application. +Otherwise, a new toplevel window is created for the \fB``.''\fR window of +the safe interpreter. +See the \fBSECURITY ISSUES\fR section below for implementation details. + +.SH SECURITY ISSUES +.PP +Please read the \fBsafe\fR manual page for Tcl to learn about the basic +security considerations for Safe Tcl. +.PP +Information in the safe interpreter should never be trusted for security +purposes. +However, because Tk initialization of the safe interpreter do use +local information, it is unsafe if the safe interpreter +could have gained control before Tk is loaded. +This will be fixed in an upcoming release, by making Tk initialization in a +safe interpreter use only information found in the interpreter's master +instead of relying on the (un)safe interpreter state. +.PP +You should therefore use \fBsafe::loadTk $slave\fR as soon as possible +after \fBsafe::interpCreate\fR and before any code is evaluated in the safe +interpreter. +The preferred sequence is: +.CS +set slave [::safe::loadTk [::safe::interpCreate]] +.CE +If you want to prevent safe interpreters from loading Tk entirely, you +should create the interpreter as follows: +.CS +::safe::interpCreate \-nostatics \-accesspath \fI{directories...}\fR +.CE +and you must also insure that the virtual access path \fIdirectories\fR for +the interpreter does not contain a dynamically loadable version of Tk. +.PP +\fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master +interpreter to the virtual access path of the safe interpreter so that +auto-loading will work in the safe interpreter. +It also sets \fBenv(DISPLAY)\fR in the safe interpreter to the value of +\fBenv(DISPLAY)\fR in the master interpreter, if it exists. +Finally, it sets the slave's Tcl variable \fBargv\fR to \fB\-use\fR +\fIwindowId\fR in the safe interpreter. + +When \fB\-use\fR is not used, the new toplevel created is specially +decorated so the user is always aware that the user interface presented comes +from a potentially unsafe code and can easily delete the corresponding +interpreter. + +.SH "SEE ALSO" +safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) + +.SH KEYWORDS +alias, auto\-loading, auto_mkindex, load, master interpreter, safe +interpreter, slave interpreter, source diff --git a/doc/lower.n b/doc/lower.n new file mode 100644 index 0000000..f3a202c --- /dev/null +++ b/doc/lower.n @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) lower.n 1.9 96/06/14 14:19:56 +'\" +.so man.macros +.TH lower n 3.3 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +lower \- Change a window's position in the stacking order +.SH SYNOPSIS +\fBlower \fIwindow \fR?\fIbelowThis\fR? +.BE + +.SH DESCRIPTION +.PP +If the \fIbelowThis\fR argument is omitted then the command 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). +If \fIbelowThis\fR is specified then it must be the path name of +a window that is either a sibling of \fIwindow\fR or the descendant +of a sibling of \fIwindow\fR. +In this case the \fBlower\fR command will insert +\fIwindow\fR into the stacking order just below \fIbelowThis\fR +(or the ancestor of \fIbelowThis\fR that is a sibling of \fIwindow\fR); +this could end up either raising or lowering \fIwindow\fR. + +.SH "SEE ALSO" +raise + +.SH KEYWORDS +lower, obscure, stacking order diff --git a/doc/menu.n b/doc/menu.n new file mode 100644 index 0000000..6d37172 --- /dev/null +++ b/doc/menu.n @@ -0,0 +1,757 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) menu.n 1.61 97/10/31 12:58:40 +'\" +.so man.macros +.TH menu n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +menu \- Create and manipulate menu widgets +.SH SYNOPSIS +\fBmenu\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-background \-disabledforeground \-relief +\-activeborderwidth \-borderwidth \-font \-takefocus +\-activeforeground \-cursor \-foreground +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.VS +.OP \-postcommand postCommand Command +If this option is specified then it provides a Tcl command to execute +each time the menu is posted. The command is invoked by the \fBpost\fR +widget command before posting the menu. Note that in 8.0 on Macintosh +and Windows, all commands in a menu systems are executed before any +are posted. This is due to the limitations in the individual platforms' +menu managers. +.VE +.OP \-selectcolor selectColor Background +For menu entries that are check buttons or radio buttons, this option +specifies the color to display in the indicator when the check button +or radio button is selected. +.OP \-tearoff tearOff TearOff +This option must have a proper boolean value, which specifies +whether or not the menu should include a tear-off entry at the +top. If so, it will exist as entry 0 of the menu and the other +entries will number starting at 1. The default +menu bindings arrange for the menu to be torn off when the tear-off +entry is invoked. +.OP \-tearoffcommand tearOffCommand TearOffCommand +If this option has a non-empty value, then it specifies a Tcl command +to invoke whenever the menu is torn off. The actual command will +consist of the value of this option, followed by a space, followed +by the name of the menu window, followed by a space, followed by +the name of the name of the torn off menu window. For example, if +the option's is ``\fBa b\fR'' and menu \fB.x.y\fR is torn off to +create a new menu \fB.x.tearoff1\fR, then the command +``\fBa b .x.y .x.tearoff1\fR'' will be invoked. +.VS +.OP \-title title Title +The string will be used to title the window created when this menu is +torn off. If the title is NULL, then the window will have the title +of the menubutton or the text of the cascade item from which this menu +was invoked. +.OP \-type type Type +This option can be one of \fBmenubar\fR, \fBtearoff\fR, or +\fBnormal\fR, and is set when the menu is created. While the string +returned by the configuration database will change if this option is +changed, this does not affect the menu widget's behavior. This is used +by the cloning mechanism and is not normally set outside of the Tk +library. +.VE +.BE + +.SH INTRODUCTION +.PP +The \fBmenu\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 +or in the option database +to configure aspects of the menu such as its colors and font. +The \fBmenu\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.PP +.VS +A menu is a widget that displays a collection of one-line entries arranged +in one or more columns. 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. +.VE +.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 \fB\-label\fR, +\fB\-bitmap\fR, and \fB\-image\fR options for the entry. +If the \fB\-accelerator\fR option is specified for an entry then a second +textual field is displayed to the right of the label. The accelerator +typically describes a keystroke sequence that may be typed in the +application to cause the same result as invoking the menu 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 colors. +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. +.VS +.PP +Whenever a menu's active entry is changed, a <<MenuSelect>> virtual +event is send to the menu. The active item can then be queried from +the menu, and an action can be taken, such as setting +context-sensitive help text for the entry. +.VE + +.SH "COMMAND ENTRIES" +.PP +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 Tcl command is executed. The Tcl +command is specified with the \fB\-command\fR option. + +.SH "SEPARATOR ENTRIES" +.PP +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 behavior other than its display appearance. + +.SH "CHECKBUTTON ENTRIES" +.PP +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, a particular +value is stored in a particular global variable (as determined by +the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when +the entry is deselected another value (determined by the +\fB\-offvalue\fR option) 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 color given by the \fB-selectcolor\fR option for the entry; +otherwise the indicator's center is displayed in the background color for +the menu. If a \fB\-command\fR option is specified for a checkbutton +entry, then its value is evaluated as a Tcl command each time the entry +is invoked; this happens after toggling the entry's +selected state. + +.SH "RADIOBUTTON ENTRIES" +.PP +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 \fB\-value\fR and +\fB\-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 color given by the \fB\-selectcolor\fR option +for the entry; +otherwise the indicator's center is displayed in the background color for +the menu. If a \fB\-command\fR option is specified for a radiobutton +entry, then its value is evaluated as a Tcl command each time the entry +is invoked; this happens after selecting the entry. + +.SH "CASCADE ENTRIES" +.PP +A cascade entry is one with an associated menu (determined +by the \fB\-menu\fR option). Cascade entries allow the construction +of cascading menus. +The \fBpostcascade\fR widget command can be used to post and unpost +the associated menu just next to 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 +Tcl command of the form +.CS +\fImenu\fB post \fIx y\fR +.CE +where \fImenu\fR is the path name of the associated menu, and \fIx\fR +and \fIy\fR are the root-window coordinates of the upper-right +corner of the cascade entry. +.VS +On Unix, the lower-level menu is unposted by executing a Tcl command with +the form +.CS +\fImenu\fB unpost\fR +.CE +where \fImenu\fR is the name of the associated menu. +On other platforms, the platform's native code takes care of unposting the +menu. +.VE +.PP +.VS +If a \fB\-command\fR option is specified for a cascade entry then it is +evaluated as a Tcl command whenever the entry is invoked. This is not +supported on Windows. +.VE + +.SH "TEAR-OFF ENTRIES" +.PP +A tear-off entry appears at the top of the menu if enabled with the +\fBtearOff\fR option. It is not like other menu entries in that +it cannot be created with the \fBadd\fR widget command and +cannot be deleted with the \fBdelete\fR widget command. +When a tear-off entry is created it appears as a dashed line at +the top of the menu. Under the default bindings, invoking the +tear-off entry causes a torn-off copy to be made of the menu and +all of its submenus. + +.VS +.SH "MENUBARS" +.PP +Any menu can be set as a menubar for a toplevel window (see +\fBtoplevel\fR command for syntax). On the Macintosh, whenever the +toplevel is in front, this menu's cascade items will appear in the +menubar across the top of the main monitor. On Windows and Unix, this +menu's items will be displayed in a menubar accross the top of the +window. These menus will behave according to the interface guidelines +of their platforms. For every menu set as a menubar, a clone menu is +made. See the \fBCLONES\fR section for more information. +.VE + +.VS +.SH "SPECIAL MENUS IN MENUBARS" +.PP +Certain menus in a menubar will be treated specially. On the Macintosh, +access to the special Apple and Help menus is provided. On Windows, +access to the Windows System menu in each window is provided. On X Windows, +a special right-justified help menu is provided. In all cases, these +menus must be created with the command name of the menubar menu concatenated +with the special name. So for a menubar named .menubar, on the Macintosh, +the special menus would be .menubar.apple and .menubar.help; on Windows, +the special menu would be .menubar.system; on X Windows, the help +menu would be .menubar.help. +.PP +When Tk sees an Apple menu on the Macintosh, that menu's contents make +up the first items of the Apple menu on the screen whenever the window +containing the menubar is in front. The menu is the +first one that the user sees and has a title which is an Apple logo. +After all of the Tk-defined items, the menu will have a separator, +followed by all of the items in the user's Apple Menu Items folder. +Since the System uses a different menu definition procedure for +the Apple menu than Tk uses for its menus, and the system APIs do +not fully support everything Tk tries to do, the menu item will only +have its text displayed. No font attributes, images, bitmaps, or colors +will be displayed. In addition, a menu with a tearoff item will have +the tearoff item displayed as "(TearOff)". +.PP +When Tk see a Help menu on the Macintosh, the menu's contents are +appended to the standard help menu on the right of the user's menubar +whenever the user's menubar is in front. The first items in the menu +are provided by Apple. Similar to the Apple Menu, cusomization in this +menu is limited to what the system provides. +.PP +When Tk sees a System menu on Windows, its items are appended to the +system menu that the menubar is attached to. This menu has an icon +representing a spacebar, and can be invoked with the mouse or by typing +Alt+Spacebar. Due to limitations in the Windows API, any font changes, +colors, images, bitmaps, or tearoff images will not appear in the +system menu. +.PP +When Tk see a Help menu on X Windows, the menu is moved to be last in +the menubar and is right justified. +.VE + +.VS +.SH "CLONES" +.PP +When a menu is set as a menubar for a toplevel window, or when a menu +is torn off, a clone of the menu is made. This clone is a menu widget +in its own right, but it is a child of the original. Changes in the +configuration of the original are reflected in the +clone. Additionally, any cascades that are pointed to are also cloned +so that menu traversal will work right. Clones are destroyed when +either the tearoff or menubar goes away, or when the original menu is +destroyed. +.VE + +.SH "WIDGET COMMAND" +.PP +The \fBmenu\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior 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 +\fBactive\fR +Indicates the entry that is currently active. If no entry is +active then this form is equivalent to \fBnone\fR. This form may +not be abbreviated. +.TP 12 +\fBend\fR +Indicates the bottommost entry in the menu. If there are no +entries in the menu then this form is equivalent to \fBnone\fR. +This form may not be abbreviated. +.TP 12 +\fBlast\fR +Same as \fBend\fR. +.TP 12 +\fBnone\fR +Indicates ``no entry at all''; this is used most commonly with +the \fBactivate\fR option to deactivate all the entries in the +menu. In most cases the specification of \fBnone\fR causes +nothing to happen in the widget command. +This form may not be abbreviated. +.TP 12 +\fB@\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, ``\fB@0\fR'' indicates the top-most entry in the +window. +.TP 12 +\fIpattern\fR +If the index doesn't satisfy one of the above forms then this +form is used. \fIPattern\fR is pattern-matched against the label of +each entry in the menu, in order from the top down, until a +matching entry is found. The rules of \fBTcl_StringMatch\fR +are used. +.PP +The following widget commands are possible for menu widgets: +.TP +\fIpathName \fBactivate \fIindex\fR +Change the state of the entry indicated by \fIindex\fR to \fBactive\fR +and redisplay it using its active colors. +Any previously-active entry is deactivated. If \fIindex\fR +is specified as \fBnone\fR, or if the specified entry is +disabled, then the menu ends up with no active entry. +Returns an empty string. +.TP +\fIpathName \fBadd \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 \fBcascade\fR, +\fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, +or a unique abbreviation of one of the above. If additional arguments +are present, they specify any of the following options: +.RS +.TP +\fB\-activebackground \fIvalue\fR +Specifies a background color to use for displaying this entry when it +is active. +If this option is specified as an empty string (the default), then the +\fBactiveBackground\fR option for the overall menu is used. +If the \fBtk_strictMotif\fR variable has been set to request strict +Motif compliance, then this option is ignored and the \fB\-background\fR +option is used in its place. +This option is not available for separator or tear-off entries. +.TP +\fB\-activeforeground \fIvalue\fR +Specifies a foreground color to use for displaying this entry when it +is active. +If this option is specified as an empty string (the default), then the +\fBactiveForeground\fR option for the overall menu is used. +This option is not available for separator or tear-off entries. +.TP +\fB\-accelerator \fIvalue\fR +Specifies a string to display at the right side of the menu entry. +Normally describes an accelerator keystroke sequence that may be +typed to invoke the same function as the menu entry. This option +is not available for separator or tear-off entries. +.TP +\fB\-background \fIvalue\fR +Specifies a background color to use for displaying this entry when it +is in the normal state (neither active nor disabled). +If this option is specified as an empty string (the default), then the +\fBbackground\fR option for the overall menu is used. +This option is not available for separator or tear-off entries. +.TP +\fB\-bitmap \fIvalue\fR +Specifies a bitmap to display in the menu instead of a textual +label, in any of the forms accepted by \fBTk_GetBitmap\fR. +This option overrides the \fB\-label\fR option but may be reset +to an empty string to enable a textual label to be displayed. +If a \fB\-image\fR option has been specified, it overrides +\fB\-bitmap\fR. +This option is not available for separator or tear-off entries. +.VS +.TP +\fB\-columnbreak \fIvalue\fR +When this option is zero, the appears below the previous entry. When +this option is one, the menu appears at the top of a new column in the +menu. +.VE +.TP +\fB\-command \fIvalue\fR +Specifies a Tcl command to execute when the menu entry is invoked. +Not available for separator or tear-off entries. +.TP +\fB\-font \fIvalue\fR +Specifies the font to use when drawing the label or accelerator +string in this entry. +If this option is specified as an empty string (the default) then +the \fBfont\fR option for the overall menu is used. +This option is not available for separator or tear-off entries. +.TP +\fB\-foreground \fIvalue\fR +Specifies a foreground color to use for displaying this entry when it +is in the normal state (neither active nor disabled). +If this option is specified as an empty string (the default), then the +\fBforeground\fR option for the overall menu is used. +This option is not available for separator or tear-off entries. +.VS +.TP +\fB\-hidemargin \fIvalue\fR +Specifies whether the standard margins should be drawn for this menu +entry. This is useful when creating palette with images in them, i.e., +color palettes, pattern palettes, etc. 1 indicates that the margin for +the entry is hidden; 0 means that the margin is used. +.VE +.TP +\fB\-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 +\fBimage create\fR. +This option overrides the \fB\-label\fR and \fB\-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 or tear-off entries. +.TP +\fB\-indicatoron \fIvalue\fR +Available only for checkbutton and radiobutton entries. +\fIValue\fR is a boolean that determines whether or not the +indicator should be displayed. +.TP +\fB\-label \fIvalue\fR +Specifies a string to display as an identifying label in the menu +entry. Not available for separator or tear-off entries. +.TP +\fB\-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 +\fB\-offvalue \fIvalue\fR +Available only for checkbutton entries. Specifies the value to +store in the entry's associated variable when the entry is +deselected. +.TP +\fB\-onvalue \fIvalue\fR +Available only for checkbutton entries. Specifies the value to +store in the entry's associated variable when the entry is selected. +.TP +\fB\-selectcolor \fIvalue\fR +Available only for checkbutton and radiobutton entries. +Specifies the color to display in the indicator when the entry is +selected. +If the value is an empty string (the default) then the \fBselectColor\fR +option for the menu determines the indicator color. +.TP +\fB\-selectimage \fIvalue\fR +Available only for checkbutton and radiobutton entries. +Specifies an image to display in the entry (in place of +the \fB\-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 \fBimage create\fR. +This option is ignored unless the \fB\-image\fR option has +been specified. +.TP +\fB\-state \fIvalue\fR +Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, +or \fBdisabled\fR. In normal state the entry is displayed using the +\fBforeground\fR option for the menu and the \fBbackground\fR +option from the entry or the menu. +The active state is typically used when the pointer is over the entry. +In active state the entry is displayed using the \fBactiveForeground\fR +option for the menu along with the \fBactivebackground\fR option from +the entry. 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 +\fBdisabledForeground\fR option for the menu and the +\fBbackground\fR option from the entry. +This option is not available for separator entries. +.TP +\fB\-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 or tear-off entries. +.TP +\fB\-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 \fB\-label\fR option +for the entry as the value to store in the variable. +.TP +\fB\-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 \fBadd\fR widget command returns an empty string. +.RE +.TP +\fIpathName \fBcget\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 \fBmenu\fR +command. +.VS +.TP +\fIpathName\fR \fBclone\fR \fInewPathname ?cloneType?\fR +Makes a clone of the current menu named \fInewPathName\fR. This clone +is a menu in its own right, but any changes to the clone are +propogated to the original menu and vice versa. \fIcloneType\fR can be +\fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be +called outside of the Tk library. See the \fBCLONES\fR section for +more information. +.VE +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBmenu\fR +command. +.TP +\fIpathName \fBdelete \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. +Attempts to delete a tear-off menu entry are ignored (instead, you +should change the \fBtearOff\fR option to remove the tear-off entry). +.TP +\fIpathName \fBentrycget\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 \fBadd\fR +widget command. +.TP +\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions\fR? +This command is similar to the \fBconfigure\fR command, except that +it applies to the options for an individual entry, whereas \fBconfigure\fR +applies to the options for the menu as a whole. +\fIOptions\fR may have any of the values accepted by the \fBadd\fR +widget command. If \fIoptions\fR are specified, options are modified +as indicated +in the command and the command returns an empty string. +If no \fIoptions\fR are specified, returns a list describing +the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). +.TP +\fIpathName \fBindex \fIindex\fR +Returns the numerical index corresponding to \fIindex\fR, or +\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. +.TP +\fIpathName \fBinsert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR? +Same as the \fBadd\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 \fBadd\fR widget +command. It is not possible to insert new menu entries before the +tear-off entry, if the menu has one. +.TP +\fIpathName \fBinvoke \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 \fBinvoke\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 \fBinvoke\fR +widget command. +.TP +\fIpathName \fBpost \fIx y\fR +Arrange for the menu to be displayed on the screen at the root-window +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 \fBpostCommand\fR option has been specified, then its value is +executed as a Tcl script before posting the menu and the result of +that script is returned as the result of the \fBpost\fR widget +command. +If an error returns while executing the command, then the error is +returned without posting the menu. +.TP +\fIpathName \fBpostcascade \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 \fBtype \fIindex\fR +Returns the type of the menu entry given by \fIindex\fR. +This is the \fItype\fR argument passed to the \fBadd\fR widget +command when the entry was created, such as \fBcommand\fR +or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. +.TP +.VS +\fIpathName \fBunpost\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. This subcommand does not work on Windows and the +Macintosh, as those platforms have their own way of unposting menus. +.VE +.TP +\fIpathName \fByposition \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 "MENU CONFIGURATIONS" +.PP +The default bindings support four different ways of using menus: +.VS +.TP +\fBPulldown Menus in Menubar\fR +This is the most command case. You create a menu widget that will become the +menu bar. You then add cascade entries to this menu, specifying the +pull down menus you wish to use in your menu bar. You then create all +of the pulldowns. Once you have done this, specify the menu using the +\fB-menu\fR option of the toplevel's widget command. See the +\fBtoplevel\fR manual entry for details. +.VE +.TP +\fBPulldown Menus in Menu Buttons\fR +This is the compatable way to do menu bars. You create one menubutton +widget for each top-level menu, and typically you arrange a series of +menubuttons in a row in a menubar window. You also create the top-level menus +and any cascaded submenus, and tie them together with \fB\-menu\fR +options in menubuttons and cascade menu entries. The top-level menu must +be a child of the menubutton, and each submenu must be a child of the +menu that refers to it. Once you have done this, the default bindings +will allow users to traverse and invoke the tree of menus via its +menubutton; see the \fBmenubutton\fR manual entry for details. +.TP +\fBPopup Menus\fR +Popup menus typically post in response to a mouse button press or +keystroke. You create the popup menus and any cascaded submenus, +then you call the \fBtk_popup\fR procedure at the appropriate time +to post the top-level menu. +.TP +\fBOption Menus\fR +An option menu consists of a menubutton with an associated menu +that allows you to select one of several values. The current value +is displayed in the menubutton and is also stored in a global +variable. Use the \fBtk_optionMenu\fR procedure to create option +menubuttons and their menus. +.TP +\fBTorn-off Menus\fR +You create a torn-off menu by invoking the tear-off entry at +the top of an existing menu. The default bindings will create a new menu +that is a copy of the original menu and leave it permanently +posted as a top-level window. The torn-off menu behaves just +the same as the original menu. + +.SH "DEFAULT BINDINGS" +.PP +Tk automatically creates class bindings for menus that give them +the following default behavior: +.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] +The Space and Return keys invoke the active entry and +unpost the menu. +.IP [5] +If any of the entries in a menu have letters underlined with +with \fB\-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. +.IP [6] +The Escape key aborts a menu selection in progress without invoking any +entry. It also unposts the menu unless it is a torn-off menu. +.IP [7] +The Up and Down keys activate the next higher or lower entry +in the menu. When one end of the menu is reached, the active +entry wraps around to the other end. +.IP [8] +The Left key moves to the next menu to the left. +If the current menu is a cascaded submenu, then the submenu is +unposted and the current menu entry becomes the cascade entry +in the parent. +If the current menu is a top-level menu posted from a +menubutton, then the current menubutton is unposted and the +next menubutton to the left is posted. +Otherwise the key has no effect. +The left-right order of menubuttons is determined by their stacking +order: Tk assumes that the lowest menubutton (which by default +is the first one created) is on the left. +.IP [9] +The Right key moves to the next menu to the right. +If the current entry is a cascade entry, then the submenu is +posted and the current menu entry becomes the first entry +in the submenu. +Otherwise, if the current menu was posted from a +menubutton, then the current menubutton is unposted and the +next menubutton to the right is posted. +.PP +Disabled menu entries are non-responsive: they don't activate and +they ignore mouse button presses and releases. +.PP +The behavior of menus can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH BUGS +.PP +At present it isn't possible to use the +option database to specify values for the options to individual +entries. + +.SH KEYWORDS +menu, widget diff --git a/doc/menubar.n b/doc/menubar.n new file mode 100644 index 0000000..09ea053 --- /dev/null +++ b/doc/menubar.n @@ -0,0 +1,33 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) menubar.n 1.13 96/08/27 13:21:45 +'\" +.so man.macros +.TH tk_menuBar n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_menuBar, tk_bindForTraversal \- Obsolete support for menu bars +.SH SYNOPSIS +\fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR? +.sp +\fBtk_bindForTraversal \fIarg arg ... \fR +.BE + +.SH DESCRIPTION +.PP +These procedures were used in Tk 3.6 and earlier releases to help +manage pulldown menus and to implement keyboard traversal of menus. +In Tk 4.0 and later releases they are no +longer needed. Stubs for these procedures have been retained for +backward compatibility, but they have no effect. You should remove +calls to these procedures from your code, since eventually the +procedures will go away. + +.SH KEYWORDS +keyboard traversal, menu, menu bar, post diff --git a/doc/menubutton.n b/doc/menubutton.n new file mode 100644 index 0000000..6adae9d --- /dev/null +++ b/doc/menubutton.n @@ -0,0 +1,193 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) menubutton.n 1.36 97/10/31 12:58:49 +'\" +.so man.macros +.TH menubutton n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +menubutton \- Create and manipulate menubutton widgets +.SH SYNOPSIS +\fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-cursor \-highlightthickness \-takefocus +\-activeforeground \-disabledforeground \-image \-text +\-anchor \-font \-justify \-textvariable +\-background \-foreground \-padx \-underline +\-bitmap \-highlightbackground \-pady \-wraplength +\-borderwidth \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.VS +.OP \-direction direction Height +Specifies where the menu is going to be popup up. \fBabove\fR tries to +pop the menu above the menubutton. \fBbelow\fR tries to pop the menu +below the menubutton. \fBleft\fR tries to pop the menu to the left of +the menubutton. \fBright\fR tries to pop the menu to the right of the +menu button. \fBflush\fR pops the menu directly over the menubutton. +.VE +.OP \-height height Height +Specifies a desired height for the menubutton. +If an image or bitmap is being displayed in the menubutton then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in lines of text. +If this option isn't specified, the menubutton's desired height is computed +from the size of the image or bitmap or text being displayed in it. +.OP \-indicatoron indicatorOn IndicatorOn +The value must be a proper boolean value. If it is true then +a small indicator rectangle will be displayed on the right side +of the menubutton and the default menu bindings will treat this +as an option menubutton. If false then no indicator will be +displayed. +.OP \-menu menu MenuName +Specifies the path name of the menu associated with this menubutton. +The menu must be a child of the menubutton. +.OP \-state state State +Specifies one of three states for the menubutton: \fBnormal\fR, \fBactive\fR, +or \fBdisabled\fR. In normal state the menubutton is displayed using the +\fBforeground\fR and \fBbackground\fR options. The active state is +typically used when the pointer is over the menubutton. In active state +the menubutton is displayed using the \fBactiveForeground\fR and +\fBactiveBackground\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 \fBdisabledForeground\fR and +\fBbackground\fR options determine how the button is displayed. +.OP \-width width Width +Specifies a desired width for the menubutton. +If an image or bitmap is being displayed in the menubutton then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in characters. +If this option isn't specified, the menubutton's desired width is computed +from the size of the image or bitmap or text being displayed in it. +.BE + +.SH INTRODUCTION +.PP +The \fBmenubutton\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 on the command line +or in the option database +to configure aspects of the menubutton such as its colors, font, +text, and initial relief. The \fBmenubutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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 +or if wrapping occurs because of the \fBwrapLength\fR option) and +one of the characters may optionally be underlined using the +\fBunderline\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 is moved over +the menu before releasing the mouse button, the button release +causes the underlying menu entry to be invoked. When the button +is released, the menu is unposted. +.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 +in the same menu bar without releasing the mouse button, then the +menu of the first menubutton is unposted and the menu of the +new menubutton is posted instead. +.PP +There are several interactions between menubuttons and menus; see +the \fBmenu\fR manual entry for information on various menu configurations, +such as pulldown menus and option menus. + +.SH "WIDGET COMMAND" +.PP +The \fBmenubutton\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for menubutton widgets: +.TP +\fIpathName \fBcget\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 \fBmenubutton\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBmenubutton\fR +command. + +.SH "DEFAULT BINDINGS" +.PP +Tk automatically creates class bindings for menubuttons that give them +the following default behavior: +.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 menubutton: +its relief changes to raised and its associated menu is posted +under the menubutton. If the mouse is dragged down into the menu +with the button still down, and if the mouse button is then +released over an entry in the menu, the menubutton is unposted +and the menu entry is invoked. +.IP [3] +If button 1 is pressed over a menubutton and then released over that +menubutton, the menubutton stays posted: you can still move the mouse +over the menu and click button 1 on an entry to invoke it. +Once a menu entry has been invoked, the menubutton unposts itself. +.IP [4] +If button 1 is pressed over a menubutton and then dragged over some +other menubutton, the original menubutton unposts itself and the +new menubutton posts. +.IP [5] +If button 1 is pressed over a menubutton and released outside +any menubutton or menu, the menubutton unposts without invoking +any menu entry. +.IP [6] +When a menubutton is posted, its associated menu claims the input +focus to allow keyboard traversal of the menu and its submenus. +See the \fBmenu\fR manual entry for details on these bindings. +.IP [7] +If the \fBunderline\fR option has been specified for a menubutton +then keyboard traversal may be used to post the menubutton: +Alt+\fIx\fR, where \fIx\fR is the underlined character (or its +lower-case or upper-case equivalent), may be typed in any window +under the menubutton's toplevel to post the menubutton. +.IP [8] +The F10 key may be typed in any window to post the first menubutton +under its toplevel window that isn't disabled. +.IP [9] +If a menubutton has the input focus, the space and return keys +post the menubutton. +.PP +If the menubutton's state is \fBdisabled\fR then none of the above +actions occur: the menubutton is completely non-responsive. +.PP +The behavior of menubuttons can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +menubutton, widget diff --git a/doc/message.n b/doc/message.n new file mode 100644 index 0000000..19e2d82 --- /dev/null +++ b/doc/message.n @@ -0,0 +1,147 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) message.n 1.32 97/10/31 12:58:50 +'\" +.so man.macros +.TH message n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +message \- Create and manipulate message widgets +.SH SYNOPSIS +\fBmessage\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-anchor \-font \-highlightthickness \-takefocus +\-background \-foreground \-padx \-text +\-borderwidth \-highlightbackground \-pady \-textvariable +\-cursor \-highlightcolor \-relief \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-aspect aspect Aspect +Specifies a non-negative integer value indicating desired +aspect ratio for the text. The aspect ratio is specified as +100*width/height. 100 means the text should +be as wide as it is tall, 200 means the text should +be twice as wide as it is tall, 50 means the text should +be twice as tall as it is wide, and so on. +Used to choose line length for text if \fBwidth\fR option +isn't specified. +Defaults to 150. +.OP \-justify justify Justify +Specifies how to justify lines of text. +Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. Defaults +to \fBleft\fR. +This option works together with the \fBanchor\fR, \fBaspect\fR, +\fBpadX\fR, \fBpadY\fR, and \fBwidth\fR options to provide a variety +of arrangements of the text within the window. +The \fBaspect\fR and \fBwidth\fR options determine the amount of +screen space needed to display the text. +The \fBanchor\fR, \fBpadX\fR, and \fBpadY\fR options determine where this +rectangular area is displayed within the widget's window, and the +\fBjustify\fR option determines how each line is displayed within that +rectangular region. +For example, suppose \fBanchor\fR is \fBe\fR and \fBjustify\fR is +\fBleft\fR, and that the message window is much larger than needed +for the text. +The the text will displayed so that the left edges of all the lines +line up and the right edge of the longest line is \fBpadX\fR from +the right side of the window; the entire text block will be centered +in the vertical span of the window. +.OP \-width width Width +Specifies the length of lines in the window. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +If this option has a value greater than zero then the \fBaspect\fR +option is ignored and the \fBwidth\fR option determines the line +length. +If this option has a value less than or equal to zero, then +the \fBaspect\fR option determines the line length. +.BE + +.SH DESCRIPTION +.PP +The \fBmessage\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a message widget. +Additional +options, described above, may be specified on the command line +or in the option database +to configure aspects of the message such as its colors, font, +text, and initial relief. The \fBmessage\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.PP +A message is a widget that displays a textual string. A message +widget has three special features. First, it breaks up +its string into lines in order to produce a given aspect ratio +for the window. The line breaks are chosen at word boundaries +wherever possible (if not even a single word would fit on a +line, then the word will be split across lines). Newline characters +in the string will force line breaks; they can be used, for example, +to leave blank lines in the display. +.PP +The second feature of a message widget is justification. The text +may be displayed left-justified (each line starts at the left side of +the window), centered on a line-by-line basis, or right-justified +(each line ends at the right side of the window). +.PP +The third feature of a message widget is that it handles control +characters and non-printing characters specially. Tab characters +are replaced with enough blank space to line up on the next +8-character boundary. Newlines cause line breaks. Other control +characters (ASCII code less than 0x20) and characters not defined +in the font are displayed as a four-character sequence \fB\ex\fIhh\fR where +\fIhh\fR is the two-digit hexadecimal number corresponding to +the character. In the unusual case where the font doesn't contain +all of the characters in ``0123456789abcdef\ex'' then control +characters and undefined characters are not displayed at all. + +.SH "WIDGET COMMAND" +.PP +The \fBmessage\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for message widgets: +.TP +\fIpathName \fBcget\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 \fBmessage\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBmessage\fR +command. + +.SH "DEFAULT BINDINGS" +.PP +When a new message is created, it has no default event bindings: +messages are intended for output purposes only. + +.SH BUGS +.PP +Tabs don't work very well with text that is centered or right-justified. +The most common result is that the line is justified wrong. + +.SH KEYWORDS +message, widget diff --git a/doc/messageBox.n b/doc/messageBox.n new file mode 100644 index 0000000..7b6a5e6 --- /dev/null +++ b/doc/messageBox.n @@ -0,0 +1,90 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) messageBox.n 1.5 96/09/19 17:02:40 +'\" +.so man.macros +.TH tk_messageBox n 4.2 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_messageBox \- pops up a message window and waits for user response. +.SH SYNOPSIS +\fBtk_messageBox \fR?\fIoption value ...\fR? +.BE + +.SH DESCRIPTION +.PP +This procedure creates and displays a message window with an +application-specified message, an icon and a set of buttons. Each of +the buttons in the message window is identified by a unique symbolic +name (see the \fB\-type\fR options). After the message window is +popped up, \fBtk_messageBox\fR waits for the user to select one of the +buttons. Then it returns the symbolic name of the selected button. + +The following option-value pairs are supported: +.TP +\fB\-default\fR \fIname\fR +\fIName\fR gives the symbolic name of the default button for +this message window ('ok', 'cancel', and so on). See \fB\-type\fR +for a list of the symbolic names. If the message box has just one +button it will automatically be made the default, otherwise if this +option is not specified, there won't be any default button. +.TP +\fB\-icon\fR \fIiconImage\fR +Specifies an icon to display. \fIIconImage\fR must be one of the +following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or +\fBwarning\fR. If this option is not specified, then no icon will be +displayed. +.TP +\fB\-message\fR \fIstring\fR +Specifies the message to display in this message box. +.TP +\fB\-parent\fR \fIwindow\fR +Makes \fIwindow\fR the logical parent of the message box. The message +box is displayed on top of its parent window. +.TP +\fB\-title\fR \fItitleString\fR +Specifies a string to display as the title of the message box. The +default value is an empty string. +.TP +\fB\-type\fR \fIpredefinedType\fR +Arranges for a predefined set of buttons to be displayed. The +following values are possible for \fIpredefinedType\fR: +.RS +.TP 18 +\fBabortretryignore\fR +Displays three buttons whose symbolic names are \fBabort\fR, +\fBretry\fR and \fBignore\fR. +.TP 18 +\fBok\fR +Displays one button whose symbolic name is \fBok\fR. +.TP 18 +\fBokcancel\fR +Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR. +.TP 18 +\fBretrycancel\fR +Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR. +.TP 18 +\fByesno\fR +Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR. +.TP 18 +\fByesnocancel\fR +Displays three buttons whose symbolic names are \fByes\fR, \fBno\fR +and \fBcancel\fR. +.RE +.PP +.SH EXAMPLE +.CS +set answer [tk_messageBox \-message "Really quit?" \-type yesno \-icon question] +case $answer { + yes exit + no {tk_messageBox \-message "I know you like this application!" \-type ok} +} +.CE + +.SH KEYWORDS +message box diff --git a/doc/option.n b/doc/option.n new file mode 100644 index 0000000..33feaf8 --- /dev/null +++ b/doc/option.n @@ -0,0 +1,91 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) option.n 1.10 96/03/26 18:25:08 +'\" +.so man.macros +.TH option n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +option \- Add/retrieve window options to/from the option database +.SH SYNOPSIS +\fBoption add \fIpattern value \fR?\fIpriority\fR? +.sp +\fBoption clear\fR +.sp +\fBoption get \fIwindow name class\fR +.sp +\fBoption readfile \fIfileName \fR?\fIpriority\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBoption\fR command allows you to add entries to the Tk option +database or to retrieve options from the database. The \fBadd\fR +form of the command adds a new option to the database. +\fIPattern\fR contains +the option being specified, and consists of names and/or classes +separated by asterisks or dots, in the usual X format. \fIValue\fR +contains a text string to associate with \fIpattern\fR; this is the +value that will be returned in calls to \fBTk_GetOption\fR or by +invocations of the \fBoption get\fR command. If \fIpriority\fR +is specified, it indicates the priority level for this option (see +below for legal values); it defaults to \fBinteractive\fR. +This command always returns an empty string. +.PP +The \fBoption clear\fR command clears the option database. Default +options (from the +\fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR +file) will be reloaded automatically the next time an +option is added to the database or removed from it. This command +always returns an empty string. +.PP +The \fBoption get\fR command returns the value of the option +specified for \fIwindow\fR +under \fIname\fR and \fIclass\fR. If several entries in the option +database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then +the command returns whichever was created with highest +\fIpriority\fR level. If there are several matching +entries at the same priority level, then it returns whichever entry +was most recently entered into the option database. If there are +no matching entries, then the empty string is returned. +.PP +The \fBreadfile\fR form of the command reads \fIfileName\fR, +which should have the standard format for an +X resource database such as \fB.Xdefaults\fR, and adds all the +options specified in that file to the option database. If \fIpriority\fR +is specified, it indicates the priority level at which to enter the +options; \fIpriority\fR defaults to \fBinteractive\fR. +.PP +The \fIpriority\fR arguments to the \fBoption\fR command are +normally specified symbolically using one of the following values: +.TP +\fBwidgetDefault\fR +Level 20. Used for default values hard-coded into widgets. +.TP +\fBstartupFile\fR +Level 40. Used for options specified in application-specific +startup files. +.TP +\fBuserDefault\fR +Level 60. Used for options specified in user-specific defaults +files, such as \fB.Xdefaults\fR, resource databases loaded into +the X server, or user-specific startup files. +.TP +\fBinteractive\fR +Level 80. Used for options specified interactively after the application +starts running. If \fIpriority\fR isn't specified, it defaults to +this level. +.LP +Any of the above keywords may be abbreviated. In addition, priorities +may be specified numerically using integers between 0 and 100, +inclusive. The numeric form is probably a bad idea except for new priority +levels other than the ones given above. + +.SH KEYWORDS +database, option, priority, retrieve diff --git a/doc/optionMenu.n b/doc/optionMenu.n new file mode 100644 index 0000000..3303847 --- /dev/null +++ b/doc/optionMenu.n @@ -0,0 +1,40 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) optionMenu.n 1.5 96/03/26 18:25:21 +'\" +.so man.macros +.TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_optionMenu \- Create an option menubutton and its menu +.SH SYNOPSIS +\fBtk_optionMenu \fIw varName value \fR?\fIvalue value ...\fR? +.BE + +.SH DESCRIPTION +.PP +This procedure creates an option menubutton whose name is \fIw\fR, +plus an associated menu. +Together they allow the user to select one of the values +given by the \fIvalue\fR arguments. +The current value will be stored in the global variable whose +name is given by \fIvarName\fR and it will also be displayed as the label +in the option menubutton. +The user can click on the menubutton to display a menu containing +all of the \fIvalue\fRs and thereby select a new value. +Once a new value is selected, it will be stored in the variable +and appear in the option menubutton. +The current value can also be changed by setting the variable. +.PP +The return value from \fBtk_optionMenu\fR is the name of the menu +associated with \fIw\fR, so that the caller can change its configuration +options or manipulate it in other ways. + +.SH KEYWORDS +option menu diff --git a/doc/options.n b/doc/options.n new file mode 100644 index 0000000..8de9b76 --- /dev/null +++ b/doc/options.n @@ -0,0 +1,328 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) options.n 1.47 97/05/31 17:12:19 +'\" +.so man.macros +.TH options n 4.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +options \- Standard options supported by widgets +.BE + +.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. +.PP +In the descriptions below, ``Command-Line Name'' refers to the +switch used in class commands and \fBconfigure\fR widget commands to +set this value. For example, if an option's command-line switch is +\fB\-foreground\fR and there exists a widget \fB.a.b.c\fR, then the +command +.CS +\&\fB.a.b.c\0\0configure\0\0\-foreground black\fR +.CE +may be used to specify the value \fBblack\fR for the option in the +the widget \fB.a.b.c\fR. Command-line switches may be abbreviated, +as long as the abbreviation is unambiguous. +``Database Name'' refers to the option's name in the option database (e.g. +in .Xdefaults files). ``Database Class'' refers to the option's class value +in the option database. +.OP \-activebackground activeBackground Foreground +Specifies background color 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. +If strict Motif compliance has been requested by setting the +\fBtk_strictMotif\fR variable, this option will normally be +ignored; the normal background color will be used instead. +.VS +For some elements on Windows and Macintosh systems, the active color +will only be used while mouse button 1 is pressed over the element. +.VE +.OP \-activeborderwidth activeBorderWidth BorderWidth +Specifies a non-negative value indicating +the width of the 3-D border drawn around active elements. See above for +definition of active elements. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +This option is typically only available in widgets displaying more +than one element at a time (e.g. menus but not buttons). +.OP \-activeforeground activeForeground Background +Specifies foreground color to use when drawing active elements. +See above for definition of active elements. +.OP \-anchor anchor Anchor +Specifies how the information in a widget (e.g. text or a bitmap) +is to be displayed in the widget. +Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, +\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. +For example, \fBnw\fR means display the information such that its +top-left corner is at the top-left corner of the widget. +.OP "\-background or \-bg" background Background +Specifies the normal background color to use when displaying the +widget. +.OP \-bitmap bitmap Bitmap +Specifies a bitmap to display in the widget, in any of the forms +acceptable to \fBTk_GetBitmap\fR. +The exact way in which the bitmap is displayed may be affected by +other options such as \fBanchor\fR or \fBjustify\fR. +Typically, if this option is specified then it overrides other +options that specify a textual value to display in the widget; +the \fBbitmap\fR option may be reset to an empty string to re-enable +a text display. +In widgets that support both \fBbitmap\fR and \fBimage\fR options, +\fBimage\fR will usually override \fBbitmap\fR. +.OP "\-borderwidth or \-bd" borderWidth BorderWidth +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 \fBrelief\fR option typically determines +this). The value may also be used when drawing 3-D effects in the +interior of the widget. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +.OP \-cursor cursor Cursor +Specifies the mouse cursor to be used for the widget. +The value may have any of the forms acceptable to \fBTk_GetCursor\fR. +.OP \-disabledforeground disabledForeground DisabledForeground +Specifies foreground color to use when drawing a disabled element. +If the option is specified as an empty string (which is typically the +case on monochrome displays), disabled elements are drawn with the +normal foreground color but they are dimmed by drawing them +with a stippled fill pattern. +.OP \-exportselection exportSelection ExportSelection +Specifies whether or not a selection in the widget should also be +the X selection. +The value may have any of the forms accepted by \fBTcl_GetBoolean\fR, +such as \fBtrue\fR, \fBfalse\fR, \fB0\fR, \fB1\fR, \fByes\fR, or \fBno\fR. +If the selection is exported, then selecting in the widget deselects +the current X selection, selecting outside the widget deselects any +widget selection, and the widget will respond to selection retrieval +requests when it has a selection. The default is usually for widgets +to export selections. +.OP \-font font Font +Specifies the font to use when drawing text inside the widget. +.OP "\-foreground or \-fg" foreground Foreground +Specifies the normal foreground color to use when displaying the widget. +.OP \-highlightbackground highlightBackground HighlightBackground +Specifies the color to display in the traversal highlight region when +the widget does not have the input focus. +.OP \-highlightcolor highlightColor HighlightColor +Specifies the color to use for the traversal highlight rectangle that is +drawn around the widget when it has the input focus. +.OP \-highlightthickness highlightThickness HighlightThickness +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. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +If the value is zero, no focus highlight is drawn around the widget. +.OP \-image image Image +Specifies an image to display in the widget, which must have been +created with the \fBimage create\fR command. +Typically, if the \fBimage\fR option is specified then it overrides other +options that specify a bitmap or textual value to display in the widget; +the \fBimage\fR option may be reset to an empty string to re-enable +a bitmap or text display. +.OP \-insertbackground insertBackground Foreground +Specifies the color to use as background in the area covered by the +insertion cursor. This color will normally override either the normal +background for the widget (or the selection background if the insertion +cursor happens to fall in the selection). +.OP \-insertborderwidth insertBorderWidth BorderWidth +Specifies a non-negative value indicating the width +of the 3-D border to draw around the insertion cursor. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +.OP \-insertofftime insertOffTime OffTime +Specifies a non-negative integer value indicating the number of +milliseconds the insertion cursor should remain ``off'' in each blink cycle. +If this option is zero then the cursor doesn't blink: it is on +all the time. +.OP \-insertontime insertOnTime OnTime +Specifies a non-negative integer value indicating the number of +milliseconds the insertion cursor should remain ``on'' in each blink cycle. +.OP \-insertwidth insertWidth InsertWidth +Specifies a value indicating the total width of the insertion cursor. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +If a border has been specified for the insertion +cursor (using the \fBinsertBorderWidth\fR option), the border +will be drawn inside the width specified by the \fBinsertWidth\fR +option. +.OP \-jump jump Jump +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. +The option's value must be a boolean of the form accepted by +\fBTcl_GetBoolean\fR. +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). +.OP \-justify justify Justify +When there are multiple lines of text displayed in a widget, this +option determines how the lines line up with each other. +Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. +\fBLeft\fR means that the lines' left edges all line up, \fBcenter\fR +means that the lines' centers are aligned, and \fBright\fR means +that the lines' right edges line up. +.OP \-orient orient Orient +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. Must be either \fBhorizontal\fR +or \fBvertical\fR or an abbreviation of one of these. +.OP \-padx padX Pad +Specifies a non-negative value indicating how much extra space +to request for the widget in the X-direction. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +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. +.OP \-pady padY Pad +Specifies a non-negative value indicating how much extra space +to request for the widget in the Y-direction. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +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. +.OP \-relief relief Relief +Specifies the 3-D effect desired for the widget. Acceptable +values are \fBraised\fR, \fBsunken\fR, \fBflat\fR, \fBridge\fR, +\fBsolid\fR, and \fBgroove\fR. +The value +indicates how the interior of the widget should appear relative +to its exterior; for example, \fBraised\fR means the interior of +the widget should appear to protrude from the screen, relative to +the exterior of the widget. +.OP \-repeatdelay repeatDelay RepeatDelay +Specifies the number of milliseconds a button or key must be held +down before it begins to auto-repeat. Used, for example, on the +up- and down-arrows in scrollbars. +.OP \-repeatinterval repeatInterval RepeatInterval +Used in conjunction with \fBrepeatDelay\fR: once auto-repeat +begins, this option determines the number of milliseconds between +auto-repeats. +.OP \-selectbackground selectBackground Foreground +Specifies the background color to use when displaying selected +items. +.OP \-selectborderwidth selectBorderWidth BorderWidth +Specifies a non-negative value indicating the width +of the 3-D border to draw around selected items. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +.OP \-selectforeground selectForeground Background +Specifies the foreground color to use when displaying selected +items. +.OP \-setgrid setGrid SetGrid +Specifies a boolean value that determines whether this widget controls the +resizing grid for its top-level window. +This option is typically used in text widgets, where the information +in the widget has a natural size (the size of a character) and it makes +sense for the window's dimensions to be integral numbers of these units. +These natural window sizes form a grid. +If the \fBsetGrid\fR option is set to true then the widget will +communicate with the window manager so that when the user interactively +resizes the top-level window that contains the widget, the dimensions of +the window will be displayed to the user in grid units and the window +size will be constrained to integral numbers of grid units. +See the section GRIDDED GEOMETRY MANAGEMENT in the \fBwm\fR manual +entry for more details. +.OP \-takefocus takeFocus TakeFocus +Determines whether the window accepts the focus during keyboard +traversal (e.g., Tab and Shift-Tab). +Before setting the focus to a window, the traversal scripts +consult the value of the \fBtakeFocus\fR option. +A value of \fB0\fR means that the window should be skipped entirely +during keyboard traversal. +\fB1\fR means that the window should receive the input +focus as long as it is viewable (it and all of its ancestors are mapped). +An empty value for the option means that the traversal scripts make +the decision about whether or not to focus on the window: the current +algorithm is to skip the window if it is +disabled, if it has no key bindings, or if it is not viewable. +If the value has any other form, then the traversal scripts take +the value, append the name of the window to it (with a separator space), +and evaluate the resulting string as a Tcl script. +The script must return \fB0\fR, \fB1\fR, or an empty string: a +\fB0\fR or \fB1\fR value specifies whether the window will receive +the input focus, and an empty string results in the default decision +described above. +Note: this interpretation of the option is defined entirely by +the Tcl scripts that implement traversal: the widget implementations +ignore the option entirely, so you can change its meaning if you +redefine the keyboard traversal scripts. +.OP \-text text Text +Specifies a string 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 \fBanchor\fR or \fBjustify\fR. +.OP \-textvariable textVariable Variable +Specifies the name of a variable. The value of the variable is a text +string to be displayed inside the widget; if the variable value changes +then the widget will automatically update itself to reflect the new value. +The way in which the string is displayed in the widget depends on the +particular widget and may be determined by other options, such as +\fBanchor\fR or \fBjustify\fR. +.OP \-troughcolor troughColor Background +Specifies the color to use for the rectangular trough areas +in widgets such as scrollbars and scales. +.OP \-underline underline Underline +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. +.OP \-wraplength wrapLength WrapLength +For widgets that can perform word-wrapping, this option specifies +the maximum line length. +Lines that would exceed this length are wrapped onto the next line, +so that no line is longer than the specified length. +The value may be specified in any of the standard forms for +screen distances. +If this value is less than or equal to 0 then no wrapping is done: lines +will break only at newline characters in the text. +.OP \-xscrollcommand xScrollCommand ScrollCommand +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 Tcl command by concatenating the scroll 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 Tcl interpreter for execution. Typically the +\fBxScrollCommand\fR option consists of the path name of a scrollbar +widget followed by ``set'', e.g. ``.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. +.OP \-yscrollcommand yScrollCommand ScrollCommand +Specifies the prefix for a command used to communicate with vertical +scrollbars. This option is treated in the same way as the +\fBxScrollCommand\fR option, except that it is used for vertical +scrollbars and is provided by widgets that support vertical scrolling. +See the description of \fBxScrollCommand\fR for details +on how this option is used. + +.SH KEYWORDS +class, name, standard option, switch diff --git a/doc/pack-old.n b/doc/pack-old.n new file mode 100644 index 0000000..a0638b6 --- /dev/null +++ b/doc/pack-old.n @@ -0,0 +1,196 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) pack-old.n 1.12 96/03/26 18:25:44 +'\" +.so man.macros +.TH pack-old n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +pack \- Obsolete syntax for packer geometry manager +.SH SYNOPSIS +\fBpack after \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? +.sp +\fBpack append \fIparent \fIwindow options\fR ?\fIwindow options \fR...? +.sp +\fBpack before \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? +.sp +\fBpack unpack \fIwindow\fR +.BE + +.SH DESCRIPTION +.PP +\fINote: this manual entry describes the syntax for the \fBpack\fI +command as it existed before Tk version 3.3. +Although this syntax continues to be supported for backward +compatibility, it is obsolete and should not be used anymore. +At some point in the future it may cease to be supported.\fR +.PP +The packer is a geometry manager that arranges the +children of a parent by packing them in order around the edges of +the parent. The first child is placed against one side of +the window, occupying the entire span of the window along that +side. This reduces the space remaining for other children as +if the side had been moved in by the size of the first child. +Then the next child is placed against one side of the remaining +cavity, and so on until all children have been placed or there +is no space left in the cavity. +.PP +The \fBbefore\fR, \fBafter\fR, and \fBappend\fR forms of the \fBpack\fR +command are used to insert one or more children into the packing order +for their parent. The \fBbefore\fR form inserts the children before +window \fIsibling\fR in the order; all of the other windows must be +siblings of \fIsibling\fR. The \fBafter\fR form inserts the windows +after \fIsibling\fR, and the \fBappend\fR form appends one or more +windows to the end of the packing order for \fIparent\fR. If a +\fIwindow\fR named in any of these commands is already packed in +its parent, it is removed from its current position in the packing +order and repositioned as indicated by the command. All of these +commands return an empty string as result. +.PP +The \fBunpack\fR form of the \fBpack\fR command removes \fIwindow\fR +from the packing order of its parent and unmaps it. After the +execution of this command the packer will no longer manage +\fIwindow\fR's geometry. +.PP +The placement of each child is actually a four-step process; +the \fIoptions\fR argument following each \fIwindow\fR consists of +a list of one or more fields that govern the placement of that +window. In the discussion below, the term \fIcavity\fR refers +to the space left in a parent when a particular child is placed +(i.e. all the space that wasn't claimed by earlier children in +the packing order). The term \fIparcel\fR refers to the space +allocated to a particular child; this is not necessarily the +same as the child window's final geometry. +.PP +The first step in placing a child is to determine which side of +the cavity it will lie against. Any one of the following options +may be used to specify a side: +.TP +\fBtop\fR +Position the child's parcel against the top of the cavity, +occupying the full width of the cavity. +.TP +\fBbottom\fR +Position the child's parcel against the bottom of the cavity, +occupying the full width of the cavity. +.TP +\fBleft\fR +Position the child's parcel against the left side of the cavity, +occupying the full height of the cavity. +.TP +\fBright\fR +Position the child's parcel against the right side of the cavity, +occupying the full height of the cavity. +.LP +At most one of these options should be specified for any given window. +If no side is specified, then the default is \fBtop\fR. +.PP +The second step is to decide on a parcel for the child. For \fBtop\fR +and \fBbottom\fR windows, the desired parcel width is normally the cavity +width and the desired parcel height is the window's requested height, +as passed to \fBTk_GeometryRequest\fR. For \fBleft\fR and \fBright\fR +windows, the desired parcel height is normally the cavity height and the +desired width is the window's requested width. However, extra +space may be requested for the window using any of the following +options: +.TP 12 +\fBpadx \fInum\fR +Add \fInum\fR pixels to the window's requested width before computing +the parcel size as described above. +.TP 12 +\fBpady \fInum\fR +Add \fInum\fR pixels to the window's requested height before computing +the parcel size as described above. +.TP 12 +\fBexpand\fR +This option requests that the window's parcel absorb any extra space left over +in the parent's cavity after packing all the children. +The amount of space left over depends on the sizes requested by the +other children, and may be zero. If several windows have all specified +\fBexpand\fR then the extra width will be divided equally among all the +\fBleft\fR and \fBright\fR windows that specified \fBexpand\fR and +the extra height will be divided equally among all the \fBtop\fR and +\fBbottom\fR windows that specified \fBexpand\fR. +.LP +If the desired width or height for a parcel is larger than the corresponding +dimension of the cavity, then the cavity's dimension is used instead. +.PP +The third step in placing the window is to decide on the window's +width and height. The default is for the window to receive either +its requested width and height or the those of the parcel, whichever +is smaller. If the parcel is larger than the window's requested +size, then the following options may be used to expand the +window to partially or completely fill the parcel: +.TP +\fBfill\fR +Set the window's size to equal the parcel size. +.TP +\fBfillx\fR +Increase the window's width to equal the parcel's width, but retain +the window's requested height. +.TP +\fBfilly\fR +Increase the window's height to equal the parcel's height, but retain +the window's requested width. +.PP +The last step is to decide the window's location within its parcel. +If the window's size equals the parcel's size, then the window simply +fills the entire parcel. If the parcel is larger than the window, +then one of +the following options may be used to specify where the window should +be positioned within its parcel: +.TP 15 +\fBframe center\fR +Center the window in its parcel. This is the default if no framing +option is specified. +.TP 15 +\fBframe n\fR +Position the window with its top edge centered on the top edge of +the parcel. +.TP 15 +\fBframe ne\fR +Position the window with its upper-right corner at the upper-right corner +of the parcel. +.TP 15 +\fBframe e\fR +Position the window with its right edge centered on the right edge of +the parcel. +.TP 15 +\fBframe se\fR +Position the window with its lower-right corner at the lower-right corner +of the parcel. +.TP 15 +\fBframe s\fR +Position the window with its bottom edge centered on the bottom edge of +the parcel. +.TP 15 +\fBframe sw\fR +Position the window with its lower-left corner at the lower-left corner +of the parcel. +.TP 15 +\fBframe w\fR +Position the window with its left edge centered on the left edge of +the parcel. +.TP 15 +\fBframe nw\fR +Position the window with its upper-left corner at the upper-left corner +of the parcel. +.PP +The packer manages the mapped/unmapped state of all the packed +children windows. It automatically maps the windows when it packs +them, and it unmaps any windows for which there was no space left +in the cavity. +.PP +The packer makes geometry requests on behalf of the parent windows +it manages. For each parent window it requests a size large enough +to accommodate all the options specified by all the packed children, +such that zero space would be leftover for \fBexpand\fR options. + +.SH KEYWORDS +geometry manager, location, packer, parcel, size diff --git a/doc/pack.n b/doc/pack.n new file mode 100644 index 0000000..580f252 --- /dev/null +++ b/doc/pack.n @@ -0,0 +1,266 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) pack.n 1.19 96/08/27 13:21:48 +'\" +.so man.macros +.TH pack n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +pack \- Geometry manager that packs around edges of cavity +.SH SYNOPSIS +\fBpack \fIoption arg \fR?\fIarg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBpack\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 \fBpack\fR command can have any of several forms, depending +on the \fIoption\fR argument: +.TP +\fBpack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? +If the first argument to \fBpack\fR is a window name (any value +starting with ``.''), then the command is processed in the same +way as \fBpack configure\fR. +.TP +\fBpack 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 +\fB\-after \fIother\fR +\fIOther\fR must 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 +\fB\-anchor \fIanchor\fR +\fIAnchor\fR must be a valid anchor position such as \fBn\fR +or \fBsw\fR; it specifies where to position each slave in its +parcel. +Defaults to \fBcenter\fR. +.TP +\fB\-before \fIother\fR +\fIOther\fR must 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 +\fB\-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 \fB1\fR +or \fBno\fR. +Defaults to 0. +.TP +\fB\-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 +\fBnone\fR +Give the slave its requested dimensions plus any internal padding +requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. +.TP +\fBx\fR +Stretch the slave horizontally to fill the entire width of its +parcel (except leave external padding as specified by \fB\-padx\fR). +.TP +\fBy\fR +Stretch the slave vertically to fill the entire height of its +parcel (except leave external padding as specified by \fB\-pady\fR). +.TP +\fBboth\fR +Stretch the slave both horizontally and vertically. +.RE +.TP +\fB\-in \fIother\fR +Insert the slave(s) at the end of the packing order for the master +window given by \fIother\fR. +.TP +\fB\-ipadx \fIamount\fR +\fIAmount\fR specifies how much horizontal internal padding to +leave on each side of the slave(s). +\fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. +It defaults to 0. +.TP +\fB\-ipady \fIamount\fR +\fIAmount\fR specifies how much vertical internal padding to +leave on each side of the slave(s). +\fIAmount\fR defaults to 0. +.TP +\fB\-padx \fIamount\fR +\fIAmount\fR specifies how much horizontal external padding to +leave on each side of the slave(s). +\fIAmount\fR defaults to 0. +.TP +\fB\-pady \fIamount\fR +\fIAmount\fR specifies how much vertical external padding to +leave on each side of the slave(s). +\fIAmount\fR defaults to 0. +.TP +\fB\-side \fIside\fR +Specifies which side of the master the slave(s) will be packed against. +Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. +Defaults to \fBtop\fR. +.LP +If no \fB\-in\fR, \fB\-after\fR or \fB\-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 +\fBpack 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 +\fBpack 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 \fBpack configure\fR. +The first two elements of the list are ``\fB\-in \fImaster\fR'' where +\fImaster\fR is the slave's master. +.TP +\fBpack propagate \fImaster\fR ?\fIboolean\fR? +If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\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 \fB0\fR or +\fB1\fR to indicate whether propagation is currently enabled +for \fImaster\fR. +Propagation is enabled by default. +.TP +\fBpack 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" +.PP +For each master the packer maintains an ordered list of slaves +called the \fIpacking list\fR. +The \fB\-in\fR, \fB\-after\fR, and \fB\-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 \fB\-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 \fB\-ipady\fR and \fB\-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 \fB\-ipadx\fR and \fB\-padx\fR options. +The parcel may be enlarged further because of the \fB\-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 \fB\-ipadx\fR option and the height will normally be +the slave's requested height plus twice its \fB\-ipady\fR +option. +However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR +then the width of the slave is expanded to fill the width of the parcel, +minus twice the \fB\-padx\fR option. +If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR +then the height of the slave is expanded to fill the width of the parcel, +minus twice the \fB\-pady\fR option. +.IP [3] +The packer positions the slave over its parcel. +If the slave is smaller than the parcel then the \fB\-anchor\fR +option determines where in the parcel the slave will be placed. +If \fB\-padx\fR or \fB\-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" +.PP +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 \fB\-expand\fR option is set. +Extra horizontal space is distributed among the expandable +slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR, +and extra vertical space is distributed among the expandable +slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. + +.SH "GEOMETRY PROPAGATION" +.PP +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 \fBpack 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" +.PP +The master for each slave must either be the slave's parent +(the default) or a descendant of the slave's parent. +This restriction is necessary to guarantee that the +slave can be placed over any part of its master that is +visible without danger of the slave being clipped by its parent. + +.SH "PACKING ORDER" +.PP +If the master for a slave is not its parent then you must make sure +that the slave is higher in the stacking order than the master. +Otherwise the master will obscure the slave and it will appear as +if the slave hasn't been packed correctly. +The easiest way to make sure the slave is higher than the master is +to create the master window first: the most recently created window +will be highest in the stacking order. +Or, you can use the \fBraise\fR and \fBlower\fR commands to change +the stacking order of either the master or the slave. + +.SH KEYWORDS +geometry manager, location, packer, parcel, propagation, size diff --git a/doc/palette.n b/doc/palette.n new file mode 100644 index 0000000..7a54eb9 --- /dev/null +++ b/doc/palette.n @@ -0,0 +1,73 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) palette.n 1.5 96/03/26 18:26:11 +'\" +.so man.macros +.TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_setPalette, tk_bisque \- Modify the Tk color palette +.SH SYNOPSIS +\fBtk_setPalette \fIbackground\fR +.sp +\fBtk_setPalette \fIname value \fR?\fIname value ...\fR? +.sp +\fBtk_bisque\fR +.BE + +.SH DESCRIPTION +.PP +The \fBtk_setPalette\fR procedure changes the color scheme for Tk. +It does this by modifying the colors of existing widgets and by changing +the option database so that future widgets will use the new color scheme. +If \fBtk_setPalette\fR is invoked with a single argument, the +argument is the name of a color to use as the normal background +color; \fBtk_setPalette\fR will compute a complete color palette +from this background color. +Alternatively, the arguments to \fBtk_setPalette\fR may consist of any number +of \fIname\fR\-\fIvalue\fR pairs, where the first argument of the pair +is the name of an option in the Tk option database and the second +argument is the new value to use for that option. The following +database names are currently supported: +.DS L +.ta 4c 8c +\fBactiveBackground foreground selectColor +activeForeground highlightBackground selectBackground +background highlightColor selectForeground +disabledForeground insertBackground troughColor\fR +.DE +\fBtk_setPalette\fR tries to compute reasonable defaults for any +options that you don't specify. You can specify options other +than the above ones and Tk will change those options on widgets as +well. This feature may be useful if you are using custom widgets with +additional color options. +.PP +Once it has computed the new value to use for each of the color options, +\fBtk_setPalette\fR scans the widget hierarchy to modify the options +of all existing widgets. For each widget, it checks to see if any +of the above options is defined for the widget. If so, and if the +option's current value is the default, then the value is changed; if +the option has a value other than the default, \fBtk_setPalette\fR +will not change it. The default for an option is the one provided by +the widget (\fB[lindex [$w configure $option] 3]\fR) unless +\fBtk_setPalette\fR has been run previously, in which case it is the +value specified in the previous invocation of \fBtk_setPalette\fR. +.PP +After modifying all the widgets in the application, \fBtk_setPalette\fR +adds options to the option database to change the defaults for +widgets created in the future. The new options are added at +priority \fBwidgetDefault\fR, so they will be overridden by options +from the .Xdefaults file or options specified on the command-line +that creates a widget. +.PP +The procedure \fBtk_bisque\fR is provided for backward compatibility: +it restores the application's colors to the light brown (``bisque'') +color scheme used in Tk 3.6 and earlier versions. + +.SH KEYWORDS +bisque, color, palette diff --git a/doc/photo.n b/doc/photo.n new file mode 100644 index 0000000..1e26f8a --- /dev/null +++ b/doc/photo.n @@ -0,0 +1,344 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +'\" "@(#) photo.n 1.12 97/10/14 10:52:30" +'\" +.so man.macros +.TH photo n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +photo \- Full-color images +.SH SYNOPSIS +\fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? +.BE + +.SH DESCRIPTION +.PP +A photo is an image whose pixels can display any color or be +transparent. A photo image is stored internally in full color (24 +bits per pixel), and is displayed using dithering if necessary. Image +data for a photo image can be obtained from a file or a string, or it +can be supplied from +C code through a procedural interface. At present, only GIF and PPM/PGM +formats are supported, but an interface exists to allow additional +image file formats to be added easily. A photo image is transparent +in regions where no image data has been supplied. + +.SH "CREATING PHOTOS" +.PP +Like all images, photos are created using the \fBimage create\fR +command. +Photos support the following \fIoptions\fR: +.TP +\fB\-data \fIstring\fR +Specifies the contents of the image as a string. The format of the +string must be one of those for which there is an image file format +handler that will accept string data. If both the \fB\-data\fR +and \fB\-file\fR options are specified, the \fB\-file\fR option takes +precedence. +.TP +\fB\-format \fIformat-name\fR +Specifies the name of the file format for the data specified with the +\fB\-data\fR or \fB\-file\fR option. +.TP +\fB\-file \fIname\fR +\fIname\fR gives the name of a file that is to be read to supply data +for the photo image. The file format must be one of those for which +there is an image file format handler that can read data. +.TP +\fB\-gamma \fIvalue\fR +Specifies that the colors allocated for displaying this image in a +window should be corrected for a non-linear display with the specified +gamma exponent value. (The intensity produced by most +CRT displays is a power function of the input value, to a good +approximation; gamma is the exponent and is typically around 2). +The value specified must be greater than zero. The default +value is one (no correction). In general, values greater than one +will make the image lighter, and values less than one will make it +darker. +.TP +\fB\-height \fInumber\fR +Specifies the height of the image, in pixels. This option is useful +primarily in situations where the user wishes to build up the contents +of the image piece by piece. A value of zero (the default) allows the +image to expand or shrink vertically to fit the data stored in it. +.TP +\fB\-palette \fIpalette-spec\fR +Specifies the resolution of the color cube to be allocated for +displaying this image, and thus the number of colors used from the +colormaps of the windows where it is displayed. The +\fIpalette-spec\fR string may be either a single decimal number, +specifying the number of shades of gray to use, or three decimal +numbers separated by slashes (/), specifying the number of shades of +red, green and blue to use, respectively. If the first form (a single +number) is used, the image will be displayed in monochrome (i.e., +grayscale). +.TP +\fB\-width \fInumber\fR +Specifies the width of the image, in pixels. This option is useful +primarily in situations where the user wishes to build up the contents +of the image piece by piece. A value of zero (the default) allows the +image to expand or shrink horizontally to fit the data stored in it. + +.SH "IMAGE COMMAND" +.PP +When a photo image is created, Tk also creates a new command +whose name is the same as the image. +This command may be used to invoke various operations +on the image. +It has the following general form: +.CS +\fIimageName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +.PP +Those options that write data to the image generally expand the size +of the image, if necessary, to accommodate the data written to the +image, unless the user has specified non-zero values for the +\fB\-width\fR and/or \fB\-height\fR configuration options, in which +case the width and/or height, respectively, of the image will not be +changed. +.PP +The following commands are possible for photo images: +.TP +\fIimageName \fBblank\fR +Blank the image; that is, set the entire image to have no data, so it +will be displayed as transparent, and the background of whatever +window it is displayed in will show through. +.TP +\fIimageName \fBcget\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 +\fBimage create photo\fR command. +.TP +\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options for the image. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the +\fBimage create photo\fR command. +.TP +\fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? +Copies a region from the image called \fIsourceImage\fR (which must +be a photo image) to the image called \fIimageName\fR, possibly with +pixel zooming and/or subsampling. If no options are specified, this +command copies the whole of \fIsourceImage\fR into \fIimageName\fR, +starting at coordinates (0,0) in \fIimageName\fR. The following +options may be specified: +.RS +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the source image to be copied. +(\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of +the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the +default value is the bottom-right corner of the source image. The +pixels copied will include the left and top edges of the specified +rectangle but not the bottom or right edges. If the \fB\-from\fR +option is not given, the default is the whole source image. +.TP +\fB\-to \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the destination image to be +affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite +corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, +the default value is (\fIx1,y1\fR) plus the size of the source +region (after subsampling and zooming, if specified). If \fIx2\fR and +\fIy2\fR are specified, the source region will be replicated if +necessary to fill the destination region in a tiled fashion. +.TP +\fB\-shrink\fR +Specifies that the size of the destination image should be reduced, if +necessary, so that the region being copied into is at the bottom-right +corner of the image. This option will not affect the width or height +of the image if the user has specified a non-zero value for the +\fB\-width\fR or \fB\-height\fR configuration option, respectively. +.TP +\fB\-zoom \fIx y\fR +Specifies that the source region should be magnified by a factor of +\fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR +is not given, the default value is the same as \fIx\fR. With this +option, each pixel in the source image will be expanded into a block +of \fIx\fR x \fIy\fR pixels in the destination image, all the same +color. \fIx\fR and \fIy\fR must be greater than 0. +.TP +\fB\-subsample \fIx y\fR +Specifies that the source image should be reduced in size by using +only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in +the Y direction. Negative values will cause the image to be flipped +about the Y or X axes, respectively. If \fIy\fR is not given, the +default value is the same as \fIx\fR. +.RE +.TP +\fIimageName \fBget\fR \fIx y\fR +Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the +image as a list of three integers between 0 and 255, representing the +red, green and blue components respectively. +.TP +\fIimageName \fBput \fIdata\fR ?\fB\-to\fI x1 y1 x2 y2\fR? +Sets pixels in \fIimageName\fR to the colors specified in \fIdata\fR. +\fIdata\fR is used to form a two-dimensional array of pixels that are +then copied into the \fIimageName\fR. \fIdata\fR is structured as a +list of horizontal rows, from top to bottom, each of which is a list +of colors, listed from left to right. Each color may be specified by name +(e.g., blue) or in hexadecimal form (e.g., #2376af). The +\fB\-to\fR option can be used to specify the area of \fIimageName\fR to be +affected. If only \fIx1\fR and \fIy1\fR are given, the area affected +has its top-left corner at (\fIx1,y1\fR) and is the same size as the +array given in \fIdata\fR. If all four coordinates are given, they +specify diagonally opposite corners of the affected rectangle, and the +array given in \fIdata\fR will be replicated as necessary in the X and +Y directions to fill the rectangle. +.TP +\fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? +Reads image data from the file named \fIfilename\fR into the image. +This command first searches the list of +image file format handlers for a handler that can interpret the data +in \fIfilename\fR, and then reads the image in \fIfilename\fR into +\fIimageName\fR (the destination image). The following options may be +specified: +.RS +.TP +\fB\-format \fIformat-name\fR +Specifies the format of the image data in \fIfilename\fR. +Specifically, only image file format handlers whose names begin with +\fIformat-name\fR will be used while searching for an image data +format handler to read the data. +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the image file data to be copied +to the destination image. If only \fIx1\fR and \fIy1\fR are +specified, the region extends from (\fIx1,y1\fR) to the bottom-right +corner of the image in the image file. If all four coordinates are +specified, they specify diagonally opposite corners or the region. +The default, if this option is not specified, is the whole of the +image in the image file. +.TP +\fB\-shrink\fR +If this option, the size of \fIimageName\fR will be reduced, if +necessary, so that the region into which the image file data are read +is at the bottom-right corner of the \fIimageName\fR. This option +will not affect the width or height of the image if the user has +specified a non-zero value for the \fB\-width\fR or \fB\-height\fR +configuration option, respectively. +.TP +\fB\-to \fIx y\fR +Specifies the coordinates of the top-left corner of the region of +\fIimageName\fR into which data from \fIfilename\fR are to be read. +The default is (0,0). +.RE +.TP +\fIimageName \fBredither\fR +The dithering algorithm used in displaying photo images propagates +quantization errors from one pixel to its neighbors. +If the image data for \fIimageName\fR is supplied in pieces, the +dithered image may not be exactly correct. Normally the difference is +not noticeable, but if it is a problem, this command can be used to +recalculate the dithered image in each window where the image is +displayed. +.TP +\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? +Writes image data from \fIimageName\fR to a file named \fIfilename\fR. +The following options may be specified: +.RS +.TP +\fB\-format\fI format-name\fR +Specifies the name of the image file format handler to be used to +write the data to the file. Specifically, this subcommand searches +for the first handler whose name matches a initial substring of +\fIformat-name\fR and which has the capability to write an image +file. If this option is not given, this subcommand uses the first +handler that has the capability to write an image file. +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular region of \fIimageName\fR to be written to the +image file. If only \fIx1\fR and \fIy1\fR are specified, the region +extends from \fI(x1,y1)\fR to the bottom-right corner of +\fIimageName\fR. If all four coordinates are given, they specify +diagonally opposite corners of the rectangular region. The default, +if this option is not given, is the whole image. +.RE +.SH "IMAGE FORMATS" +.PP +The photo image code is structured to allow handlers for additional +image file formats to be added easily. The photo image code maintains +a list of these handlers. Handlers are added to the list by +registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The +standard Tk distribution comes with handlers for PPM/PGM and GIF formats, +which are automatically registered on initialization. +.PP +When reading an image file or processing +string data specified with the \fB\-data\fR configuration option, the +photo image code invokes each handler in turn until one is +found that claims to be able to read the data in the file or string. +Usually this will find the correct handler, but if it doesn't, the +user may give a format name with the \fB\-format\fR option to specify +which handler to use. In fact the photo image code will try those +handlers whose names begin with the string specified for the +\fB\-format\fR option (the comparison is case-insensitive). For +example, if the user specifies \fB\-format gif\fR, then a handler +named GIF87 or GIF89 may be invoked, but a handler +named JPEG may not (assuming that such handlers had been +registered). +.PP +When writing image data to a file, the processing of the +\fB\-format\fR option is slightly different: the string value given +for the \fB\-format\fR option must begin with the complete name of the +requested handler, and may contain additional information following +that, which the handler can use, for example, to specify which variant +to use of the formats supported by the handler. + +.SH "COLOR ALLOCATION" +.PP +When a photo image is displayed in a window, the photo image code +allocates colors to use to display the image and dithers the image, if +necessary, to display a reasonable approximation to the image using +the colors that are available. The colors are allocated as a color +cube, that is, the number of colors allocated is the product of the +number of shades of red, green and blue. +.PP +Normally, the number of +colors allocated is chosen based on the depth of the window. For +example, in an 8-bit PseudoColor window, the photo image code will +attempt to allocate seven shades of red, seven shades of green and +four shades of blue, for a total of 198 colors. In a 1-bit StaticGray +(monochrome) window, it will allocate two colors, black and white. In +a 24-bit DirectColor or TrueColor window, it will allocate 256 shades +each of red, green and blue. Fortunately, because of the way that +pixel values can be combined in DirectColor and TrueColor windows, +this only requires 256 colors to be allocated. If not all of the +colors can be allocated, the photo image code reduces the number of +shades of each primary color and tries again. +.PP +The user can exercise some control over the number of colors that a +photo image uses with the \fB\-palette\fR configuration option. If +this option is used, it specifies the maximum number of shades of +each primary color to try to allocate. It can also be used to force +the image to be displayed in shades of gray, even on a color display, +by giving a single number rather than three numbers separated by +slashes. + +.SH CREDITS +.PP +The photo image type was designed and implemented by Paul Mackerras, +based on his earlier photo widget and some suggestions from +John Ousterhout. + +.SH KEYWORDS +photo, image, color diff --git a/doc/place.n b/doc/place.n new file mode 100644 index 0000000..6084118 --- /dev/null +++ b/doc/place.n @@ -0,0 +1,237 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) place.n 1.13 96/08/27 13:21:49 +'\" +.so man.macros +.TH place n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +place \- Geometry manager for fixed or rubber-sheet placement +.SH SYNOPSIS +\fBplace \fIwindow option value \fR?\fIoption value ...\fR? +.sp +\fBplace configure \fIwindow option value \fR?\fIoption value ...\fR? +.sp +\fBplace forget \fIwindow\fR +.sp +\fBplace info \fIwindow\fR +.sp +\fBplace slaves \fIwindow\fR +.BE + +.SH DESCRIPTION +.PP +The placer is a geometry manager for Tk. +It provides simple fixed placement of windows, where you specify +the exact size and location of one window, called the \fIslave\fR, +within another window, called the \fImaster\fR. +The placer also provides rubber-sheet placement, where you specify the +size and location of the slave in terms of the dimensions of +the master, so that the slave changes size and location +in response to changes in the size of the master. +Lastly, the placer allows you to mix these styles of placement so +that, for example, the slave has a fixed width and height but is +centered inside the master. +.PP +If the first argument to the \fBplace\fR command is a window path +name or \fBconfigure\fR then the command arranges for the placer +to manage the geometry of a slave whose path name is \fIwindow\fR. +The remaining arguments consist of one or more \fIoption\-value\fR +pairs that specify the way in which \fIwindow\fR's +geometry is managed. +If the placer is already managing \fIwindow\fR, then the +\fIoption\-value\fR pairs modify the configuration for \fIwindow\fR. +In this form the \fBplace\fR command returns an empty string as result. +The following \fIoption\-value\fR pairs are supported: +.TP +\fB\-in \fImaster\fR +\fIMaster\fR specifes the path name of the window relative +to which \fIwindow\fR is to be placed. +\fIMaster\fR must either be \fIwindow\fR's parent or a descendant +of \fIwindow\fR's parent. +In addition, \fImaster\fR and \fIwindow\fR must both be descendants +of the same top-level window. +These restrictions are necessary to guarantee +that \fIwindow\fR is visible whenever \fImaster\fR is visible. +If this option isn't specified then the master defaults to +\fIwindow\fR's parent. +.TP +\fB\-x \fIlocation\fR +\fILocation\fR specifies the x-coordinate within the master window +of the anchor point for \fIwindow\fR. +The location is specified in screen units (i.e. any of the forms +accepted by \fBTk_GetPixels\fR) and need not lie within the bounds +of the master window. +.TP +\fB\-relx \fIlocation\fR +\fILocation\fR specifies the x-coordinate within the master window +of the anchor point for \fIwindow\fR. +In this case the location is specified in a relative fashion +as a floating-point number: 0.0 corresponds to the left edge +of the master and 1.0 corresponds to the right edge of the master. +\fILocation\fR need not be in the range 0.0\-1.0. +If both \fB\-x\fR and \fB\-relx\fR are specified for a slave +then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR +positions the left edge of the slave 2 pixels to the left of the +center of its master. +.TP +\fB\-y \fIlocation\fR +\fILocation\fR specifies the y-coordinate within the master window +of the anchor point for \fIwindow\fR. +The location is specified in screen units (i.e. any of the forms +accepted by \fBTk_GetPixels\fR) and need not lie within the bounds +of the master window. +.TP +\fB\-rely \fIlocation\fR +\fILocation\fR specifies the y-coordinate within the master window +of the anchor point for \fIwindow\fR. +In this case the value is specified in a relative fashion +as a floating-point number: 0.0 corresponds to the top edge +of the master and 1.0 corresponds to the bottom edge of the master. +\fILocation\fR need not be in the range 0.0\-1.0. +If both \fB\-y\fR and \fB\-rely\fR are specified for a slave +then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR +positions the top edge of the slave 3 pixels below the +center of its master. +.TP +\fB\-anchor \fIwhere\fR +\fIWhere\fR specifies which point of \fIwindow\fR is to be positioned +at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, +\fB\-relx\fR, and \fB\-rely\fR options. +The anchor point is in terms of the outer area of \fIwindow\fR +including its border, if any. +Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of +\fIwindow\fR's border will appear at the given (x,y) location +in the master. +The anchor position defaults to \fBnw\fR. +.TP +\fB\-width \fIsize\fR +\fISize\fR specifies the width for \fIwindow\fR in screen units +(i.e. any of the forms accepted by \fBTk_GetPixels\fR). +The width will be the outer width of \fIwindow\fR including its +border, if any. +If \fIsize\fR is an empty string, or if no \fB\-width\fR +or \fB\-relwidth\fR option is specified, then the width requested +internally by the window will be used. +.TP +\fB\-relwidth \fIsize\fR +\fISize\fR specifies the width for \fIwindow\fR. +In this case the width is specified as a floating-point number +relative to the width of the master: 0.5 means \fIwindow\fR will +be half as wide as the master, 1.0 means \fIwindow\fR will have +the same width as the master, and so on. +If both \fB\-width\fR and \fB\-relwidth\fR are specified for a slave, +their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR +makes the slave 5 pixels wider than the master. +.TP +\fB\-height \fIsize\fR +\fISize\fR specifies the height for \fIwindow\fR in screen units +(i.e. any of the forms accepted by \fBTk_GetPixels\fR). +The height will be the outer dimension of \fIwindow\fR including its +border, if any. +If \fIsize\fR is an empty string, or if no \fB\-height\fR or +\fB\-relheight\fR option is specified, then the height requested +internally by the window will be used. +.TP +\fB\-relheight \fIsize\fR +\fISize\fR specifies the height for \fIwindow\fR. +In this case the height is specified as a floating-point number +relative to the height of the master: 0.5 means \fIwindow\fR will +be half as high as the master, 1.0 means \fIwindow\fR will have +the same height as the master, and so on. +If both \fB\-height\fR and \fB\-relheight\fR are specified for a slave, +their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR +makes the slave 2 pixels shorter than the master. +.TP +\fB\-bordermode \fImode\fR +\fIMode\fR determines the degree to which borders within the +master are used in determining the placement of the slave. +The default and most common value is \fBinside\fR. +In this case the placer considers the area of the master to +be the innermost area of the master, inside any border: +an option of \fB\-x 0\fR corresponds to an x-coordinate just +inside the border and an option of \fB\-relwidth 1.0\fR +means \fIwindow\fR will fill the area inside the master's +border. +If \fImode\fR is \fBoutside\fR then the placer considers +the area of the master to include its border; +this mode is typically used when placing \fIwindow\fR +outside its master, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. +Lastly, \fImode\fR may be specified as \fBignore\fR, in which +case borders are ignored: the area of the master is considered +to be its official X area, which includes any internal border but +no external border. A bordermode of \fBignore\fR is probably +not very useful. +.PP +If the same value is specified separately with +two different options, such as \fB\-x\fR and \fB\-relx\fR, then +the most recent option is used and the older one is ignored. +.PP +The \fBplace slaves\fR command returns a list of all the slave +windows for which \fIwindow\fR is the master. +If there are no slaves for \fIwindow\fR then an empty string is +returned. +.PP +The \fBplace forget\fR command causes the placer to stop managing +the geometry of \fIwindow\fR. As a side effect of this command +\fIwindow\fR will be unmapped so that it doesn't appear on the +screen. +If \fIwindow\fR isn't currently managed by the placer then the +command has no effect. +\fBPlace forget\fR returns an empty string as result. +.PP +The \fBplace info\fR command returns a list giving the current +configuration of \fIwindow\fR. +The list consists of \fIoption\-value\fR pairs in exactly the +same form as might be specified to the \fBplace configure\fR +command. +If the configuration of a window has been retrieved with +\fBplace info\fR, that configuration can be restored later by +first using \fBplace forget\fR to erase any existing information +for the window and then invoking \fBplace configure\fR with +the saved information. + +.SH "FINE POINTS" +.PP +It is not necessary for the master window to be the parent +of the slave window. +This feature is useful in at least two situations. +First, for complex window layouts it means you can create a +hierarchy of subwindows whose only purpose +is to assist in the layout of the parent. +The ``real children'' of the parent (i.e. the windows that +are significant for the application's user interface) can be +children of the parent yet be placed inside the windows +of the geometry-management hierarchy. +This means that the path names of the ``real children'' +don't reflect the geometry-management hierarchy and users +can specify options for the real children +without being aware of the structure of the geometry-management +hierarchy. +.PP +A second reason for having a master different than the slave's +parent is to tie two siblings together. +For example, the placer can be used to force a window always to +be positioned centered just below one of its +siblings by specifying the configuration +.CS +\fB\-in \fIsibling\fB \-relx 0.5 \-rely 1.0 \-anchor n \-bordermode outside\fR +.CE +Whenever the sibling is repositioned in the future, the slave +will be repositioned as well. +.PP +Unlike many other geometry managers (such as the packer) +the placer does not make any attempt to manipulate the geometry of +the master windows or the parents of slave windows (i.e. it doesn't +set their requested sizes). +To control the sizes of these windows, make them windows like +frames and canvases that provide configuration options for this purpose. + +.SH KEYWORDS +geometry manager, height, location, master, place, rubber sheet, slave, width diff --git a/doc/popup.n b/doc/popup.n new file mode 100644 index 0000000..7728e6c --- /dev/null +++ b/doc/popup.n @@ -0,0 +1,33 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) popup.n 1.5 96/03/26 18:26:45 +'\" +.so man.macros +.TH tk_popup n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_popup \- Post a popup menu +.SH SYNOPSIS +\fBtk_popup \fImenu x y \fR?\fIentry\fR? +.BE + +.SH DESCRIPTION +.PP +This procedure posts a menu at a given position on the screen and +configures Tk so that the menu and its cascaded children can be +traversed with the mouse or the keyboard. +\fIMenu\fR is the name of a menu widget and \fIx\fR and \fIy\fR +are the root coordinates at which to display the menu. +If \fIentry\fR is omitted or an empty string, the +menu's upper left corner is positioned at the given point. +Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and +the menu will be positioned so that the entry is positioned over +the given point. + +.SH KEYWORDS +menu, popup diff --git a/doc/radiobutton.n b/doc/radiobutton.n new file mode 100644 index 0000000..58e4d22 --- /dev/null +++ b/doc/radiobutton.n @@ -0,0 +1,233 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) radiobutton.n 1.41 97/10/31 12:58:51 +'\" +.so man.macros +.TH radiobutton n 4.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +radiobutton \- Create and manipulate radiobutton widgets +.SH SYNOPSIS +\fBradiobutton\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-cursor \-highlightthickness \-takefocus +\-activeforeground \-disabledforeground \-image \-text +\-anchor \-font \-justify \-textvariable +\-background \-foreground \-padx \-underline +\-bitmap \-highlightbackground \-pady \-wraplength +\-borderwidth \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +Specifies a Tcl 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 (\fB\-variable\fR option) will +be updated before the command is invoked. +.OP \-height height Height +Specifies a desired height for the button. +If an image or bitmap is being displayed in the button then the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in lines of text. +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. +.OP \-indicatoron indicatorOn IndicatorOn +Specifies whether or not the indicator should be drawn. Must be a +proper boolean value. If false, the \fBrelief\fR option is +ignored and the widget's relief is always sunken if the widget is +selected and raised otherwise. +.OP \-selectcolor selectColor Background +Specifies a background color to use when the button is selected. +If \fBindicatorOn\fR is true then the color applies to the indicator. +Under Windows, this color is used as the background for the indicator +regardless of the select state. +If \fBindicatorOn\fR is false, this color is used as the background +for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, +whenever the widget is selected. +If specified as an empty string then no special color is used for +displaying when the widget is selected. +.OP \-selectimage selectImage SelectImage +Specifies an image to display (in place of the \fBimage\fR option) +when the radiobutton is selected. +This option is ignored unless the \fBimage\fR option has been +specified. +.OP \-state state State +Specifies one of three states for the radiobutton: \fBnormal\fR, \fBactive\fR, +or \fBdisabled\fR. In normal state the radiobutton is displayed using the +\fBforeground\fR and \fBbackground\fR options. The active state is +typically used when the pointer is over the radiobutton. In active state +the radiobutton is displayed using the \fBactiveForeground\fR and +\fBactiveBackground\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 \fBdisabledForeground\fR and +\fBbackground\fR options determine how the radiobutton is displayed. +.OP \-value value Value +Specifies value to store in the button's associated variable whenever +this button is selected. +.OP \-variable variable Variable +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 \fBselectedButton\fR. +.OP \-width width Width +Specifies a desired width for the button. +If an image or bitmap is being displayed in the button, the value is in +screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); +for text it is in characters. +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. +.BE + +.SH DESCRIPTION +.PP +The \fBradiobutton\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 +or in the option database +to configure aspects of the radiobutton such as its colors, font, +text, and initial relief. The \fBradiobutton\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.PP +.VS +A radiobutton is a widget that displays a textual string, bitmap or image +and a diamond or circle called an \fIindicator\fR. +.VE +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 +or if wrapping occurs because of the \fBwrapLength\fR option) and +one of the characters may optionally be underlined using the +\fBunderline\fR option. A radiobutton has +all of the behavior of a simple button: it can display itself in either +of three different ways, according to the \fBstate\fR option; +it can be made to appear +raised, sunken, or flat; it can be made to flash; and it invokes +a Tcl 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 +.VS +drawn with a selected appearance, and +a Tcl variable associated with the radiobutton is set to a particular +value (normally 1). +Under Unix, the indicator is drawn with a sunken relief and a special +color. Under Windows, the indicator is drawn with a round mark inside. +If the radiobutton is not selected, then the indicator is drawn with a +deselected appearance, and the associated variable is +set to a different value (typically 0). +Under Unix, the indicator is drawn with a raised relief and no special +color. Under Windows, the indicator is drawn without a round mark inside. +.VE +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 \fBselectedButton\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 or in the option database. +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" +.PP +The \fBradiobutton\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for radiobutton widgets: +.TP +\fIpathName \fBcget\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 \fBradiobutton\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBradiobutton\fR +command. +.TP +\fIpathName \fBdeselect\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 \fBflash\fR +Flashes the radiobutton. This is accomplished by redisplaying the radiobutton +several times, alternating between active and normal colors. At +the end of the flash the radiobutton is left in the same normal/active +state as when the command was invoked. +This command is ignored if the radiobutton's state is \fBdisabled\fR. +.TP +\fIpathName \fBinvoke\fR +Does just what would have happened if the user invoked the radiobutton +with the mouse: selects the button and invokes +its associated Tcl command, if there is one. +The return value is the return value from the Tcl command, or an +empty string if there is no command associated with the radiobutton. +This command is ignored if the radiobutton's state is \fBdisabled\fR. +.TP +\fIpathName \fBselect\fR +Selects the radiobutton and sets the associated variable to the +value corresponding to this widget. + +.SH BINDINGS +.PP +Tk automatically creates class bindings for radiobuttons that give them +the following default behavior: +.VS +.IP [1] +On Unix systems, a radiobutton activates whenever the mouse passes +over it and deactivates whenever the mouse leaves the radiobutton. On +Mac and Windows systems, when mouse button 1 is pressed over a +radiobutton, the button activates whenever the mouse pointer is inside +the button, and deactivates whenever the mouse pointer leaves the +button. +.VE +.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). +.IP [3] +When a radiobutton has the input focus, the space key causes the radiobutton +to be invoked. +.PP +If the radiobutton's state is \fBdisabled\fR then none of the above +actions occur: the radiobutton is completely non-responsive. +.PP +The behavior of radiobuttons can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +radiobutton, widget diff --git a/doc/raise.n b/doc/raise.n new file mode 100644 index 0000000..3769bbe --- /dev/null +++ b/doc/raise.n @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) raise.n 1.9 96/06/14 14:20:02 +'\" +.so man.macros +.TH raise n 3.3 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +raise \- Change a window's position in the stacking order +.SH SYNOPSIS +\fBraise \fIwindow \fR?\fIaboveThis\fR? +.BE + +.SH DESCRIPTION +.PP +If the \fIaboveThis\fR argument is omitted then the command 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). +If \fIaboveThis\fR is specified then it must be the path name of +a window that is either a sibling of \fIwindow\fR or the descendant +of a sibling of \fIwindow\fR. +In this case the \fBraise\fR command will insert +\fIwindow\fR into the stacking order just above \fIaboveThis\fR +(or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); +this could end up either raising or lowering \fIwindow\fR. + +.SH "SEE ALSO" +lower + +.SH KEYWORDS +obscure, raise, stacking order diff --git a/doc/scale.n b/doc/scale.n new file mode 100644 index 0000000..3557b1c --- /dev/null +++ b/doc/scale.n @@ -0,0 +1,246 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) scale.n 1.32 97/10/31 12:58:51 +'\" +.so man.macros +.TH scale n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +scale \- Create and manipulate scale widgets +.SH SYNOPSIS +\fBscale\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-font \-highlightthickness \-repeatinterval +\-background \-foreground \-orient \-takefocus +\-borderwidth \-highlightbackground \-relief \-troughcolor +\-cursor \-highlightcolor \-repeatdelay +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-bigincrement bigIncrement BigIncrement +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. +.OP \-command command Command +Specifies the prefix of a Tcl 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. +.OP \-digits digits Digits +An integer specifying how many significant digits should be retained +when converting the value of the scale to a string. +If the number is less than or equal to zero, then the scale picks +the smallest value that guarantees that every possible slider +position prints as a different string. +.OP \-from from From +A real value corresponding to the left or top end of the scale. +.OP \-label label Label +A string to display as a label for the scale. For +vertical scales the label is displayed just to the right of the +top end of the scale. For horizontal scales the label is displayed +just above the left end of the scale. If the option is specified +as an empty string, no label is displayed. +.OP \-length length Length +Specifies the desired long dimension of the scale in screen units +(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). +For vertical scales this is the scale's height; for horizontal scales +it is the scale's width. +.OP \-resolution resolution Resolution +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). +.OP \-showvalue showValue ShowValue +Specifies a boolean value indicating whether or not the current +value of the scale is to be displayed. +.OP \-sliderlength sliderLength SliderLength +Specfies the size of the slider, measured in screen units along the slider's +long dimension. The value may be specified in any of the forms acceptable +to \fBTk_GetPixels\fR. +.OP \-sliderrelief sliderRelief SliderRelief +Specifies the relief to use when drawing the slider, such as \fBraised\fR +or \fBsunken\fR. +.OP \-state state State +Specifies one of three states for the scale: \fBnormal\fR, +\fBactive\fR, or \fBdisabled\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 color +specified by the \fBactiveBackground\fR option. +.OP \-tickinterval tickInterval TickInterval +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. +.OP \-to to To +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 \fBfrom\fR option. +.OP \-variable variable Variable +Specifies the name of a global variable to link to the scale. Whenever the +value of the variable changes, the scale will update to reflect this +value. +Whenever the scale is manipulated interactively, the variable +will be modified to reflect the scale's new value. +.OP \-width width Width +Specifies the desired narrow dimension of the trough in screen units +(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). +For vertical scales this is the trough's width; for horizontal scales +this is the trough's height. +.BE + +.SH DESCRIPTION +.PP +The \fBscale\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 +or in the option database +to configure aspects of the scale such as its colors, orientation, +and relief. The \fBscale\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.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 \fBfrom\fR, \fBto\fR, and +\fBresolution\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 Tcl +command is invoked (using the \fBcommand\fR option) to notify +other interested widgets of the change. +In addition, the value +of the scale can be linked to a Tcl variable (using the \fBvariable\fR +option), so that changes in either are reflected in the other. +.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 left of the current value +(just below the trough for horizontal scales). Each of these three +annotations may be enabled or disabled using the +configuration options. + +.SH "WIDGET COMMAND" +.PP +The \fBscale\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for scale widgets: +.TP +\fIpathName \fBcget\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 \fBscale\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBscale\fR +command. +.TP +\fIpathName \fBcoords \fR?\fIvalue\fR? +Returns a list whose elements are the x and y coordinates of +the point along the centerline of the trough that corresponds +to \fIvalue\fR. +If \fIvalue\fR is omitted then the scale's current value is used. +.TP +\fIpathName \fBget\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 \fBidentify\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 \fBslider\fR means that the point is over +the slider; \fBtrough1\fR means that the point is over the +portion of the slider above or to the left of the slider; +and \fBtrough2\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 \fBset\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 +.PP +Tk automatically creates class bindings for scales that give them +the following default behavior. +Where the behavior is different for vertical and horizontal scales, +the horizontal behavior 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 \fBresolution\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 button 1 is pressed in the trough with the Control key down, +the slider moves all the way to the end of its range, in the +direction towards the mouse cursor. +.IP [4] +If button 2 is pressed, the scale's value is set to the mouse +position. If the mouse is dragged with button 2 down, the scale's +value changes with the drag. +.IP [5] +The Up and Left keys move the slider up (left) by the value +of the \fBresolution\fR option. +.IP [6] +The Down and Right keys move the slider down (right) by the value +of the \fBresolution\fR option. +.IP [7] +Control-Up and Control-Left move the slider up (left) by the +value of the \fBbigIncrement\fR option. +.IP [8] +Control-Down and Control-Right move the slider down (right) by the +value of the \fBbigIncrement\fR option. +.IP [9] +Home moves the slider to the top (left) end of its range. +.IP [10] +End moves the slider to the bottom (right) end of its range. +.PP +If the scale is disabled using the \fBstate\fR option then +none of the above bindings have any effect. +.PP +The behavior of scales can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +scale, slider, trough, widget diff --git a/doc/scrollbar.n b/doc/scrollbar.n new file mode 100644 index 0000000..ba8e824 --- /dev/null +++ b/doc/scrollbar.n @@ -0,0 +1,340 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) scrollbar.n 1.33 97/10/31 12:58:52 +'\" +.so man.macros +.TH scrollbar n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +scrollbar \- Create and manipulate scrollbar widgets +.SH SYNOPSIS +\fBscrollbar\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-highlightbackground \-orient \-takefocus +\-background \-highlightcolor \-relief \-troughcolor +\-borderwidth \-highlightthickness \-repeatdelay +\-cursor \-jump \-repeatinterval +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-activerelief activeRelief ActiveRelief +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. +.OP \-command command Command +Specifies the prefix of a Tcl 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 Tcl 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 \fB.t xview\fR or \fB.t yview\fR, consisting of the +name of a widget and either \fBxview\fR (if the scrollbar is for +horizontal scrolling) or \fByview\fR (for vertical scrolling). +All scrollable widgets have \fBxview\fR and \fByview\fR commands +that take exactly the additional arguments appended by the scrollbar +as described in SCROLLING COMMANDS below. +.OP \-elementborderwidth elementBorderWidth BorderWidth +Specifies the width of borders drawn around the internal elements +of the scrollbar (the two arrows and the slider). The value may +have any of the forms acceptable to \fBTk_GetPixels\fR. +If this value is less than zero, the value of the \fBborderWidth\fR +option is used in its place. +.OP \-width width Width +Specifies the desired narrow dimension of the scrollbar window, +not including 3-D border, if any. For vertical +scrollbars this will be the width and for horizontal scrollbars +this will be the height. +The value may have any of the forms acceptable to \fBTk_GetPixels\fR. +.BE + +.SH DESCRIPTION +.PP +The \fBscrollbar\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 or in the option database to configure aspects of the scrollbar +such as its colors, orientation, and relief. +The \fBscrollbar\fR command returns its \fIpathName\fR argument. +At the time this command is invoked, there must not exist a window +named \fIpathName\fR, but \fIpathName\fR's parent must exist. +.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 an 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" +.PP +A scrollbar displays five elements, which are referred to in the +widget commands for the scrollbar: +.TP 10 +\fBarrow1\fR +The top or left arrow in the scrollbar. +.TP 10 +\fBtrough1\fR +The region between the slider and \fBarrow1\fR. +.TP 10 +\fBslider\fR +The rectangle that indicates what is visible in the associated widget. +.TP 10 +\fBtrough2\fR +The region between the slider and \fBarrow2\fR. +.TP 10 +\fBarrow2\fR +The bottom or right arrow in the scrollbar. + +.SH "WIDGET COMMAND" +.PP +The \fBscrollbar\fR command creates a new Tcl command whose +name is \fIpathName\fR. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for scrollbar widgets: +.TP +\fIpathName \fBactivate \fR?\fIelement\fR? +Marks the element indicated by \fIelement\fR as active, which +causes it to be displayed as specified by the \fBactiveBackground\fR +and \fBactiveRelief\fR options. +The only element values understood by this command are \fBarrow1\fR, +\fBslider\fR, or \fBarrow2\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 \fBcget\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 \fBscrollbar\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBscrollbar\fR +command. +.TP +\fIpathName \fBdelta \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 \fBfraction \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 \fBget\fR +Returns the scrollbar settings in the form of a list whose +elements are the arguments to the most recent \fBset\fR widget command. +.TP +\fIpathName \fBidentify\fR \fIx y\fR +Returns the name of the element under the point given by \fIx\fR and +\fIy\fR (such as \fBarrow1\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 \fBset\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" +.PP +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 Tcl command +generated from the scrollbar's \fB\-command\fR option. +The command may take any of the following forms. +In each case, \fIprefix\fR is the contents of the +\fB\-command\fR option, which usually has a form like \fB.t yview\fR +.TP +\fIprefix \fBmoveto \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 \fBscroll \fInumber \fBunits\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 \fBscroll \fInumber \fBpages\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 "OLD COMMAND SYNTAX" +.PP +In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget +commands used a different form. +This form is still supported for backward compatibility, but it +is deprecated. +In the old command syntax, the \fBset\fR widget command has the +following form: +.TP +\fIpathName \fBset\fR \fItotalUnits windowUnits firstUnit lastUnit\fR +In this form the arguments are all integers. +\fITotalUnits\fR gives the total size of the object being displayed in the +associated widget. The meaning of one unit depends on the associated +widget; for example, in a text editor widget units might +correspond to lines of +text. \fIWindowUnits\fR indicates the total number of units that +can fit in the associated window at one time. \fIFirstUnit\fR +and \fIlastUnit\fR give the indices of the first and last units +currently visible in the associated window (zero corresponds to the +first unit of the object). +.LP +Under the old syntax the \fBget\fR widget command returns a list +of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR, +\fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR +widget command. +.PP +The commands generated by scrollbars also have a different form +when the old syntax is being used: +.TP +\fIprefix\fR \fIunit\fR +\fIUnit\fR is an integer that indicates what should appear at +the top or left of the associated widget's window. +It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR +arguments to the \fBset\fR widget command. +.LP +The most recent \fBset\fR widget command determines whether or not +to use the old syntax. +If it is given two real arguments then the new syntax will be +used in the future, and if it is given four integer arguments then +the old syntax will be used. + +.SH BINDINGS +Tk automatically creates class bindings for scrollbars that give them +the following default behavior. +If the behavior is different for vertical and horizontal scrollbars, +the horizontal behavior is described in parentheses. + +.IP [1] +Pressing button 1 over \fBarrow1\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 \fBtrough1\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. +If the button is held down, the action auto-repeats. +.IP [3] +Pressing button 1 over the slider and dragging causes the view +to drag with the slider. +If the \fBjump\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 \fBtrough2\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. +If the button is held down, the action auto-repeats. +.IP [5] +Pressing button 1 over \fBarrow2\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 behavior as pressing button 1. +.IP [7] +If button 1 is pressed with the Control key down, then if the +mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes +to the very top (left) of the document; if the mouse is over +\fBarrow2\fR or \fBtrough2\fR the view changes +to the very bottom (right) of the document; if the mouse is +anywhere else then the button press has no effect. +.IP [8] +In vertical scrollbars the Up and Down keys have the same behavior +as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. +In horizontal scrollbars these keys have no effect. +.IP [9] +In vertical scrollbars Control-Up and Control-Down have the same +behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. +In horizontal scrollbars these keys have no effect. +.IP [10] +In horizontal scrollbars the Up and Down keys have the same behavior +as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. +In vertical scrollbars these keys have no effect. +.IP [11] +In horizontal scrollbars Control-Up and Control-Down have the same +behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. +In vertical scrollbars these keys have no effect. +.IP [12] +The Prior and Next keys have the same behavior +as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. +.IP [13] +The Home key adjusts the view to the top (left edge) of the document. +.IP [14] +The End key adjusts the view to the bottom (right edge) of the document. + +.SH KEYWORDS +scrollbar, widget diff --git a/doc/selection.n b/doc/selection.n new file mode 100644 index 0000000..294a243 --- /dev/null +++ b/doc/selection.n @@ -0,0 +1,128 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) selection.n 1.18 96/08/27 13:21:51 +'\" +.so man.macros +.TH selection n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +selection \- Manipulate the X selection +.SH SYNOPSIS +\fBselection \fIoption\fR ?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command provides a Tcl interface to the X selection mechanism and +implements the full selection functionality described in the +X Inter-Client Communication Conventions Manual (ICCCM). +.PP +The first argument to \fBselection\fR determines the format of the +rest of the arguments and the behavior of the command. The following +forms are currently supported: +.PP +.TP +\fBselection clear\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? +If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it +so that no window owns the selection anymore. \fISelection\fR +specifies the X selection that should be cleared, and should be an +atom name such as PRIMARY or CLIPBOARD; see the Inter-Client +Communication Conventions Manual for complete details. +\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to ``.''. +Returns an empty string. +.TP +\fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? +Retrieves the value of \fIselection\fR from \fIwindow\fR's display and +returns it as a result. \fISelection\fR defaults to PRIMARY and +\fIwindow\fR defaults to ``.''. +\fIType\fR specifies the form in which the selection is to be returned +(the desired ``target'' for conversion, in ICCCM terminology), and +should be an atom name such as STRING or FILE_NAME; see the +Inter-Client Communication Conventions Manual for complete details. +\fIType\fR defaults to STRING. The selection owner may choose to +return the selection in any of several different representation +formats, such as STRING, ATOM, INTEGER, etc. (this format is different +than the selection type; see the ICCCM for all the confusing details). +If the selection is returned in a non-string format, such as INTEGER +or ATOM, the \fBselection\fR command converts it to string format as a +collection of fields separated by spaces: atoms are converted to their +textual names, and anything else is converted to hexadecimal integers. +.TP +\fBselection handle\fR ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-format\fR \fIformat\fR? \fIwindow command\fR +Creates a handler for selection requests, such that \fIcommand\fR will +be executed whenever \fIselection\fR is owned by \fIwindow\fR and +someone attempts to retrieve it in the form given by \fItype\fR +(e.g. \fItype\fR is specified in the \fBselection get\fR command). +\fISelection\fR defaults to PRIMARY, \fItype\fR defaults to STRING, and +\fIformat\fR defaults to STRING. If \fIcommand\fR is an empty string +then any existing handler for \fIwindow\fR, \fItype\fR, and +\fIselection\fR is removed. +.RS +.PP +When \fIselection\fR is requested, \fIwindow\fR is the selection owner, +and \fItype\fR is the requested type, \fIcommand\fR will be executed +as a Tcl command with two additional numbers appended to it +(with space separators). +The two additional numbers +are \fIoffset\fR and \fImaxBytes\fR: \fIoffset\fR specifies a starting +character position in the selection and \fImaxBytes\fR gives the maximum +number of bytes to retrieve. The command should return a value consisting +of at most \fImaxBytes\fR of the selection, starting at position +\fIoffset\fR. For very large selections (larger than \fImaxBytes\fR) +the selection will be retrieved using several invocations of \fIcommand\fR +with increasing \fIoffset\fR values. If \fIcommand\fR returns a string +whose length is less than \fImaxBytes\fR, the return value is assumed to +include all of the remainder of the selection; if the length of +\fIcommand\fR's result is equal to \fImaxBytes\fR then +\fIcommand\fR will be invoked again, until it eventually +returns a result shorter than \fImaxBytes\fR. The value of \fImaxBytes\fR +will always be relatively large (thousands of bytes). +.PP +If \fIcommand\fR returns an error then the selection retrieval is rejected +just as if the selection didn't exist at all. +.PP +The \fIformat\fR argument specifies the representation that should be +used to transmit the selection to the requester (the second column of +Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is +STRING, the selection is transmitted as 8-bit ASCII characters (i.e. +just in the form returned by \fIcommand\fR). If \fIformat\fR is +ATOM, then the return value from \fIcommand\fR is divided into fields +separated by white space; each field is converted to its atom value, +and the 32-bit atom value is transmitted instead of the atom name. +For any other \fIformat\fR, the return value from \fIcommand\fR is +divided into fields separated by white space and each field is +converted to a 32-bit integer; an array of integers is transmitted +to the selection requester. +.PP +The \fIformat\fR argument is needed only for compatibility with +selection requesters that don't use Tk. If Tk is being +used to retrieve the selection then the value is converted back to +a string at the requesting end, so \fIformat\fR is +irrelevant. +.RE +.TP +\fBselection own\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? +.TP +\fBselection own\fR ?\fB\-command\fR \fIcommand\fR? ?\fB\-selection\fR \fIselection\fR? \fIwindow\fR +The first form of \fBselection own\fR returns the path name of the +window in this application that owns \fIselection\fR on the display +containing \fIwindow\fR, or an empty string if no window in this +application owns the selection. \fISelection\fR defaults to PRIMARY and +\fIwindow\fR defaults to ``.''. +.PP +The second form of \fBselection own\fR causes \fIwindow\fR to become +the new owner of \fIselection\fR on \fIwindow\fR's display, returning +an empty string as result. The existing owner, if any, is notified +that it has lost the selection. +If \fIcommand\fR is specified, it is a Tcl script to execute when +some other window claims ownership of the selection away from +\fIwindow\fR. \fISelection\fR defaults to PRIMARY. + +.SH KEYWORDS +clear, format, handler, ICCCM, own, selection, target, type diff --git a/doc/send.n b/doc/send.n new file mode 100644 index 0000000..e949c18 --- /dev/null +++ b/doc/send.n @@ -0,0 +1,92 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) send.n 1.18 96/08/27 13:21:47 +'\" +.so man.macros +.TH send n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +send \- Execute a command in a different application +.SH SYNOPSIS +\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the +application named by \fIapp\fR. It returns the result or +error from that command execution. +\fIApp\fR may be the name of any application whose main window is +on the display containing the sender's main window; it need not +be within the same process. +If no \fIarg\fR arguments are present, then the command to be executed is +contained entirely within the \fIcmd\fR argument. If one or +more \fIarg\fRs are present, they are concatenated to form the +command to be executed, just as for the \fBeval\fR command. +.PP +If the initial arguments of the command begin with ``\-'' +they are treated as options. The following options are +currently defined: +.TP +\fB\-async\fR +Requests asynchronous invocation. In this case the \fBsend\fR +command will complete immediately without waiting for \fIcmd\fR +to complete in the target application; no result will be available +and errors in the sent command will be ignored. +If the target application is in the same process as the sending +application then the \fB\-async\fR option is ignored. +.TP +\fB\-displayof\fR \fIpathName\fR +Specifies that the target application's main window is on the display +of the window given by \fIpathName\fR, instead of the display containing +the application's main window. +.TP +\fB\-\|\-\fR +Serves no purpose except to terminate the list of options. This +option is needed only if \fIapp\fR could contain a leading ``\-'' +character. + +.SH "APPLICATION NAMES" +.PP +The name of an application is set initially from the name of the +program or script that created the application. +You can query and change the name of an application with the +\fBtk appname\fR command. + +.SH "DISABLING SENDS" +.PP +If the \fBsend\fR command is removed from an application (e.g. +with the command \fBrename send {}\fR) then the application +will not respond to incoming send requests anymore, nor will it +be able to issue outgoing requests. +Communication can be reenabled by invoking the \fBtk appname\fR +command. + +.SH SECURITY +.PP +The \fBsend\fR command is potentially a serious security loophole, +since any application that can connect to your X server can send +scripts to your applications. +These incoming scripts can use Tcl to read and +write your files and invoke subprocesses under your name. +Host-based access control such as that provided by \fBxhost\fR +is particularly insecure, since it allows anyone with an account +on particular hosts to connect to your server, and if disabled it +allows anyone anywhere to connect to your server. +In order to provide at least a small amount of +security, Tk checks the access control being used by the server +and rejects incoming sends unless (a) \fBxhost\fR-style access control +is enabled (i.e. only certain hosts can establish connections) and (b) the +list of enabled hosts is empty. +This means that applications cannot connect to your server unless +they use some other form of authorization +such as that provide by \fBxauth\fR. + +.SH KEYWORDS +application, name, remote execution, security, send diff --git a/doc/text.n b/doc/text.n new file mode 100644 index 0000000..606249d --- /dev/null +++ b/doc/text.n @@ -0,0 +1,1621 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) text.n 1.68 97/10/31 12:58:41 +'\" +.so man.macros +.TH text n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +text \- Create and manipulate text widgets +.SH SYNOPSIS +\fBtext\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-background \-highlightbackground \-insertontime \-selectborderwidth +\-borderwidth \-highlightcolor \-insertwidth \-selectforeground +\-cursor \-highlightthickness \-padx \-setgrid +\-exportselection \-insertbackground \-pady \-takefocus +\-font \-insertborderwidth \-relief \-xscrollcommand +\-foreground \-insertofftime \-selectbackground \-yscrollcommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-height height Height +Specifies the desired height for the window, in units of characters +in the font given by the \fB\-font\fR option. +Must be at least one. +.OP \-spacing1 spacing1 Spacing1 +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 \fB\-spacing1\fR options in +tags. +.OP \-spacing2 spacing2 Spacing2 +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 \fB\-spacing2\fR options in +tags. +.OP \-spacing3 spacing3 Spacing3 +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 \fB\-spacing3\fR options in +tags. +.OP \-state state State +Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\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. +.OP \-tabs tabs Tabs +Specifies a set of tab stops for the window. The option's value consists +of a list of screen distances giving the positions of the tab stops. Each +position may optionally be followed in the next list element +by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, +or \fBnumeric\fR, which specifies how to justify +text relative to the tab stop. \fBLeft\fR is the default; it causes +the text following the tab character to be positioned with its left edge +at the tab position. \fBRight\fR means that the right edge of the text +following the tab character is positioned at the tab position, and +\fBcenter\fR means that the text is centered at the tab position. +\fBNumeric\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, \fB\-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 \fBtabs\fR option may be overridden by \fB\-tabs\fR +options in tags. +If no \fB\-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. +.OP \-width width Width +Specifies the desired width for the window in units of characters +in the font given by the \fB\-font\fR option. +If the font doesn't have a uniform width then the width of the +character ``0'' is used in translating from character units to +screen units. +.OP \-wrap wrap Wrap +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 \fBnone\fR or \fBchar\fR or \fBword\fR. +A wrap mode of \fBnone\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 \fBchar\fR mode a screen line break may occur after any character; +in \fBword\fR mode a line break will only be made at word boundaries. +.BE + +.SH DESCRIPTION +.PP +The \fBtext\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 +or in the option database +to configure aspects of the text such as its default background color +and relief. The \fBtext\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. +.VS +Text widgets support four different kinds of annotations on the +text, called tags, marks, embedded windows or embedded images. +.VE +Tags allow different portions of the text +to be displayed with different fonts and colors. +In addition, Tcl 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. +.PP +.VS +The fourth form of annotation allows Tk images to be embedded in a text +widget. +See EMBEDDED IMAGES below for more details. +.VE + +.SH INDICES +.PP +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 +.CS +\fIbase modifier modifier modifier ...\fR +.CE +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\fB.\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 \fBend\fR then it refers to the newline character +that ends the line. +.TP 12 +\fB@\fIx\fB,\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 +\fBend\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\fB.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\fB.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. +.TP 12 +.VS +\fIimageName\fR +Indicates the position of the embedded image whose name is +\fIimageName\fR. +This form generates an error if there is no embedded image +by the given name. +.VE +.PP +If the \fIbase\fP could match more than one of the above forms, such +as a \fImark\fP and \fIimageName\fP both having the same value, then +the form earlier in the above list takes precedence. +If modifiers follow the base index, each one of them must have one +of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR +may be abbreviated as long as the abbreviation is unambiguous. +.TP +\fB+ \fIcount\fB 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 +\fB\- \fIcount\fB 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 +\fB+ \fIcount\fB 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 +\fB\- \fIcount\fB 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 +\fBlinestart\fR +Adjust the index to refer to the first character on the line. +.TP +\fBlineend\fR +Adjust the index to refer to the last character on the line (the newline). +.TP +\fBwordstart\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 +\fBwordend\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 ``\fBend \- 1 chars\fR'' +refers to the next-to-last character in the text and +``\fBinsert wordstart \- 1 c\fR'' refers to the character just before +the first one in the word containing the insertion cursor. + +.SH TAGS +.PP +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), \fB+\fR, or \fB\-\fR: +these characters have special meaning in indices, so tags containing +them can't be used as indices. +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 \fBtag raise\fR'' and ``\fIpathName \fBtag 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 +\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the +text widget. +However, display options may be associated with individual tags +using the ``\fIpathName \fBtag 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 +\fB\-background \fIcolor\fR +\fIColor\fR specifies the background color to use for characters +associated with the tag. +It may have any of the forms accepted by \fBTk_GetColor\fR. +.TP +\fB\-bgstipple \fIbitmap\fR +\fIBitmap\fR specifies a bitmap that is used as a stipple pattern +for the background. +It may have any of the forms accepted by \fBTk_GetBitmap\fR. +If \fIbitmap\fR hasn't been specified, or if it is specified +as an empty string, then a solid fill will be used for the +background. +.TP +\fB\-borderwidth \fIpixels\fR +\fIPixels\fR specifies the width of a 3-D border to draw around +the background. +It may have any of the forms accepted by \fBTk_GetPixels\fR. +This option is used in conjunction with the \fB\-relief\fR +option to give a 3-D appearance to the background for characters; +it is ignored unless the \fB\-background\fR option +has been set for the tag. +.TP +\fB\-fgstipple \fIbitmap\fR +\fIBitmap\fR specifies a bitmap that is used as a stipple pattern +when drawing text and other foreground information such as +underlines. +It may have any of the forms accepted by \fBTk_GetBitmap\fR. +If \fIbitmap\fR hasn't been specified, or if it is specified +as an empty string, then a solid fill will be used. +.TP +\fB\-font \fIfontName\fR +\fIFontName\fR is the name of a font to use for drawing characters. +It may have any of the forms accepted by \fBTk_GetFontStruct\fR. +.TP +\fB\-foreground \fIcolor\fR +\fIColor\fR specifies the color to use when drawing text and other +foreground information such as underlines. +It may have any of the forms accepted by \fBTk_GetColor\fR. +.TP +\fB\-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 \fBleft\fR, \fBright\fR, or \fBcenter\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 +\fB\-lmargin1 \fIpixels\fR +If the first character of a text line has a tag for which this +option has been specified, then \fIpixels\fR specifies how +much the line should be indented from the left edge of the +window. +\fIPixels\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 \fB\-lmargin2\fR option controls +the indentation for subsequent lines. +.TP +\fB\-lmargin2 \fIpixels\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 +\fIpixels\fR specifies how much the line should be indented from +the left edge of the window. +\fIPixels\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 +\fB\-offset \fIpixels\fR +\fIPixels\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. +\fIPixels\fR may have any of the standard forms for screen +distances. +.TP +\fB\-overstrike \fIboolean\fR +Specifies whether or not to draw a horizontal rule through +the middle of characters. +\fIBoolean\fR may have any of the forms accepted by \fBTk_GetBoolean\fR. +.TP +\fB\-relief \fIrelief\fR +\fIRelief\fR specifies the 3-D relief to use for drawing backgrounds, +in any of the forms accepted by \fBTk_GetRelief\fR. +This option is used in conjunction with the \fB\-borderwidth\fR +option to give a 3-D appearance to the background for characters; +it is ignored unless the \fB\-background\fR option +has been set for the tag. +.TP +\fB\-rmargin \fIpixels\fR +If the first character of a display line has a tag for which this +option has been specified, then \fIpixels\fR specifies how wide +a margin to leave between the end of the line and the right +edge of the window. +\fIPixels\fR may have any of the standard forms for screen +distances. +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 +\fB\-spacing1 \fIpixels\fR +\fIPixels\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 +\fB\-spacing2 \fIpixels\fR +For lines that wrap, this option specifies how much additional +space to leave between the display lines for a single text line. +\fIPixels\fR may have any of the standard forms for screen +distances. +.TP +\fB\-spacing3 \fIpixels\fR +\fIPixels\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 +\fB\-tabs \fItabList\fR +\fITabList\fR specifies a set of tab stops in the same form +as for the \fB\-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 \fB\-tags\0{\0}\fR, then it requests +default 8-character tabs as described for the \fBtags\fR +widget option. +.TP +\fB\-underline \fIboolean\fR +\fIBoolean\fR specifies whether or not to draw an underline underneath +characters. +It may have any of the forms accepted by \fBTk_GetBoolean\fR. +.TP +\fB\-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 \fB\-wrap\fR option +for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. +If this tag option is specified, it overrides the \fB\-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 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 X +events occur on characters with the given tag, a given +Tcl command will be executed. +Tag bindings can be used to give behaviors to ranges of characters; +among other things, this allows hypertext-like +features to be implemented. +For details, see the description of the \fBtag bind\fR widget +command below. +.PP +The third use for tags is in managing the selection. +See THE SELECTION below. + +.SH MARKS +.PP +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 neighbor 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 \fBmark\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 \fBleft\fR or +\fBright\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 \fBright\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 \fBinsert\fR is associated with the insertion cursor, +as described under THE INSERTION CURSOR below. +Second, the mark \fBcurrent\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: \fBcurrent\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 +.PP +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 (subject to the +usual rules for geometry management, which require the text window +to be the parent of the embedded window or a descendant of its +parent). +The embedded window's position on the screen will be updated as the +text is modified or scrolled, and it will be mapped and unmapped as +it moves into and out of the visible area of the text widget. +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 then +the window is destroyed. +.PP +When an embedded window is added to a text widget with the +\fBwindow create\fR widget command, several configuration +options may be associated with it. +These options may be modified later with the \fBwindow configure\fR +widget command. +The following options are currently supported: +.TP +\fB\-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 \fBtop\fR (align the top of the window +with the top of the line), \fBcenter\fR (center the window +within the range of the line), \fBbottom\fR (align the bottom of the +window with the bottom of the line's area), +or \fBbaseline\fR (align the bottom of the window with the baseline +of the line). +.TP +\fB\-create \fIscript\fR +Specifies a Tcl script that may be evaluated to create the window +for the annotation. +If no \fB\-window\fR option has been specified for the annotation +this script will be evaluated when the annotation is about to +be displayed on the screen. +\fIScript\fR must create a window for the annotation and return +the name of that window as its result. +If the annotation's window should ever be deleted, \fIscript\fR +will be evaluated again the next time the annotation is displayed. +.TP +\fB\-padx \fIpixels\fR +\fIPixels\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 +\fB\-pady \fIpixels\fR +\fIPixels\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 +\fB\-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 \fB\-pady\fR option has been specified as well, then the +requested padding will be retained even if the window is +stretched. +.TP +\fB\-window \fIpathName\fR +Specifies the name of a window to display in the annotation. + +.VS +.SH EMBEDDED IMAGES +.PP +The final form of annotation in text widgets is an embedded image. +Each embedded image annotation causes an image to be displayed +at a particular point in the text. +There may be any number of embedded images in a text widget, +and a particular image may be embedded in multiple places in the same +text widget. +The embedded image's position on the screen will be updated as the +text is modified or scrolled. +Each embedded image occupies one character's worth of index space +in the text widget, and it may be referred to either by +its position in the widget's index space, or the name it is assigned +when the image is inserted into the text widget widh \fBimage create\fP. +If the range of text containing the embedded image is deleted then +that copy of the image is removed from the screen. +.PP +When an embedded image is added to a text widget with the \fBimage +create\fR widget command, a name unique to this instance of the image +is returned. This name may then be used to refer to this image +instance. The name is taken to be the value of the \fB-name\fP option +(described below). If the \fB-name\fP option is not provided, the +\fB-image\fP name is used instead. If the \fIimageName\fP is already +in use in the text widget, then \fB#\fInn\fR is added to the end of the +\fIimageName\fP, where \fInn\fP is an arbitrary integer. This insures +the \fIimageName\fP is unique. +Once this name is assigned to this instance of the image, it does not +change, even though the \fB-image\fP or \fB-name\fP values can be changed +with \fBimage configure\fP. +.PP +When an embedded image is added to a text widget with the +\fBimage create\fR widget command, several configuration +options may be associated with it. +These options may be modified later with the \fBimage configure\fR +widget command. +The following options are currently supported: +.TP +\fB\-align \fIwhere\fR +If the image is not as tall as the line in which it is displayed, +this option determines where the image is displayed in the line. +\fIWhere\fR must have one of the values \fBtop\fR (align the top of the image +with the top of the line), \fBcenter\fR (center the image +within the range of the line), \fBbottom\fR (align the bottom of the +image with the bottom of the line's area), +or \fBbaseline\fR (align the bottom of the image with the baseline +of the line). +.TP +\fB\-image \fIimage\fR +Specifies the name of the Tk image to display in the annotation. +If \fIimage\fP is not a valid Tk image, then an error is returned. +.TP +\fB\-name \fIImageName\fR +Specifies the name by which this image instance may be referenced in +the text widget. If \fIImageName\fP is not supplied, then the +name of the Tk image is used instead. +If the \fIimageName\fP is already in use, \fI#nn\fP is appended to +the end of the name as described above. +.TP +\fB\-padx \fIpixels\fR +\fIPixels\fR specifies the amount of extra space to leave on +each side of the embedded image. +It may have any of the usual forms defined for a screen distance. +.TP +\fB\-pady \fIpixels\fR +\fIPixels\fR specifies the amount of extra space to leave on +the top and on the bottom of the embedded image. +It may have any of the usual forms defined for a screen distance. +.VE + +.SH THE SELECTION +.PP +Selection support is implemented via tags. +If the \fBexportSelection\fR option for the text widget is true +then the \fBsel\fR tag will be associated with the selection: +.IP [1] +Whenever characters are tagged with \fBsel\fR the text widget +will claim ownership of the selection. +.IP [2] +Attempts to retrieve the +selection will be serviced by the text widget, returning all the +characters with the \fBsel\fR tag. +.IP [3] +If the selection is claimed away by another application or by another +window within this application, then the \fBsel\fR tag will be removed +from all characters in the text. +.PP +The \fBsel\fR tag is automatically defined when a text widget is +created, and it may not be deleted with the ``\fIpathName \fBtag delete\fR'' +widget command. Furthermore, the \fBselectBackground\fR, +\fBselectBorderWidth\fR, and \fBselectForeground\fR options for +the text widget are tied to the \fB\-background\fR, +\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR +tag: changes in either will automatically be reflected in the +other. + +.SH THE INSERTION CURSOR +.PP +The mark named \fBinsert\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 \fBmark unset\fR'' widget +command. +The \fBinsert\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" +.PP +The \fBtext\fR command creates a new Tcl 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: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\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 behavior of the command. The following +commands are possible for text widgets: +.TP +\fIpathName \fBbbox \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 \fBcget\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 \fBtext\fR +command. +.TP +\fIpathName \fBcompare\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 \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBtext\fR +command. +.TP +\fIpathName \fBdebug \fR?\fIboolean\fR? +If \fIboolean\fR is specified, then it must have one of the true or +false values accepted by Tcl_GetBoolean. +If the value is a true one then internal consistency checks will be +turned on in the B-tree 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 \fBon\fR +or \fBoff\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 \fBdelete \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 \fBdlineinfo \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 \fBnone\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 \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? +Return the contents of the text widget from \fIindex1\fR up to, +but not including \fIindex2\fR, +including the text and +information about marks, tags, and embedded windows. +If \fIindex2\fR is not specified, then it defaults to +one character past \fIindex1\fR. The information is returned +in the following format: +.LP +.RS +\fIkey1 value1 index1 key2 value2 index2\fR ... +.LP +The possible \fIkey\fP values are \fBtext\fP, \fBmark\fP, +\fBtagon\fP, \fBtagoff\fP, and \fBwindow\fP. The corresponding +\fIvalue\fP is the text, mark name, tag name, or window name. +The \fIindex\fP information is the index of the +start of the text, the mark, the tag transition, or the window. +One or more of the following switches (or abbreviations thereof) +may be specified to control the dump: +.TP +\fB\-all\fR +Return information about all elements: text, marks, tags, and windows. +This is the default. +.TP +\fB\-command \fIcommand\fR +Instead of returning the information as the result of the dump operation, +invoke the \fIcommand\fR on each element of the text widget within the range. +The command has three arguments appended to it before it is evaluated: +the \fIkey\fP, \fIvalue\fP, and \fIindex\fP. +.TP +\fB\-mark\fR +Include information about marks in the dump results. +.TP +\fB\-tag\fR +Include information about tag transitions in the dump results. Tag information is +returned as \fBtagon\fP and \fBtagoff\fP elements that indicate the +begin and end of each range of each tag, respectively. +.TP +\fB\-text\fR +Include information about text in the dump results. The value is the +text up to the next element or the end of range indicated by \fIindex2\fR. +A text element does not span newlines. A multi-line block of text that +contains no marks or tag transitions will still be dumped as a set +of text seqments that each end with a newline. The newline is part +of the value. +.TP +\fB\-window\fR +Include information about embedded windows in the dump results. +The value of a window is its Tk pathname, unless the window +has not been created yet. (It must have a create script.) +In this case an empty string is returned, and you must query the +window by its index position to get more information. +.RE +.TP +\fIpathName \fBget \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 \fBimage \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate embedded images. +The behavior of the command depends on the \fIoption\fR argument +that follows the \fBtag\fR argument. +The following forms of the command are currently supported: +.RS +.TP +\fIpathName \fBimage cget\fR \fIindex option\fR +Returns the value of a configuration option for an embedded image. +\fIIndex\fR identifies the embedded image, and \fIoption\fR +specifies a particular configuration option, which must be one of +the ones listed in the section EMBEDDED IMAGES. +.TP +\fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? +Query or modify the configuration options for an embedded image. +If no \fIoption\fR is specified, returns a list describing all of +the available options for the embedded image at \fIindex\fR +(see \fBTk_ConfigureInfo\fR for information on the format of this list). +If \fIoption\fR is specified with no \fIvalue\fR, then the command +returns a list describing the one named option (this list will be +identical to the corresponding sublist of the value returned if no +\fIoption\fR is specified). +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 +this case the command returns an empty string. +See EMBEDDED IMAGES for information on the options that +are supported. +.TP +\fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? +This command creates a new image 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. +Returns a unique identifier that may be used as an index to refer to +this image. +See EMBEDDED IMAGES for information on the options that +are supported, and a description of the identifier returned. +.TP +\fIpathName \fBimage names\fR +Returns a list whose elements are the names of all image instances currently +embedded in \fIwindow\fR. +.RE +.TP +\fIpathName \fBindex \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 \fBinsert \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 \fBinsert\fR widget +command had been issued for each pair, in order. +The last \fItagList\fR argument may be omitted. +.TP +\fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate marks. The exact behavior of +the command depends on the \fIoption\fR argument that follows +the \fBmark\fR argument. The following forms of the command +are currently supported: +.RS +.TP +\fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR? +If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR +to indicate which of its adjacent characters \fImarkName\fR is attached +to. +If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; +the gravity of \fImarkName\fR is set to the given value. +.TP +\fIpathName \fBmark names\fR +Returns a list whose elements are the names of all the marks that +are currently set. +.TP +\fIpathName \fBmark 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. +These semantics mean that the \fBmark next\fP operation can be used to +step through all the marks in a text widget in the same order +as the mark information returned by the \fBdump\fP operation. +If a mark has been set to the special \fBend\fP index, +then it appears to be \fIafter\fP \fBend\fP with respect to the \fBmark next\fP operation. +An empty string is returned if there are no marks after \fIindex\fR. +.TP +\fIpathName \fBmark 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. +These semantics mean that the \fBmark previous\fP operation can be used to +step through all the marks in a text widget in the reverse order +as the mark information returned by the \fBdump\fP operation. +An empty string is returned if there are no marks before \fIindex\fR. +.TP +\fIpathName \fBmark 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 \fBmark 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 \fBmark names\fR''. +This command returns an empty string. +.RE +.TP +\fIpathName \fBscan\fR \fIoption args\fR +This command is used to implement scanning on texts. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark \fIx y\fR +Records \fIx\fR and \fIy\fR and the current view in the text window, +for use in conjunction with later \fBscan dragto\fR commands. +Typically this command is associated with a mouse button press in +the widget. It returns an empty string. +.TP +\fIpathName \fBscan 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 +\fBscan 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 \fBsearch \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 (or abbreviations thereof) +may be specified to control the search: +.RS +.TP +\fB\-forwards\fR +The search will proceed forward through the text, finding the first +matching range starting at or after the position given by \fIindex\fR. +This is the default. +.TP +\fB\-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 +\fB\-exact\fR +Use exact matching: the characters in the matching range must be +identical to those in \fIpattern\fR. +This is the default. +.TP +\fB\-regexp\fR +Treat \fIpattern\fR as a regular expression and match it against +the text using the rules for regular expressions (see the \fBregexp\fR +command for details). +.TP +\fB\-nocase\fR +Ignore case differences between the pattern and the text. +.TP +\fB\-count\fI varName\fR +The argument following \fB\-count\fR gives the name of a variable; +if a match is found, the number of characters in the matching +range will be stored in the variable. +.TP +\fB\-\|\-\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 \fB\-\fR. +.LP +The matching range must be entirely within a single line of text. +For regular expression matching the newlines are removed from the ends +of the lines before matching: use the \fB$\fR feature in regular +expressions to match the end of a line. +For exact matching the newlines are retained. +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 \fBsee \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 \fBtag \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate tags. The exact behavior of the +command depends on the \fIoption\fR argument that follows the +\fBtag\fR argument. The following forms of the command are currently +supported: +.RS +.TP +\fIpathName \fBtag 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 \fBtag 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 \fBbind\fR command except that +it operates on characters in a text rather than entire widgets. +See the \fBbind\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. +If \fIscript\fR is omitted then the command returns the \fIscript\fR +associated with \fItagName\fR and \fIsequence\fR (an error occurs +if there is no such binding). +If both \fIscript\fR and \fIsequence\fR are omitted then the command +returns a list of all the sequences for which bindings have been +defined for \fItagName\fR. +.RS +.PP +.VS +The only events for which bindings may be specified are those related +to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, +\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. +Event bindings for a text widget use the \fBcurrent\fR mark described +under MARKS above. An \fBEnter\fR event triggers for a tag when the tag +first becomes present on the current character, and a \fBLeave\fR event +triggers for a tag when it ceases to be present on the current character. +\fBEnter\fR and \fBLeave\fR events can happen either because the +\fBcurrent\fR mark moved or because the character at that position +changed. Note that these events are different than \fBEnter\fR and +\fBLeave\fR events for windows. Mouse and keyboard events are directed +to the current character. If a virtual event is used in a binding, that +binding can trigger only if the virtual event is defined by an underlying +mouse-related or keyboard-related event. +.VE +.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 \fBbind\fR command for details). +\fBcontinue\fR and \fBbreak\fR commands within binding scripts +are processed in the same way as for bindings created with +the \fBbind\fR command. +.PP +If bindings are created for the widget as a whole using the +\fBbind\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 \fBtag 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 \fBtag configure\fR +widget command. +.TP +\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \fBconfigure\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 no \fIoption\fR is specified, the command returns a list describing +all of the available options for \fItagName\fR (see \fBTk_ConfigureInfo\fR +for information on the format of this list). +If \fIoption\fR is specified with no \fIvalue\fR, then the command returns +a list describing the one named option (this list will be identical to +the corresponding sublist of the value returned if no \fIoption\fR +is specified). +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; +in this case the command returns an empty string. +See TAGS above for details on the options available for tags. +.TP +\fIpathName \fBtag 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\fB 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 \fBtag 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 \fBtag\fR'' widget +command but haven't been deleted by a ``\fIpathName \fBtag delete\fR'' +widget command, even if no characters are currently marked with +the tag). +The list will be sorted in order from lowest priority to highest +priority. +.TP +\fIpathName \fBtag 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 \fBtag 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\fB 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 \fBtag 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 \fBtag 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 \fBwindow \fIoption \fR?\fIarg arg ...\fR? +This command is used to manipulate embedded windows. +The behavior of the command depends on the \fIoption\fR argument +that follows the \fBtag\fR argument. +The following forms of the command are currently supported: +.RS +.TP +\fIpathName \fBwindow 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 \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? +Query or modify the configuration options for an embedded window. +If no \fIoption\fR is specified, returns a list describing all of +the available options for the embedded window at \fIindex\fR +(see \fBTk_ConfigureInfo\fR for information on the format of this list). +If \fIoption\fR is specified with no \fIvalue\fR, then the command +returns a list describing the one named option (this list will be +identical to the corresponding sublist of the value returned if no +\fIoption\fR is specified). +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 +this case the command returns an empty string. +See EMBEDDED WINDOWS for information on the options that +are supported. +.TP +\fIpathName \fBwindow 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 \fBwindow names\fR +Returns a list whose elements are the names of all windows currently +embedded in \fIwindow\fR. +.RE +.TP +\fIpathName \fBxview \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 \fBxview\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 \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview 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 \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then characters farther to the left +become visible; if it is positive then characters farther to the right +become visible. +.RE +.TP +\fIpathName \fByview \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 \fByview\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 \fB\-yscrollcommand\fR +option. +.TP +\fIpathName \fByview 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 \fByview 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 \fBunits\fR or \fBpages\fR. +If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by +\fInumber\fR lines on the display; if it is \fBpages\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 \fByview \fR?\fB\-pickplace\fR? \fIindex\fR +Changes the view in the widget's window to make \fIindex\fR visible. +If the \fB\-pickplace\fR option isn't specified then \fIindex\fR will +appear at the top of the window. +If \fB\-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 \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget +command (\fBsee\fR handles both x- and y-motion to make a location +visible, whereas \fB\-pickplace\fR only handles motion in y). +.RE +.TP +\fIpathName \fByview \fInumber\fR +This command makes the first character on the line after +the one given by \fInumber\fR visible at the top of the window. +\fINumber\fR must be an integer. +This command used to be used for scrolling, but now it is obsolete. +.RE + +.SH BINDINGS +.PP +Tk automatically creates class bindings for texts that give them +the following default behavior. +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 will stroke out a selection consisting +of whole words. +.IP [3] +Triple-clicking with mouse button 1 selects the line under the mouse +and positions the insertion cursor at the beginning of the line. +Dragging after a triple click will stroke out a selection consisting +of whole lines. +.IP [4] +The ends of the selection can be adjusted by dragging with mouse +button 1 while the Shift key is down; this will adjust the end +of the selection that was nearest to the mouse cursor when button +1 was pressed. +If the button is double-clicked before dragging then the selection +will be adjusted in units of whole words; if it is triple-clicked +then the selection will be adjusted in units of whole lines. +.IP [5] +Clicking mouse button 1 with the Control key down will reposition the +insertion cursor without affecting the selection. +.IP [6] +If any normal printing characters are typed, they are +inserted at the point of the insertion cursor. +.IP [7] +The view in the widget can be adjusted by dragging with mouse button 2. +If mouse button 2 is clicked without moving the mouse, the selection +is copied into the text at the position of the mouse cursor. +The Insert key also inserts the selection, but at the position of +the insertion cursor. +.IP [8] +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 [9] +The Left and Right keys move the insertion cursor one character to the +left or right; they also clear any selection in the text. +If Left or Right is typed with the Shift key down, then the insertion +cursor moves and the selection is extended to include the new character. +Control-Left and Control-Right move the insertion cursor by words, and +Control-Shift-Left and Control-Shift-Right move the insertion cursor +by words and also extend the selection. +Control-b and Control-f behave the same as Left and Right, respectively. +Meta-b and Meta-f behave the same as Control-Left and Control-Right, +respectively. +.IP [10] +The Up and Down keys move the insertion cursor one line up or +down and clear any selection in the text. +If Up or Right is typed with the Shift key down, then the insertion +cursor moves and the selection is extended to include the new character. +Control-Up and Control-Down move the insertion cursor by paragraphs (groups +of lines separated by blank lines), and +Control-Shift-Up and Control-Shift-Down move the insertion cursor +by paragraphs and also extend the selection. +Control-p and Control-n behave the same as Up and Down, respectively. +.IP [11] +The Next and Prior keys move the insertion cursor forward or backwards +by one screenful and clear any selection in the text. +If the Shift key is held down while Next or Prior is typed, then +the selection is extended to include the new character. +Control-v moves the view down one screenful without moving the +insertion cursor or adjusting the selection. +.IP [12] +Control-Next and Control-Prior scroll the view right or left by one page +without moving the insertion cursor or affecting the selection. +.IP [13] +Home and Control-a move the insertion cursor to the +beginning of its line and clear any selection in the widget. +Shift-Home moves the insertion cursor to the beginning of the line +and also extends the selection to that point. +.IP [14] +End and Control-e move the insertion cursor to the +end of the line and clear any selection in the widget. +Shift-End moves the cursor to the end of the line and extends the selection +to that point. +.IP [15] +Control-Home and Meta-< move the insertion cursor to the beginning of +the text and clear any selection in the widget. +Control-Shift-Home moves the insertion cursor to the beginning of the text +and also extends the selection to that point. +.IP [16] +Control-End and Meta-> move the insertion cursor to the end of the +text and clear any selection in the widget. +Control-Shift-End moves the cursor to the end of the text and extends +the selection to that point. +.IP [17] +The Select key and Control-Space set the selection anchor to the position +of the insertion cursor. They don't affect the current selection. +Shift-Select and Control-Shift-Space adjust the selection to the +current position of the insertion cursor, selecting from the anchor +to the insertion cursor if there was not any selection previously. +.IP [18] +Control-/ selects the entire contents of the widget. +.IP [19] +Control-\e clears any selection in the widget. +.IP [20] +The F16 key (labelled Copy on many Sun workstations) or Meta-w +copies the selection in the widget to the clipboard, if there is a selection. +.IP [21] +The F20 key (labelled Cut on many Sun workstations) or Control-w +copies the selection in the widget to the clipboard and deletes +the selection. +If there is no selection in the widget then these keys have no effect. +.IP [22] +The F18 key (labelled Paste on many Sun workstations) or Control-y +inserts the contents of the clipboard at the position of the +insertion cursor. +.IP [23] +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 [24] +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 [25] +Control-d deletes the character to the right of the insertion cursor. +.IP [26] +Meta-d deletes the word to the right of the insertion cursor. +.IP [27] +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 the newline character. +.IP [28] +Control-o opens a new line by inserting a newline character in +front of the insertion cursor without moving the insertion cursor. +.IP [29] +Meta-backspace and Meta-Delete delete the word to the left of the +insertion cursor. +.IP [30] +Control-x deletes whatever is selected in the text widget. +.IP [31] +Control-t reverses the order of the two characters to the right of +the insertion cursor. +.PP +If the widget is disabled using the \fB\-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 behavior of texts can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH "PERFORMANCE ISSUES" +.PP +Text widgets should run efficiently under a variety +of conditions. The text widget uses about 2-3 bytes of +main memory for each byte of text, so texts containing a megabyte +or more should be practical on most workstations. +Text is represented internally with a modified B-tree structure +that makes operations relatively efficient even with large texts. +Tags are included in the B-tree structure in a way that allows +tags to span large ranges or have many disjoint smaller ranges +without loss of efficiency. +Marks are also implemented in a way that allows large numbers of +marks. +In most cases it is fine to have large numbers of unique tags, +or a tag that has many distinct ranges. +.PP +One performance problem can arise if you have hundreds or thousands +of different tags that all have the following characteristics: +the first and last ranges of each tag are near the beginning and +end of the text, respectively, +or a single tag range covers most of the text widget. +The cost of adding and deleting tags like this is proportional +to the number of other tags with the same properties. +In contrast, there is no problem with having thousands of distinct +tags if their overall ranges are localized and spread uniformly throughout +the text. +.PP +Very long text lines can be expensive, +especially if they have many marks and tags within them. +.PP +The display line with the insert cursor is redrawn each time the +cursor blinks, which causes a steady stream of graphics traffic. +Set the \fBinsertOffTime\fP attribute to 0 avoid this. +.SH KEYWORDS +text, widget diff --git a/doc/tk.n b/doc/tk.n new file mode 100644 index 0000000..98a04c3 --- /dev/null +++ b/doc/tk.n @@ -0,0 +1,72 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) tk.n 1.15 97/05/20 20:32:56 +'\" +.so man.macros +.TH tk n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk \- Manipulate Tk internal state +.SH SYNOPSIS +\fBtk\fR \fIoption \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBtk\fR command provides access to miscellaneous +elements of Tk's internal state. +Most of the information manipulated by this command pertains to the +application as a whole, or to a screen or display, rather than to a +particular window. +The command can take any of a number of different forms +depending on the \fIoption\fR argument. The legal forms are: +.TP +\fBtk appname \fR?\fInewName\fR? +If \fInewName\fR isn't specified, this command returns the name +of the application (the name that may be used in \fBsend\fR +commands to communicate with the application). +If \fInewName\fR is specified, then the name of the application +is changed to \fInewName\fR. +If the given name is already in use, then a suffix of the form +``\fB #2\fR'' or ``\fB #3\fR'' is appended in order to make the name unique. +The command's result is the name actually chosen. +\fInewName\fR should not start with a capital letter. +This will interfere with option processing, since names starting with +capitals are assumed to be classes; as a result, Tk may not +be able to find some options for the application. +If sends have been disabled by deleting the \fBsend\fR command, +this command will reenable them and recreate the \fBsend\fR +command. +.VS +.TP +\fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? +. +Sets and queries the current scaling factor used by Tk to convert between +physical units (for example, points, inches, or millimeters) and pixels. The +\fInumber\fR argument is a floating point number that specifies the number of +pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is +omitted, it defaults to the main window. If the \fInumber\fR argument is +omitted, the current value of the scaling factor is returned. +.RS +.PP +A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor +of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard +72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, +which is the setting for a 90 dpi monitor; setting the scaling factor to +1.25 on a 72 dpi monitor would cause everything in the application to be +displayed 1.25 times as large as normal. The initial value for the scaling +factor is set when the application starts, based on properties of the +installed monitor, but it can be changed at any time. Measurements made +after the scaling factor is changed will use the new scaling factor, but it +is undefined whether existing widgets will resize themselves dynamically to +accomodate the new scaling factor. +.RE +.VE +.SH KEYWORDS +application name, send diff --git a/doc/tk4.0.ps b/doc/tk4.0.ps new file mode 100644 index 0000000..d79642d --- /dev/null +++ b/doc/tk4.0.ps @@ -0,0 +1,4602 @@ +%! +%%BoundingBox: (atend) +%%Pages: (atend) +%%DocumentFonts: (atend) +%%EndComments +%%BeginProlog +% +% FrameMaker postscript_prolog 3.0, for use with FrameMaker 3.0 +% This postscript_prolog file is Copyright (c) 1986-1991 Frame Technology +% Corporation. All rights reserved. This postscript_prolog file may be +% freely copied and distributed in conjunction with documents created using +% FrameMaker. +% NOTE +% This file fixes the problem with NeWS printers dithering color output. +% Any questions should be sent to mickey@magickingdom.eng.sun.com +% +% Known Problems: +% Due to bugs in Transcript, the 'PS-Adobe-' is omitted from line 1 +/FMversion (3.0) def +% Set up Color vs. Black-and-White + +/FMPrintInColor { % once-thru loop gimmick + % See if we're a NeWSprint printer + /currentcanvas where { + pop systemdict /separationdict known + exit + } if +% originally had the following, which should always be false: +% /currentcanvas where { +% pop currentcanvas /Color known { +% currentcanvas /Color get +% exit +% } if +% } if + systemdict /colorimage known + systemdict /currentcolortransfer known and +exit } loop def + +% Uncomment the following line to force b&w on color printer +% /FMPrintInColor false def +/FrameDict 195 dict def +systemdict /errordict known not {/errordict 10 dict def + errordict /rangecheck {stop} put} if +% The readline in 23.0 doesn't recognize cr's as nl's on AppleTalk +FrameDict /tmprangecheck errordict /rangecheck get put +errordict /rangecheck {FrameDict /bug true put} put +FrameDict /bug false put +mark +% Some PS machines read past the CR, so keep the following 3 lines together! +currentfile 5 string readline +00 +0000000000 +cleartomark +errordict /rangecheck FrameDict /tmprangecheck get put +FrameDict /bug get { + /readline { + /gstring exch def + /gfile exch def + /gindex 0 def + { + gfile read pop + dup 10 eq {exit} if + dup 13 eq {exit} if + gstring exch gindex exch put + /gindex gindex 1 add def + } loop + pop + gstring 0 gindex getinterval true + } def + } if +/FMVERSION { + FMversion ne { + /Times-Roman findfont 18 scalefont setfont + 100 100 moveto + (FrameMaker version does not match postscript_prolog!) + dup = + show showpage + } if + } def +/FMLOCAL { + FrameDict begin + 0 def + end + } def + /gstring FMLOCAL + /gfile FMLOCAL + /gindex FMLOCAL + /orgxfer FMLOCAL + /orgproc FMLOCAL + /organgle FMLOCAL + /orgfreq FMLOCAL + /yscale FMLOCAL + /xscale FMLOCAL + /manualfeed FMLOCAL + /paperheight FMLOCAL + /paperwidth FMLOCAL +/FMDOCUMENT { + array /FMfonts exch def + /#copies exch def + FrameDict begin + 0 ne dup {setmanualfeed} if + /manualfeed exch def + /paperheight exch def + /paperwidth exch def + /yscale exch def + /xscale exch def + currenttransfer cvlit /orgxfer exch def + currentscreen cvlit /orgproc exch def + /organgle exch def /orgfreq exch def + setpapername + manualfeed {true} {papersize} ifelse + {manualpapersize} {false} ifelse + {desperatepapersize} if + end + } def + /pagesave FMLOCAL + /orgmatrix FMLOCAL + /landscape FMLOCAL +/FMBEGINPAGE { + FrameDict begin + /pagesave save def + 3.86 setmiterlimit + /landscape exch 0 ne def + landscape { + 90 rotate 0 exch neg translate pop + } + {pop pop} + ifelse + xscale yscale scale + /orgmatrix matrix def + gsave + } def +/FMENDPAGE { + grestore + pagesave restore + end + showpage + } def +/FMFONTDEFINE { + FrameDict begin + findfont + ReEncode + 1 index exch + definefont + FMfonts 3 1 roll + put + end + } def +/FMFILLS { + FrameDict begin + array /fillvals exch def + end + } def +/FMFILL { + FrameDict begin + fillvals 3 1 roll put + end + } def +/FMNORMALIZEGRAPHICS { + newpath + 0.0 0.0 moveto + 1 setlinewidth + 0 setlinecap + 0 0 0 sethsbcolor + 0 setgray + } bind def + /fx FMLOCAL + /fy FMLOCAL + /fh FMLOCAL + /fw FMLOCAL + /llx FMLOCAL + /lly FMLOCAL + /urx FMLOCAL + /ury FMLOCAL +/FMBEGINEPSF { + end + /FMEPSF save def + /showpage {} def + FMNORMALIZEGRAPHICS + [/fy /fx /fh /fw /ury /urx /lly /llx] {exch def} forall + fx fy translate + rotate + fw urx llx sub div fh ury lly sub div scale + llx neg lly neg translate + } bind def +/FMENDEPSF { + FMEPSF restore + FrameDict begin + } bind def +FrameDict begin +/setmanualfeed { +%%BeginFeature *ManualFeed True + statusdict /manualfeed true put +%%EndFeature + } def +/max {2 copy lt {exch} if pop} bind def +/min {2 copy gt {exch} if pop} bind def +/inch {72 mul} def +/pagedimen { + paperheight sub abs 16 lt exch + paperwidth sub abs 16 lt and + {/papername exch def} {pop} ifelse + } def + /papersizedict FMLOCAL +/setpapername { + /papersizedict 14 dict def + papersizedict begin + /papername /unknown def + /Letter 8.5 inch 11.0 inch pagedimen + /LetterSmall 7.68 inch 10.16 inch pagedimen + /Tabloid 11.0 inch 17.0 inch pagedimen + /Ledger 17.0 inch 11.0 inch pagedimen + /Legal 8.5 inch 14.0 inch pagedimen + /Statement 5.5 inch 8.5 inch pagedimen + /Executive 7.5 inch 10.0 inch pagedimen + /A3 11.69 inch 16.5 inch pagedimen + /A4 8.26 inch 11.69 inch pagedimen + /A4Small 7.47 inch 10.85 inch pagedimen + /B4 10.125 inch 14.33 inch pagedimen + /B5 7.16 inch 10.125 inch pagedimen + end + } def +/papersize { + papersizedict begin + /Letter {lettertray letter} def + /LetterSmall {lettertray lettersmall} def + /Tabloid {11x17tray 11x17} def + /Ledger {ledgertray ledger} def + /Legal {legaltray legal} def + /Statement {statementtray statement} def + /Executive {executivetray executive} def + /A3 {a3tray a3} def + /A4 {a4tray a4} def + /A4Small {a4tray a4small} def + /B4 {b4tray b4} def + /B5 {b5tray b5} def + /unknown {unknown} def + papersizedict dup papername known {papername} {/unknown} ifelse get + end + /FMdicttop countdictstack 1 add def + statusdict begin stopped end + countdictstack -1 FMdicttop {pop end} for + } def +/manualpapersize { + papersizedict begin + /Letter {letter} def + /LetterSmall {lettersmall} def + /Tabloid {11x17} def + /Ledger {ledger} def + /Legal {legal} def + /Statement {statement} def + /Executive {executive} def + /A3 {a3} def + /A4 {a4} def + /A4Small {a4small} def + /B4 {b4} def + /B5 {b5} def + /unknown {unknown} def + papersizedict dup papername known {papername} {/unknown} ifelse get + end + stopped + } def +/desperatepapersize { + statusdict /setpageparams known + { + paperwidth paperheight 0 1 + statusdict begin + {setpageparams} stopped pop + end + } if + } def +/savematrix { + orgmatrix currentmatrix pop + } bind def +/restorematrix { + orgmatrix setmatrix + } bind def +/dmatrix matrix def +/dpi 72 0 dmatrix defaultmatrix dtransform + dup mul exch dup mul add sqrt def +/freq dpi 18.75 div 8 div round dup 0 eq {pop 1} if 8 mul dpi exch div def +/sangle 1 0 dmatrix defaultmatrix dtransform exch atan def +/DiacriticEncoding [ +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /space /exclam /quotedbl +/numbersign /dollar /percent /ampersand /quotesingle /parenleft +/parenright /asterisk /plus /comma /hyphen /period /slash /zero /one +/two /three /four /five /six /seven /eight /nine /colon /semicolon +/less /equal /greater /question /at /A /B /C /D /E /F /G /H /I /J /K +/L /M /N /O /P /Q /R /S /T /U /V /W /X /Y /Z /bracketleft /backslash +/bracketright /asciicircum /underscore /grave /a /b /c /d /e /f /g /h +/i /j /k /l /m /n /o /p /q /r /s /t /u /v /w /x /y /z /braceleft /bar +/braceright /asciitilde /.notdef /Adieresis /Aring /Ccedilla /Eacute +/Ntilde /Odieresis /Udieresis /aacute /agrave /acircumflex /adieresis +/atilde /aring /ccedilla /eacute /egrave /ecircumflex /edieresis +/iacute /igrave /icircumflex /idieresis /ntilde /oacute /ograve +/ocircumflex /odieresis /otilde /uacute /ugrave /ucircumflex +/udieresis /dagger /.notdef /cent /sterling /section /bullet +/paragraph /germandbls /registered /copyright /trademark /acute +/dieresis /.notdef /AE /Oslash /.notdef /.notdef /.notdef /.notdef +/yen /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/ordfeminine /ordmasculine /.notdef /ae /oslash /questiondown +/exclamdown /logicalnot /.notdef /florin /.notdef /.notdef +/guillemotleft /guillemotright /ellipsis /.notdef /Agrave /Atilde +/Otilde /OE /oe /endash /emdash /quotedblleft /quotedblright +/quoteleft /quoteright /.notdef /.notdef /ydieresis /Ydieresis +/fraction /currency /guilsinglleft /guilsinglright /fi /fl /daggerdbl +/periodcentered /quotesinglbase /quotedblbase /perthousand +/Acircumflex /Ecircumflex /Aacute /Edieresis /Egrave /Iacute +/Icircumflex /Idieresis /Igrave /Oacute /Ocircumflex /.notdef /Ograve +/Uacute /Ucircumflex /Ugrave /dotlessi /circumflex /tilde /macron +/breve /dotaccent /ring /cedilla /hungarumlaut /ogonek /caron +] def +/ReEncode { + dup + length + dict begin + { + 1 index /FID ne + {def} + {pop pop} ifelse + } forall + 0 eq {/Encoding DiacriticEncoding def} if + currentdict + end + } bind def +/graymode true def + /bwidth FMLOCAL + /bpside FMLOCAL + /bstring FMLOCAL + /onbits FMLOCAL + /offbits FMLOCAL + /xindex FMLOCAL + /yindex FMLOCAL + /x FMLOCAL + /y FMLOCAL +/setpattern { + /bwidth exch def + /bpside exch def + /bstring exch def + /onbits 0 def /offbits 0 def + freq sangle landscape {90 add} if + {/y exch def + /x exch def + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + bstring yindex bwidth mul xindex 8 idiv add get + 1 7 xindex 8 mod sub bitshift and 0 ne + {/onbits onbits 1 add def 1} + {/offbits offbits 1 add def 0} + ifelse + } + setscreen + {} settransfer + offbits offbits onbits add div FMsetgray + /graymode false def + } bind def +/grayness { + FMsetgray + graymode not { + /graymode true def + orgxfer cvx settransfer + orgfreq organgle orgproc cvx setscreen + } if + } bind def + /HUE FMLOCAL + /SAT FMLOCAL + /BRIGHT FMLOCAL + /Colors FMLOCAL +FMPrintInColor + + { + /HUE 0 def + /SAT 0 def + /BRIGHT 0 def + % array of arrays Hue and Sat values for the separations [HUE BRIGHT] + /Colors + [[0 0 ] % black + [0 0 ] % white + [0.00 1.0] % red + [0.37 1.0] % green + [0.60 1.0] % blue + [0.50 1.0] % cyan + [0.83 1.0] % magenta + [0.16 1.0] % comment / yellow + ] def + + /BEGINBITMAPCOLOR { + BITMAPCOLOR} def + /BEGINBITMAPCOLORc { + BITMAPCOLORc} def + /BEGINBITMAPTRUECOLOR { + BITMAPTRUECOLOR } def + /BEGINBITMAPTRUECOLORc { + BITMAPTRUECOLORc } def + /K { + Colors exch get dup + 0 get /HUE exch store + 1 get /BRIGHT exch store + HUE 0 eq BRIGHT 0 eq and + {1.0 SAT sub setgray} + {HUE SAT BRIGHT sethsbcolor} + ifelse + } def + /FMsetgray { + /SAT exch 1.0 exch sub store + HUE 0 eq BRIGHT 0 eq and + {1.0 SAT sub setgray} + {HUE SAT BRIGHT sethsbcolor} + ifelse + } bind def + } + + { + /BEGINBITMAPCOLOR { + BITMAPGRAY} def + /BEGINBITMAPCOLORc { + BITMAPGRAYc} def + /BEGINBITMAPTRUECOLOR { + BITMAPTRUEGRAY } def + /BEGINBITMAPTRUECOLORc { + BITMAPTRUEGRAYc } def + /FMsetgray {setgray} bind def + /K { + pop + } def + } +ifelse +/normalize { + transform round exch round exch itransform + } bind def +/dnormalize { + dtransform round exch round exch idtransform + } bind def +/lnormalize { + 0 dtransform exch cvi 2 idiv 2 mul 1 add exch idtransform pop + } bind def +/H { + lnormalize setlinewidth + } bind def +/Z { + setlinecap + } bind def + /fillvals FMLOCAL +/X { + fillvals exch get + dup type /stringtype eq + {8 1 setpattern} + {grayness} + ifelse + } bind def +/V { + gsave eofill grestore + } bind def +/N { + stroke + } bind def +/M {newpath moveto} bind def +/E {lineto} bind def +/D {curveto} bind def +/O {closepath} bind def + /n FMLOCAL +/L { + /n exch def + newpath + normalize + moveto + 2 1 n {pop normalize lineto} for + } bind def +/Y { + L + closepath + } bind def + /x1 FMLOCAL + /x2 FMLOCAL + /y1 FMLOCAL + /y2 FMLOCAL + /rad FMLOCAL +/R { + /y2 exch def + /x2 exch def + /y1 exch def + /x1 exch def + x1 y1 + x2 y1 + x2 y2 + x1 y2 + 4 Y + } bind def +/RR { + /rad exch def + normalize + /y2 exch def + /x2 exch def + normalize + /y1 exch def + /x1 exch def + newpath + x1 y1 rad add moveto + x1 y2 x2 y2 rad arcto + x2 y2 x2 y1 rad arcto + x2 y1 x1 y1 rad arcto + x1 y1 x1 y2 rad arcto + closepath + 16 {pop} repeat + } bind def +/C { + grestore + gsave + R + clip + } bind def + /FMpointsize FMLOCAL +/F { + FMfonts exch get + FMpointsize scalefont + setfont + } bind def +/Q { + /FMpointsize exch def + F + } bind def +/T { + moveto show + } bind def +/RF { + rotate + 0 ne {-1 1 scale} if + } bind def +/TF { + gsave + moveto + RF + show + grestore + } bind def +/P { + moveto + 0 32 3 2 roll widthshow + } bind def +/PF { + gsave + moveto + RF + 0 32 3 2 roll widthshow + grestore + } bind def +/S { + moveto + 0 exch ashow + } bind def +/SF { + gsave + moveto + RF + 0 exch ashow + grestore + } bind def +/B { + moveto + 0 32 4 2 roll 0 exch awidthshow + } bind def +/BF { + gsave + moveto + RF + 0 32 4 2 roll 0 exch awidthshow + grestore + } bind def +/G { + gsave + newpath + normalize translate 0.0 0.0 moveto + dnormalize scale + 0.0 0.0 1.0 5 3 roll arc + closepath fill + grestore + } bind def +/A { + gsave + savematrix + newpath + 2 index 2 div add exch 3 index 2 div sub exch + normalize 2 index 2 div sub exch 3 index 2 div add exch + translate + scale + 0.0 0.0 1.0 5 3 roll arc + restorematrix + stroke + grestore + } bind def + /x FMLOCAL + /y FMLOCAL + /w FMLOCAL + /h FMLOCAL + /xx FMLOCAL + /yy FMLOCAL + /ww FMLOCAL + /hh FMLOCAL + /FMsaveobject FMLOCAL + /FMoptop FMLOCAL + /FMdicttop FMLOCAL +/BEGINPRINTCODE { + /FMdicttop countdictstack 1 add def + /FMoptop count 4 sub def + /FMsaveobject save def + userdict begin + /showpage {} def + FMNORMALIZEGRAPHICS + 3 index neg 3 index neg translate + } bind def +/ENDPRINTCODE { + count -1 FMoptop {pop pop} for + countdictstack -1 FMdicttop {pop end} for + FMsaveobject restore + } bind def +/gn { + 0 + { 46 mul + cf read pop + 32 sub + dup 46 lt {exit} if + 46 sub add + } loop + add + } bind def + /str FMLOCAL +/cfs { + /str sl string def + 0 1 sl 1 sub {str exch val put} for + str def + } bind def +/ic [ + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 + 0 + {0 hx} {1 hx} {2 hx} {3 hx} {4 hx} {5 hx} {6 hx} {7 hx} {8 hx} {9 hx} + {10 hx} {11 hx} {12 hx} {13 hx} {14 hx} {15 hx} {16 hx} {17 hx} {18 hx} + {19 hx} {gn hx} {0} {1} {2} {3} {4} {5} {6} {7} {8} {9} {10} {11} {12} + {13} {14} {15} {16} {17} {18} {19} {gn} {0 wh} {1 wh} {2 wh} {3 wh} + {4 wh} {5 wh} {6 wh} {7 wh} {8 wh} {9 wh} {10 wh} {11 wh} {12 wh} + {13 wh} {14 wh} {gn wh} {0 bl} {1 bl} {2 bl} {3 bl} {4 bl} {5 bl} {6 bl} + {7 bl} {8 bl} {9 bl} {10 bl} {11 bl} {12 bl} {13 bl} {14 bl} {gn bl} + {0 fl} {1 fl} {2 fl} {3 fl} {4 fl} {5 fl} {6 fl} {7 fl} {8 fl} {9 fl} + {10 fl} {11 fl} {12 fl} {13 fl} {14 fl} {gn fl} + ] def + /sl FMLOCAL + /val FMLOCAL + /ws FMLOCAL + /im FMLOCAL + /bs FMLOCAL + /cs FMLOCAL + /len FMLOCAL + /pos FMLOCAL +/ms { + /sl exch def + /val 255 def + /ws cfs + /im cfs + /val 0 def + /bs cfs + /cs cfs + } bind def +400 ms +/ip { + is + 0 + cf cs readline pop + { ic exch get exec + add + } forall + pop + + } bind def +/wh { + /len exch def + /pos exch def + ws 0 len getinterval im pos len getinterval copy pop + pos len + } bind def +/bl { + /len exch def + /pos exch def + bs 0 len getinterval im pos len getinterval copy pop + pos len + } bind def +/s1 1 string def +/fl { + /len exch def + /pos exch def + /val cf s1 readhexstring pop 0 get def + pos 1 pos len add 1 sub {im exch val put} for + pos len + } bind def +/hx { + 3 copy getinterval + cf exch readhexstring pop pop + } bind def + /h FMLOCAL + /w FMLOCAL + /d FMLOCAL + /lb FMLOCAL + /bitmapsave FMLOCAL + /is FMLOCAL + /cf FMLOCAL +/wbytes { + dup + 8 eq {pop} {1 eq {7 add 8 idiv} {3 add 4 idiv} ifelse} ifelse + } bind def +/BEGINBITMAPBWc { + 1 {} COMMONBITMAPc + } bind def +/BEGINBITMAPGRAYc { + 8 {} COMMONBITMAPc + } bind def +/BEGINBITMAP2BITc { + 2 {} COMMONBITMAPc + } bind def +/COMMONBITMAPc { + /r exch def + /d exch def + gsave + translate rotate scale /h exch def /w exch def + /lb w d wbytes def + sl lb lt {lb ms} if + /bitmapsave save def + r + /is im 0 lb getinterval def + ws 0 lb getinterval is copy pop + /cf currentfile def + w h d [w 0 0 h neg 0 h] + {ip} image + bitmapsave restore + grestore + } bind def +/BEGINBITMAPBW { + 1 {} COMMONBITMAP + } bind def +/BEGINBITMAPGRAY { + 8 {} COMMONBITMAP + } bind def +/BEGINBITMAP2BIT { + 2 {} COMMONBITMAP + } bind def +/COMMONBITMAP { + /r exch def + /d exch def + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + r + /is w d wbytes string def + /cf currentfile def + w h d [w 0 0 h neg 0 h] + {cf is readhexstring pop} image + bitmapsave restore + grestore + } bind def + /proc1 FMLOCAL + /proc2 FMLOCAL + /newproc FMLOCAL +/Fmcc { + /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx +} bind def +/ngrayt 256 array def +/nredt 256 array def +/nbluet 256 array def +/ngreent 256 array def + /gryt FMLOCAL + /blut FMLOCAL + /grnt FMLOCAL + /redt FMLOCAL + /indx FMLOCAL + /cynu FMLOCAL + /magu FMLOCAL + /yelu FMLOCAL + /k FMLOCAL + /u FMLOCAL +/colorsetup { + currentcolortransfer + /gryt exch def + /blut exch def + /grnt exch def + /redt exch def + 0 1 255 { + /indx exch def + /cynu 1 red indx get 255 div sub def + /magu 1 green indx get 255 div sub def + /yelu 1 blue indx get 255 div sub def + /k cynu magu min yelu min def + /u k currentundercolorremoval exec def + nredt indx 1 0 cynu u sub max sub redt exec put + ngreent indx 1 0 magu u sub max sub grnt exec put + nbluet indx 1 0 yelu u sub max sub blut exec put + ngrayt indx 1 k currentblackgeneration exec sub gryt exec put + } for + {255 mul cvi nredt exch get} + {255 mul cvi ngreent exch get} + {255 mul cvi nbluet exch get} + {255 mul cvi ngrayt exch get} + setcolortransfer + {pop 0} setundercolorremoval + {} setblackgeneration + } bind def + /tran FMLOCAL +/fakecolorsetup { + /tran 256 string def + 0 1 255 {/indx exch def + tran indx + red indx get 77 mul + green indx get 151 mul + blue indx get 28 mul + add add 256 idiv put} for + currenttransfer + {255 mul cvi tran exch get 255.0 div} + exch Fmcc settransfer +} bind def +/BITMAPCOLOR { + /d 8 def + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + colorsetup + /is w d wbytes string def + /cf currentfile def + w h d [w 0 0 h neg 0 h] + {cf is readhexstring pop} {is} {is} true 3 colorimage + bitmapsave restore + grestore + } bind def +/BITMAPCOLORc { + /d 8 def + gsave + translate rotate scale /h exch def /w exch def + /lb w d wbytes def + sl lb lt {lb ms} if + /bitmapsave save def + colorsetup + /is im 0 lb getinterval def + ws 0 lb getinterval is copy pop + /cf currentfile def + w h d [w 0 0 h neg 0 h] + {ip} {is} {is} true 3 colorimage + bitmapsave restore + grestore + } bind def +/BITMAPTRUECOLORc { + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + + /is w string def + + ws 0 w getinterval is copy pop + /cf currentfile def + w h 8 [w 0 0 h neg 0 h] + {ip} {gip} {bip} true 3 colorimage + bitmapsave restore + grestore + } bind def +/BITMAPTRUECOLOR { + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + /is w string def + /gis w string def + /bis w string def + /cf currentfile def + w h 8 [w 0 0 h neg 0 h] + { cf is readhexstring pop } + { cf gis readhexstring pop } + { cf bis readhexstring pop } + true 3 colorimage + bitmapsave restore + grestore + } bind def +/BITMAPTRUEGRAYc { + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + + /is w string def + + ws 0 w getinterval is copy pop + /cf currentfile def + w h 8 [w 0 0 h neg 0 h] + {ip gip bip w gray} image + bitmapsave restore + grestore + } bind def +/ww FMLOCAL +/r FMLOCAL +/g FMLOCAL +/b FMLOCAL +/i FMLOCAL +/gray { + /ww exch def + /b exch def + /g exch def + /r exch def + 0 1 ww 1 sub { /i exch def r i get .299 mul g i get .587 mul + b i get .114 mul add add r i 3 -1 roll floor cvi put } for + r + } bind def +/BITMAPTRUEGRAY { + gsave + translate rotate scale /h exch def /w exch def + /bitmapsave save def + /is w string def + /gis w string def + /bis w string def + /cf currentfile def + w h 8 [w 0 0 h neg 0 h] + { cf is readhexstring pop + cf gis readhexstring pop + cf bis readhexstring pop w gray} image + bitmapsave restore + grestore + } bind def +/BITMAPGRAY { + 8 {fakecolorsetup} COMMONBITMAP + } bind def +/BITMAPGRAYc { + 8 {fakecolorsetup} COMMONBITMAPc + } bind def +/ENDBITMAP { + } bind def +end + /ALDsave FMLOCAL + /ALDmatrix matrix def ALDmatrix currentmatrix pop +/StartALD { + /ALDsave save def + savematrix + ALDmatrix setmatrix + } bind def +/InALD { + restorematrix + } bind def +/DoneALD { + ALDsave restore + } bind def +%%EndProlog +%%BeginSetup +(3.0) FMVERSION +1 1 612 792 0 1 13 FMDOCUMENT +0 0 /Helvetica-Bold FMFONTDEFINE +1 0 /Times-Bold FMFONTDEFINE +2 0 /Times-Italic FMFONTDEFINE +3 0 /Times-Roman FMFONTDEFINE +4 0 /Helvetica FMFONTDEFINE +5 0 /Courier FMFONTDEFINE +6 0 /Courier-Oblique FMFONTDEFINE +32 FMFILLS +0 0 FMFILL +1 0.1 FMFILL +2 0.3 FMFILL +3 0.5 FMFILL +4 0.7 FMFILL +5 0.9 FMFILL +6 0.97 FMFILL +7 1 FMFILL +8 <0f1e3c78f0e1c387> FMFILL +9 <0f87c3e1f0783c1e> FMFILL +10 <cccccccccccccccc> FMFILL +11 <ffff0000ffff0000> FMFILL +12 <8142241818244281> FMFILL +13 <03060c183060c081> FMFILL +14 <8040201008040201> FMFILL +16 1 FMFILL +17 0.9 FMFILL +18 0.7 FMFILL +19 0.5 FMFILL +20 0.3 FMFILL +21 0.1 FMFILL +22 0.03 FMFILL +23 0 FMFILL +24 <f0e1c3870f1e3c78> FMFILL +25 <f0783c1e0f87c3e1> FMFILL +26 <3333333333333333> FMFILL +27 <0000ffff0000ffff> FMFILL +28 <7ebddbe7e7dbbd7e> FMFILL +29 <fcf9f3e7cf9f3f7e> FMFILL +30 <7fbfdfeff7fbfdfe> FMFILL +%%EndSetup +%%Page: "1" 1 +%%BeginPaperSize: Letter +%%EndPaperSize +612 792 0 FMBEGINPAGE +98.1 675 512.1 675 2 L +7 X +0 K +V +2 H +0 Z +0 X +N +98.1 450 512.1 450 2 L +7 X +V +2 Z +0 X +N +98.1 108 512.1 126 R +7 X +V +0 10 Q +0 X +(1) 506.54 119.33 T +1 24 Q +-0.48 (Tk4.0 Overview and Porting Guide) 152.1 605 S +2 12 Q +(John Ouster) 152.1 563 T +(hout) 210.84 563 T +98.1 135 512.1 423 R +7 X +V +3 10 Q +0 X +(Tk version 4.0 is a major new release with many improvements, new features, and bug) 152.1 416.33 T +(\336xes. This document provides an introduction to the new features and describes the most) 152.1 404.33 T +-0.18 (common problems you are likely to encounter when porting scripts from Tk 3.6, the previ-) 152.1 392.33 P +(ous release. This is) 152.1 380.33 T +2 F +(not) 230.66 380.33 T +3 F +( an introduction to Tk: I assume that you are already familiar with) 243.43 380.33 T +(Tk 3.6 as described in the book) 152.1 368.33 T +2 F +(T) 279.79 368.33 T +(cl and the Tk T) 284.43 368.33 T +(oolkit) 343.48 368.33 T +3 F +(.) 366.24 368.33 T +-0.26 (The good news about Tk 4.0 is that it has many improvements over Tk 3.6. Here are a) 170.1 356.33 P +(few of the most important new features:) 152.1 344.33 T +3 12 Q +(\245) 152.1 329.33 T +3 10 Q +(Tk 4.0 includes a general-purpose mechanism for manipulating color images \050Tk 3.6) 162.9 329.33 T +(supports only monochrome images\051.) 162.9 317.33 T +3 12 Q +(\245) 152.1 302.33 T +3 10 Q +-0.17 (The text widget in Tk 4.0 includes many new features such as tab stops, embedded win-) 162.9 302.33 P +(dows, horizontal scrolling, and many new formatting options.) 162.9 290.33 T +3 12 Q +(\245) 152.1 275.33 T +3 10 Q +(The binding mechanism in Tk 4.0 is much more powerful in Tk 3.6.) 162.9 275.33 T +3 12 Q +(\245) 152.1 260.33 T +3 10 Q +(Motif compliance is much better) 162.9 260.33 T +(. For example, there is now support for keyboard tra-) 292.82 260.33 T +(versal and focus highlights.) 162.9 248.33 T +3 12 Q +(\245) 152.1 233.33 T +3 10 Q +(Many widgets have been improved. For example, buttons and labels can display multi-) 162.9 233.33 T +(line justi\336ed text, and scales can handle real values.) 162.9 221.33 T +(The bad news about Tk 4.0 is that it contains several incompatibilities with Tk 3.6.) 170.1 206.33 T +(Ever since the \336rst release of Tk I have assumed that there would eventually be a major) 152.1 194.33 T +(new release of Tk with substantial incompatibilities. I knew that I wouldn\325) 152.1 182.33 T +(t be able to get) 450.06 182.33 T +(all of the features of Tk right the \336rst time; rather than live forever with all of my early) 152.1 170.33 T +(mistakes, I wanted to have a chance to correct them. Tk 4.0 is that correction. I apologize) 152.1 158.33 T +-0.05 (for the incompatibilities, but I hope they improve Tk enough to justify the dif) 152.1 146.33 P +-0.05 (\336culties you) 460.55 146.33 P +44.1 351 98.1 423 C +35.1 360 197.1 414 R +7 X +0 K +V +1 9 Q +0 X +(FIGURE 1) 35.1 408 T +(T) 35.1 387 T +(ABLE 1) 40.43 387 T +26.1 351 125.1 423 R +7 X +V +40.5 63 571.5 729 C +FMENDPAGE +%%EndPage: "1" 2 +%%Page: "2" 2 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(2) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +(encounter during porting. Tk 4.0 is a one-time correction: we will try very hard to avoid) 152.1 632.33 T +(substantial incompatibilities \050especially in Tk\325) 152.1 620.3 T +(s T) 337 620.3 T +(cl-level interfaces\051 in future releases.) 348.79 620.3 T +-0.4 (Sections 1-1) 170.1 608.3 P +-0.4 (1 cover the major areas of change in Tk 4.0: bindings, focus, text widgets,) 219.02 608.3 P +-0 (Motif compliance, other widget changes, images, color management, event handling, sup-) 152.1 596.26 P +(port for multiple displays, the) 152.1 584.23 T +5 F +(send) 273.14 584.23 T +3 F +( command, and the selection. Section 12 summarizes) 297.13 584.23 T +(several smaller changes. Section 13 lists all of the incompatibilities that af) 152.1 572.19 T +(fect T) 448.4 572.19 T +(cl scripts,) 471.29 572.19 T +-0.02 (along with suggestions for how to deal with them. The explanations here are not intended) 152.1 560.16 P +(to be comprehensive, but rather to introduce you to the issues; for complete information) 152.1 548.12 T +(on new or modi\336ed commands, refer to the reference documentation that comes with the) 152.1 536.09 T +(distribution.) 152.1 524.05 T +98.1 480.7 512.1 483.72 C +152.1 481.92 512.1 481.92 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 482.21 143.1 482.21 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(1) 134.63 487.72 T +(Bindings) 152.1 487.72 T +3 10 Q +-0.35 (The changes for Tk 4.0 that are most likely to af) 152.1 464.03 P +-0.35 (fect existing T) 341.31 464.03 P +-0.35 (cl scripts are those related to) 397.64 464.03 P +(bindings. The new binding mechanism in Tk 4.0 is much more powerful than that of Tk) 152.1 452 T +(3.6, particularly in the way it allows behaviors to be combined, but several incompatible) 152.1 439.96 T +(changes were required to implement the new features. These changes are likely to break) 152.1 427.93 T +(most Tk 3.6 scripts. Fortunately) 152.1 415.89 T +(, it is relatively easy to upgrade your bindings to work) 279.16 415.89 T +(under Tk 4.0.) 152.1 403.86 T +-0.27 (The basic mechanism for bindings is the same as in Tk 3.6. A binding associates a T) 170.1 391.86 P +-0.27 (cl) 502.65 391.86 P +(script with a particular event \050or sequence of events\051 occurring in one or more windows;) 152.1 379.82 T +-0.11 (the script will be invoked automatically whenever the event sequence occurs in any of the) 152.1 367.79 P +-0.13 (speci\336ed windows. The Tk 4.0 binding mechanism has three major feature changes. First,) 152.1 355.75 P +(there is a more general mechanism for specifying the relationship between windows and) 152.1 343.72 T +(bindings, called) 152.1 331.68 T +2 F +(binding tags) 217.89 331.68 T +3 F +(. Second, the con\337ict resolution mechanism \050which is) 267.6 331.68 T +(invoked when more than one binding matches an event\051 has been changed to allow more) 152.1 319.65 T +(than one binding script to execute for a single event. Third, the) 152.1 307.61 T +5 F +(Any) 405.81 307.61 T +3 F +( modi\336er is now) 423.8 307.61 T +(implicit in all binding patterns. These changes are discussed separately in the subsections) 152.1 295.58 T +(that follow) 152.1 283.54 T +(.) 195.04 283.54 T +-0.16 (Overall, the main ef) 170.1 271.54 P +-0.16 (fect of Tk 4.0\325) 249.37 271.54 P +-0.16 (s binding changes is that it allows more bindings to) 306.06 271.54 P +(trigger than Tk 3.6 does. Feedback from the T) 152.1 259.51 T +(cl/Tk community about the Tk 3.6 binding) 335.71 259.51 T +(mechanism indicated that it was too conservative about triggering bindings. This caused) 152.1 247.47 T +(the system to lose behaviors relatively easily and made the binding structure fragile. It) 152.1 235.44 T +-0.35 (appears to be easier to deal with too many binding invocations than too few) 152.1 223.4 P +-0.35 (, so Tk 4.0 tries) 449.17 223.4 P +(to err in this direction.) 152.1 211.37 T +0 F +(1.1) 127.41 181.37 T +(Binding tags) 152.1 181.37 T +3 F +(In Tk 3.6 you specify the window\050s\051 for a binding in one of three ways:) 152.1 165.37 T +3 12 Q +(\245) 152.1 150.37 T +3 10 Q +(Y) 162.9 150.37 T +(ou give the name of a window) 169.12 150.37 T +(, such as) 289.49 150.37 T +5 F +(.a.b.c) 326.13 150.37 T +3 F +(, in which case the binding applies) 362.11 150.37 T +(only to that window) 162.9 138.33 T +(.) 242.49 138.33 T +FMENDPAGE +%%EndPage: "2" 3 +%%Page: "3" 3 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(1 Bindings) 98.1 668.33 T +0 F +(3) 506.54 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 12 Q +0 X +(\245) 152.1 632.33 T +3 10 Q +-0.06 (Y) 162.9 632.33 P +-0.06 (ou give the name of a class, such as) 169.12 632.33 P +5 F +-0.15 (Button) 313.45 632.33 P +3 F +-0.06 (, in which case the binding applies to all) 349.43 632.33 P +(the windows of that class.) 162.9 620.33 T +3 12 Q +(\245) 152.1 605.33 T +3 10 Q +(Y) 162.9 605.33 T +(ou specify) 169.12 605.33 T +5 F +(all) 212.97 605.33 T +3 F +(, in which case the binding applies to all windows.) 230.96 605.33 T +-0.3 (In Tk4.0 you specify the window\050s\051 using a more general mechanism called a) 170.1 590.33 P +2 F +-0.3 (binding) 479.35 590.33 P +(tag) 152.1 578.33 T +3 F +(. A binding tag may be an arbitrary string, but if it starts with a \322.\323 then it must be the) 164.87 578.33 T +(name of a window) 152.1 566.33 T +(. If you specify a class name or) 225.56 566.33 T +5 F +(all) 352.4 566.33 T +3 F +( as a binding tag, it will usually) 370.39 566.33 T +-0.1 (have the same ef) 152.1 554.33 P +-0.1 (fect as in Tk 3.6, but you may also specify other strings that were not per-) 218.51 554.33 P +(mitted in Tk 3.6.) 152.1 542.33 T +-0.07 (Each window in Tk 4.0 has a list of binding tags. When an event occurs in a window) 170.1 530.33 P +-0.07 (,) 507.17 530.33 P +-0.19 (Tk fetches the window\325) 152.1 518.33 P +-0.19 (s binding tags and matches the event against all of the bindings for) 245.62 518.33 P +-0.09 (any of the tags. By default, the binding tags for a window consist of the window name, its) 152.1 506.33 P +-0.14 (class name, the name of its nearest toplevel ancestor) 152.1 494.33 P +-0.14 (, and) 359.61 494.33 P +5 F +-0.33 (all) 381.26 494.33 P +3 F +-0.14 (. For example, a button win-) 399.25 494.33 P +(dow named) 152.1 482.33 T +5 F +(.b) 200.95 482.33 T +3 F +( will have the tags) 212.95 482.33 T +5 9 Q +(.b Button . all) 179.1 468 T +3 10 Q +(by default and all of the following bindings will apply to the window:) 152.1 454.33 T +5 9 Q +(bind .b <Enter> {identify "press here to exit"}) 179.1 440 T +(bind Button <Button-Release-1> {%W invoke}) 179.1 430 T +(bind all <Help> {help %W}) 179.1 420 T +3 10 Q +(So far) 152.1 406.33 T +(, this mechanism produces the same behavior as in Tk 3.6 except that bindings cre-) 175.85 406.33 T +(ated for a toplevel also apply to its descendants \050see Section 1.5 for more on this issue\051.) 152.1 394.33 T +(Y) 170.1 382.33 T +(ou can use the) 176.32 382.33 T +5 F +(bindtags) 235.71 382.33 T +3 F +( command to change the binding tags for a window or) 283.69 382.33 T +(their order) 152.1 370.33 T +(. For example, the command) 193.46 370.33 T +5 9 Q +(bindtags .b {.b MyButton all}) 179.1 356 T +3 10 Q +(will change the binding tags for) 152.1 342.33 T +5 F +(.b) 281.46 342.33 T +3 F +( to the three values in the list. This provides a simple) 293.45 342.33 T +(way to make radical changes the behavior of a window) 152.1 330.33 T +(. After the above command is) 371.55 330.33 T +(invoked none of the) 152.1 318.33 T +5 F +(Button) 234.26 318.33 T +3 F +( class bindings will apply to) 270.24 318.33 T +5 F +(.b) 384.63 318.33 T +3 F +(. Instead, bindings for) 396.63 318.33 T +5 F +-0.81 (MyButton) 152.1 306.33 P +3 F +-0.34 ( will apply; this might give the button a totally dif) 200.07 306.33 P +-0.34 (ferent set of behaviors than a) 395.88 306.33 P +(normal button. In addition, the) 152.1 294.33 T +5 F +(bindtags) 276.75 294.33 T +3 F +( command removes the \322.\323 tag, so bindings on) 324.72 294.33 T +(\322.\323 will not apply to) 152.1 282.33 T +5 F +(.b) 234.27 282.33 T +3 F +(.) 246.27 282.33 T +(Y) 170.1 270.33 T +(ou can also place additional tags on a window with the) 176.32 270.33 T +5 F +(bindtags) 397.55 270.33 T +3 F +( command to) 445.53 270.33 T +(combine a number of behaviors. For example,) 152.1 258.33 T +5 9 Q +(bindtags .b {.b MyButton Button . all}) 179.1 244 T +3 10 Q +(gives) 152.1 230.33 T +5 F +(.b) 175.7 230.33 T +3 F +( the behaviors of) 187.69 230.33 T +5 F +(MyButton) 257.08 230.33 T +3 F +( bindings as well as those speci\336ed by) 305.06 230.33 T +5 F +(Button) 459.96 230.33 T +3 F +(bindings.) 152.1 218.33 T +(Overall, binding tags are similar to the tag mechanisms already used internally by) 170.1 206.33 T +(canvas and text widgets in Tk 3.6, except that binding tags apply to windows instead of) 152.1 194.33 T +(graphical objects or textual characters.) 152.1 182.33 T +FMENDPAGE +%%EndPage: "3" 4 +%%Page: "4" 4 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(4) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +0 F +0 X +(1.2) 127.41 632.33 T +(Con\337ict resolution) 152.1 632.33 T +3 F +(It is possible for several bindings to match a particular event. In Tk 3.6 at most one event) 152.1 616.33 T +(is actually allowed to trigger: a set of con\337ict resolution rules determines the winner) 152.1 604.22 T +(. In) 488.27 604.22 T +(general, a more speci\336c binding takes precedence over a less speci\336c binding. For exam-) 152.1 592.11 T +-0.27 (ple, any binding for a speci\336c widget takes precedence over any class or) 152.1 580 P +5 F +-0.66 (all) 439.96 580 P +3 F +-0.27 ( binding, and) 457.95 580 P +(a binding on) 152.1 567.89 T +5 F +(<Control-a>) 204.57 567.89 T +3 F +( takes precedence over a binding on) 270.54 567.89 T +5 F +(<KeyPress>.) 416.24 567.89 T +3 F +-0.26 (The mechanism for con\337ict resolution is similar in Tk 4.0 except that one binding can) 170.1 555.89 P +-0.35 (trigger for) 152.1 543.78 P +2 F +-0.35 (each) 194.7 543.78 P +3 F +-0.35 ( binding tag on the window where the event occurs. The bindings trigger in) 213.57 543.78 P +(the order of the tags. Thus if button) 152.1 531.67 T +5 F +(.b) 296.17 531.67 T +3 F +( has the default binding tags, one binding for) 308.16 531.67 T +5 F +(.b) 489.71 531.67 T +3 F +(can trigger) 152.1 519.56 T +(, followed by one for) 194.72 519.56 T +5 F +(Button) 281.32 519.56 T +3 F +(, followed by one for \322) 317.3 519.56 T +5 F +(.) 408.34 519.56 T +3 F +(\323, followed by one for) 414.34 519.56 T +5 F +(all) 152.1 507.44 T +3 F +(. If there are no matching bindings for a given tag then none will trigger) 170.09 507.44 T +(, and if there) 456.98 507.44 T +(are several matching bindings for a given tag then a single one is chosen using the same) 152.1 495.33 T +(rules as in Tk 3.6.) 152.1 483.22 T +(The philosophy behind binding tags in Tk 4.0 is that each binding tag corresponds to) 170.1 471.22 T +(an independent behavior) 152.1 459.11 T +(, so bindings with dif) 249.96 459.11 T +(ferent tags should usually be additive. Sup-) 334.46 459.11 T +(pose you de\336ned the following binding:) 152.1 447 T +5 9 Q +(bind .b <Enter> {puts "press here to exit"}) 179.1 432.67 T +3 10 Q +(This binding will add to the behavior de\336ned by the Button class binding for) 152.1 419 T +5 F +(<Enter>) 460.81 419 T +3 F +(.) 502.79 419 T +(In Tk 3.6, the widget-speci\336c binding will replace the class binding, which will break the) 152.1 406.89 T +(behavior of the button so that it no longer has normal button behavior) 152.1 394.78 T +(.) 429.71 394.78 T +(Sometimes there need to be interactions between binding tags. For example, you) 170.1 382.78 T +(might wish to keep most of the default button behavior for) 152.1 370.67 T +5 F +(.b) 388.34 370.67 T +3 F +( but replace the default) 400.33 370.67 T +(behavior for) 152.1 358.56 T +5 F +(<ButtonRelease>) 203.72 358.56 T +3 F +( with some other behavior) 293.67 358.56 T +(. T) 397.49 358.56 T +(o allow bindings to be) 407.9 358.56 T +-0.17 (overridden, Tk 4.0 allows the) 152.1 346.44 P +5 F +-0.41 (break) 271.44 346.44 P +3 F +-0.17 ( command to be invoked from inside a binding. This) 301.43 346.44 P +(causes all remaining binding tags for that binding to be skipped. Consider the following) 152.1 334.33 T +(binding:) 152.1 322.22 T +5 9 Q +(bind .b <ButtonRelease-1> {myRelease .b; break}) 179.1 307.89 T +3 10 Q +-0.21 (This will cause the) 152.1 294.22 P +5 F +-0.5 (myRelease) 228.99 294.22 P +3 F +-0.21 ( procedure to be invoked, then the) 282.96 294.22 P +5 F +-0.5 (break) 420.28 294.22 P +3 F +-0.21 ( command will) 450.26 294.22 P +-0.37 (cause the class binding for the event to be skipped \050assuming that the widget name appears) 152.1 282.11 P +(before its class in the binding tags for) 152.1 270 T +5 F +(.b) 304.78 270 T +3 F +(\051, along with any bindings for other tags.) 316.77 270 T +2 F +(Note:) 119.09 254 T +-0.07 (Y) 152.1 254 P +-0.07 (ou cannot invoke) 156.74 254 P +6 F +-0.17 (break) 227.31 254 P +2 F +-0.07 ( fr) 257.29 254 P +-0.07 (om within the) 266.02 254 P +6 F +-0.17 (myRelease) 322.73 254 P +2 F +-0.07 ( pr) 376.7 254 P +-0.07 (ocedur) 387.64 254 P +-0.07 (e in the above example:) 415.03 254 P +-0.02 (this will generate a T) 152.1 242.89 P +-0.02 (cl err) 236.05 242.89 P +-0.02 (or) 257.59 242.89 P +-0.02 (. However) 265.37 242.89 P +-0.02 (, you can invoke the command \322) 305.31 242.89 P +6 F +-0.05 (return -code) 434.25 242.89 P +(break) 152.1 231.78 T +2 F +(\323 in the pr) 182.08 231.78 T +(ocedur) 223.64 231.78 T +(e to achieve the same effect as the) 251.03 231.78 T +6 F +(break) 389.25 231.78 T +2 F +( in the binding script.) 419.23 231.78 T +0 F +(1.3) 127.41 202.78 T +(Implicit Any) 152.1 202.78 T +3 F +-0.13 (In Tk 3.6 extraneous modi\336ers prevent a binding from matching an event. For example, if) 152.1 186.78 P +(a binding is de\336ned for) 152.1 174.67 T +5 F +(<Button-1>) 247.32 174.67 T +3 F +( and the mouse button is pressed with the) 307.29 174.67 T +5 F +(Num-) 474.68 174.67 T +(Lock) 152.1 162.56 T +3 F +( key down, then the binding will not match. If you want a binding to trigger even) 176.09 162.56 T +(when extraneous modi\336ers are present, you must specify the) 152.1 150.45 T +5 F +(Any) 396.37 150.45 T +3 F +( modi\336er) 414.36 150.45 T +(, as in) 450.33 150.45 T +5 F +(<Any-) 476.42 150.45 T +(Button-1>) 152.1 138.33 T +3 F +(.) 206.07 138.33 T +FMENDPAGE +%%EndPage: "4" 5 +%%Page: "5" 5 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(1 Bindings) 98.1 668.33 T +0 F +(5) 506.54 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +-0.06 (In Tk 4.0, all bindings have the) 170.1 632.33 P +5 F +-0.15 (Any) 297.08 632.33 P +3 F +-0.06 ( modi\336er present implicitly) 315.08 632.33 P +-0.06 (. The) 423.35 632.33 P +5 F +-0.15 (Any) 446.26 632.33 P +3 F +-0.06 ( modi\336er is) 464.25 632.33 P +(still allowed for compatibility) 152.1 620.33 T +(, but it has no meaning. Thus a binding for) 270.55 620.33 T +5 F +(<Button-1>) 443.23 620.33 T +3 F +(will match a button press event even if) 152.1 608.33 T +5 F +(NumLock) 309.21 608.33 T +3 F +(,) 351.19 608.33 T +5 F +(Shift) 356.19 608.33 T +3 F +(,) 386.17 608.33 T +5 F +(Control) 391.17 608.33 T +3 F +(, or any combina-) 433.15 608.33 T +(tion of them. If you wish for a binding not to trigger when a modi\336er is present, you can) 152.1 596.33 T +(just de\336ne an empty binding for that modi\336er combination. For example,) 152.1 584.33 T +5 9 Q +(bind .b <Control-ButtonPress-1> {# this script is a no-op}) 179.1 570 T +3 10 Q +(creates a binding that will trigger on mouse button presses when the) 152.1 556.33 T +5 F +(Control) 426.36 556.33 T +3 F +( key is) 468.34 556.33 T +-0.22 (down. If there is also a) 152.1 544.33 P +5 F +-0.52 (<ButtonPress-1>) 244.35 544.33 P +3 F +-0.22 ( binding for) 334.3 544.33 P +5 F +-0.52 (.b) 383.35 544.33 P +3 F +-0.22 (, it will no longer be invoked) 395.34 544.33 P +-0.02 (if the) 152.1 532.33 P +5 F +-0.05 (Control) 175.37 532.33 P +3 F +-0.02 ( key is down, due to the con\337ict resolution rules. The script for the above) 217.35 532.33 P +(binding is just a T) 152.1 520.33 T +(cl comment, so it has no ef) 223.59 520.33 T +(fect when it is invoked. Alternatively) 330.84 520.33 T +(, you) 478.98 520.33 T +(could use) 152.1 508.33 T +5 F +(%s) 192.63 508.33 T +3 F +( in the binding script to extract the modi\336er state, then test to see that only) 204.62 508.33 T +(desired modi\336ers are present.) 152.1 496.33 T +0 F +(1.4) 127.41 466.33 T +(Porting problems: widget bindings vs. class bindings) 152.1 466.33 T +3 F +-0.38 (Y) 152.1 450.33 P +-0.38 (ou are likely to encounter two problems with bindings when you port Tk 3.6 scripts to Tk) 158.32 450.33 P +-0.18 (4.0: widget bindings vs. class bindings, and events on top-level windows. This section dis-) 152.1 438.33 P +(cusses the \336rst problem and the following section discusses the second problem.) 152.1 426.33 T +(In Tk 3.6, if a widget-speci\336c binding matches an event then no class binding will) 170.1 414.33 T +-0.15 (trigger for the event; in Tk 4.0 both bindings will trigger) 152.1 402.33 P +-0.15 (. Because of this change, you will) 375.75 402.33 P +-0.09 (need to modify most of your widget-speci\336c bindings in one of two ways. If a widget-spe-) 152.1 390.33 P +(ci\336c binding in Tk 3.6 was intended to supplement the class binding, this could only be) 152.1 378.33 T +(done by duplicating the code of the class binding in the widget binding script. This dupli-) 152.1 366.33 T +-0.02 (cated code is no longer necessary in Tk 4.0 and will probably interfere with the new class) 152.1 354.33 P +(bindings in Tk 4.0; you should remove the duplicated class code, leaving only the widget-) 152.1 342.33 T +(speci\336c code in the binding script. If a widget-speci\336c binding in Tk 3.6 was intended to) 152.1 330.33 T +-0.17 (override the class binding, this will no longer occur by default in Tk 4.0; you should add a) 152.1 318.33 P +5 F +-0.54 (break) 152.1 306.33 P +3 F +-0.22 ( command at the end of the binding script to prevent the class binding from trigger-) 182.08 306.33 P +(ing. If a widget binding in Tk 3.6 didn\325) 152.1 294.33 T +(t con\337ict with a class binding, then you will not) 308.49 294.33 T +(need to modify it for Tk 4.0. For example, a widget binding for) 152.1 282.33 T +5 F +(<Help>) 407.49 282.33 T +3 F +( in a text widget) 443.47 282.33 T +(would not need to be modi\336ed, since it doesn\325) 152.1 270.33 T +(t con\337ict with a class binding.) 336.53 270.33 T +0 F +(1.5) 127.41 240.33 T +(Porting problems: events on top-levels) 152.1 240.33 T +3 F +-0.26 (The second binding problem you are likely to encounter in porting Tk 3.6 scripts to Tk 4.0) 152.1 224.33 P +(is that in Tk 4.0 a binding on a toplevel will match events on any of the internal windows) 152.1 212.33 T +(within that top-level. For example, suppose you have a binding created as follows:) 152.1 200.33 T +5 9 Q +(toplevel .t) 179.1 186 T +(button .t.b1 ...) 179.1 176 T +(button .t.b2 ...) 179.1 166 T +(bind .t <Enter> action) 179.1 156 T +FMENDPAGE +%%EndPage: "5" 6 +%%Page: "6" 6 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(6) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +-0.27 (This binding will trigger not only when the mouse enters) 152.1 632.33 P +5 F +-0.64 (.t) 379.29 632.33 P +3 F +-0.27 (, but also when it enters either) 391.28 632.33 P +5 F +(.t.b1) 152.1 620.33 T +3 F +( or) 182.08 620.33 T +5 F +(.t.b2) 195.41 620.33 T +3 F +(. This is because the binding tags for a window include its nearest) 225.39 620.33 T +(ancestor toplevel by default. The toplevel is present in the binding tags to make it easy to) 152.1 608.33 T +(set up accelerator keys that apply in all the windows of a panel. For example,) 152.1 596.33 T +5 9 Q +(bind .t <Control-a> {controlAProc %W}) 179.1 582 T +3 10 Q +(will cause) 152.1 568.33 T +5 F +(controlAProc) 194.85 568.33 T +3 F +( to be invoked whenever) 266.81 568.33 T +5 F +(Control-a) 367.56 568.33 T +3 F +( is typed in any of the) 421.53 568.33 T +-0.12 (windows in) 152.1 556.33 P +5 F +-0.29 (.t) 200.72 556.33 P +3 F +-0.12 (. The procedure will receive the name of the focus window as its ar) 212.71 556.33 P +-0.12 (gument.) 479.62 556.33 P +(Unfortunately) 170.1 544.33 T +(, if you have created bindings on toplevel windows in your Tk 3.6) 225.52 544.33 T +-0.16 (scripts, they probably expect to trigger only for events in the toplevel, so the bindings will) 152.1 532.33 P +(misbehave under Tk 4.0. Fortunately you can reproduce the behavior of Tk 3.6 by using) 152.1 520.33 T +(the) 152.1 508.33 T +5 F +(%W) 166.81 508.33 T +3 F +( substitution in the binding script. For example, to ensure that) 178.8 508.33 T +5 F +(action) 427.28 508.33 T +3 F +( is invoked) 463.26 508.33 T +(only for) 152.1 496.33 T +5 F +(Enter) 186.52 496.33 T +3 F +( events in a toplevel window itself, create the following binding in place) 216.51 496.33 T +(of the one above:) 152.1 484.33 T +5 9 Q +(bind .t <Enter> {) 179.1 470 T +(if {"%W" == ".t"} {) 200.63 460 T +(action) 222.23 450 T +(}) 200.63 440 T +(}) 179.1 430 T +3 10 Q +-0.01 (When an) 152.1 416.33 P +5 F +-0.03 (Enter) 190.38 416.33 P +3 F +-0.01 ( event occurs in a descendant of) 220.36 416.33 P +5 F +-0.03 (.t) 350.45 416.33 P +3 F +-0.01 ( such as) 362.45 416.33 P +5 F +-0.03 (.t.x) 396.56 416.33 P +3 F +-0.01 (, a binding for) 420.54 416.33 P +5 F +-0.03 (Enter) 479.63 416.33 P +3 F +(in) 152.1 404.33 T +5 F +(.t.x) 162.37 404.33 T +3 F +( will trigger \336rst, if there is one. Then the above binding will trigger) 186.36 404.33 T +(. Since) 457.58 404.33 T +5 F +(%W) 487.29 404.33 T +3 F +(will be substituted with) 152.1 392.33 T +5 F +(.t.x) 248.17 392.33 T +3 F +(, the) 272.15 392.33 T +5 F +(if) 291.86 392.33 T +3 F +( condition will not be satis\336ed and the binding will) 303.86 392.33 T +(not do anything.) 152.1 380.33 T +-0.14 ( An alternative solution is to remove the toplevel window from the binding tags of all) 170.1 368.33 P +-0.12 (its internal windows. However) 152.1 356.33 P +-0.12 (, this means that you won\325) 274.03 356.33 P +-0.12 (t be able to take advantage of the) 378.73 356.33 P +(tag to create key bindings that apply everywhere within the toplevel.) 152.1 344.33 T +0 F +(1.6) 127.41 314.33 T +(Internal bindings in canvases and texts) 152.1 314.33 T +3 F +(The same changes in con\337ict resolution described in Section 1.2 also apply to bindings) 152.1 298.33 T +-0.05 (created internally for the items of a canvas or the tags of a text widget. If a canvas item or) 152.1 286.33 P +-0.29 (character of text has multiple tags, then one binding can trigger for each tag on each event.) 152.1 274.33 P +-0.32 (The bindings trigger in the priority order of the tags. Similar porting problems are likely to) 152.1 262.33 P +-0.19 (occur as described in Section 1.4; if a binding for one tag needs to override that of another) 152.1 250.33 P +(tag, you\325ll need to add a) 152.1 238.33 T +5 F +(break) 251.2 238.33 T +3 F +( command under Tk 4.0; if a binding for one tag dupli-) 281.18 238.33 T +-0.28 (cated the code from another tag\325) 152.1 226.33 P +-0.28 (s binding, so that they will compose in Tk 3.6, you\325ll have) 279.76 226.33 P +(to remove the duplicated code in Tk 4.0.) 152.1 214.33 T +FMENDPAGE +%%EndPage: "6" 7 +%%Page: "7" 7 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(2 Focus management) 98.1 668.33 T +0 F +(7) 506.54 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +98.1 623.98 512.1 627 C +152.1 625.2 512.1 625.2 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 625.49 143.1 625.49 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(2) 134.63 631 T +(Focus management) 152.1 631 T +3 10 Q +(The input focus is another area where Tk 4.0 contains major changes. Fortunately) 152.1 607.31 T +(, the) 477.87 607.31 T +-0.09 (focus changes should not require as many modi\336cations to your Tk 3.6 scripts as the bind-) 152.1 595.31 P +(ing changes.) 152.1 583.31 T +0 F +(2.1) 127.41 553.31 T +(One focus window per toplevel) 152.1 553.31 T +3 F +(Tk 3.6 only keeps track of a single focus window for each application, and this results in) 152.1 537.31 T +(two problems. First, it doesn\325) 152.1 525.31 T +(t allow an application to use multiple displays since this) 269.64 525.31 T +-0.16 (could result in multiple simultaneous focus windows, one on each display) 152.1 513.31 P +-0.16 (. Second, the Tk) 444.99 513.31 P +(3.6 model doesn\325) 152.1 501.31 T +(t work very well for applications that have multiple toplevels: when the) 221.04 501.31 T +(mouse moves from one toplevel to another) 152.1 489.31 T +(, the focus window should switch to whatever) 322.7 489.31 T +-0.24 (window had the focus the last time the mouse was in the new toplevel, but Tk 3.6 does not) 152.1 477.31 P +(remember this information.) 152.1 465.31 T +(Tk 4.0 corrects both of these problems. It remembers one focus window for each) 170.1 453.31 T +(toplevel, which can be queried with the) 152.1 441.31 T +5 F +(focus -lastfor) 311.98 441.31 T +3 F +( command. When the win-) 395.94 441.31 T +(dow manager gives the focus to a toplevel window \050because the mouse entered the win-) 152.1 429.31 T +(dow or because you clicked on the window) 152.1 417.31 T +(, depending on the focus model being used by) 324.38 417.31 T +(the window manager\051, Tk passes the focus on to the remembered window) 152.1 405.31 T +(. Several win-) 446.23 405.31 T +(dows in an application can have the focus at the same time, one on each display the appli-) 152.1 393.31 T +(cation is using. When asking for the current focus window in the) 152.1 381.31 T +5 F +(focus) 413.31 381.31 T +3 F +( command, you) 443.29 381.31 T +(can use the) 152.1 369.31 T +5 F +(-displayof) 199 369.31 T +3 F +( switch to specify a particular display) 258.97 369.31 T +(.) 407.66 369.31 T +(When you set the focus to a window with the) 170.1 357.31 T +5 F +(focus) 353.31 357.31 T +3 F +( command, Tk remembers that) 383.29 357.31 T +(window as the most recent focus window for its toplevel. In addition, if the application) 152.1 345.31 T +(currently has the focus for the window\325) 152.1 333.31 T +(s display) 309.2 333.31 T +(, Tk moves the focus to the speci\336ed win-) 343.82 333.31 T +-0.35 (dow; this can be used, for example to move the focus to a dialog when the dialog is posted,) 152.1 321.31 P +(or to perform keyboard traversal among the toplevels of an application. If the application) 152.1 309.31 T +(doesn\325) 152.1 297.31 T +(t currently have the focus for the display) 178.57 297.31 T +(, then Tk will not normally take the focus) 339.74 297.31 T +(from its current owner) 152.1 285.31 T +(. However) 241.2 285.31 T +(, you can specify the) 282.43 285.31 T +5 F +(-force) 367.36 285.31 T +3 F +( ar) 403.34 285.31 T +(gument to) 413.43 285.31 T +5 F +(focus) 456.18 285.31 T +3 F +( to) 486.17 285.31 T +(insist that Tk grab the focus for this application \050in general this is probably not a good) 152.1 273.31 T +(idea, since it may clash with the window manager) 152.1 261.31 T +(\325) 352.05 261.31 T +(s focus policy\051.) 354.83 261.31 T +0 F +(2.2) 127.41 231.31 T +(Keyboard traversal) 152.1 231.31 T +3 F +-0.38 (Tk 4.0 has a much more complete implementation of keyboard traversal than Tk 3.6. In Tk) 152.1 215.31 P +(3.6 there is built-in support only for keyboard traversal of menus. In Tk 4.0 keyboard tra-) 152.1 203.31 T +(versal is implemented for all widgets. Y) 152.1 191.31 T +(ou can type) 311.27 191.31 T +5 F +(Tab) 359.85 191.31 T +3 F +( to move the focus among the) 377.84 191.31 T +-0.4 (windows within a toplevel and) 152.1 179.31 P +5 F +-0.95 (Shift+Tab) 275.31 179.31 P +3 F +-0.4 ( to move in the reverse direction. The order of) 329.28 179.31 P +-0.11 (traversal is de\336ned by the stacking order of widgets, with the lowest widget \336rst in the tra-) 152.1 167.31 P +(versal order) 152.1 155.31 T +(. All Tk widgets now provide a) 199 155.31 T +5 F +(-takefocus) 326.14 155.31 T +3 F +( option, which determines) 386.11 155.31 T +FMENDPAGE +%%EndPage: "7" 8 +%%Page: "8" 8 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(8) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +(whether the window should accept the focus during traversal or be skipped. This option) 152.1 632.33 T +(has several features; see the) 152.1 620.33 T +5 F +(options.n) 265.61 620.33 T +3 F +( manual entry for details.) 319.58 620.33 T +(All of the Tk widgets provide a traversal highlight ring as required by Motif. The) 170.1 608.33 T +(highlight ring turns dark when the widget has the input focus. Its size and colors are con-) 152.1 596.33 T +(trolled by the) 152.1 584.33 T +5 F +(-highlightthickness) 207.9 584.33 T +3 F +(,) 321.84 584.33 T +5 F +(-highlightbackground) 326.83 584.33 T +3 F +(, and) 446.77 584.33 T +5 F +(-) 152.1 572.33 T +(highlightcolor) 158.1 572.33 T +3 F +( options. Y) 242.05 572.33 T +(ou may notice that widgets appear to have extra space) 285.2 572.33 T +(around them in Tk 4.0; this is due to the traversal highlight ring, which is normally the) 152.1 560.33 T +(same color as the background for widgets.) 152.1 548.33 T +0 F +(2.3) 127.41 518.33 T +(Support for focus-follows-mouse) 152.1 518.33 T +3 F +(Both Tk 3.6 and Tk 4.0 use an) 152.1 502.33 T +2 F +(explicit focus model) 275.91 502.33 T +3 F +( within a toplevel. This means that) 355.86 502.33 T +(moving the mouse among the windows of a toplevel does not normally move the focus;) 152.1 490.33 T +-0.06 (you have to click or perform some other action \050such as pressing) 152.1 478.33 P +5 F +-0.15 (Tab) 412.26 478.33 P +3 F +-0.06 (\051 to move the focus.) 430.25 478.33 P +(Tk 3.6 has no support for an) 152.1 466.33 T +2 F +(implicit focus model) 267.58 466.33 T +3 F +( where the window under the mouse) 348.64 466.33 T +(always has the focus. In Tk 4.0 you can invoke the library procedure) 152.1 454.33 T +5 F +(tk_focusFol-) 428.83 454.33 T +(lowsMouse) 152.1 442.33 T +3 F +( to switch to an implicit focus model; in this mode whenever the mouse) 206.07 442.33 T +(enters a new window the focus will switch to that window) 152.1 430.33 T +(.) 384.07 430.33 T +0 F +(2.4) 127.41 400.33 T +(No default focus window) 152.1 400.33 T +(, no \322none\323 focus.) 269.45 400.33 T +3 F +-0.16 (Tk 3.6 has the notion of a default focus window) 152.1 384.33 P +-0.16 (, which receives the focus if the focus win-) 341.56 384.33 P +(dow is deleted. It is also possible for an application to abandon the input focus by setting) 152.1 372.33 T +(the focus to) 152.1 360.33 T +5 F +(none) 201.23 360.33 T +3 F +(. In Tk 4.0 both of these features have been eliminated. There is no) 225.22 360.33 T +(default focus window) 152.1 348.33 T +(, and the focus can never be explicitly abandoned. If the focus win-) 238.05 348.33 T +(dow is destroyed, Tk resets the input focus to the toplevel containing the old focus win-) 152.1 336.33 T +(dow) 152.1 324.33 T +(. If the toplevel is destroyed, the window manager will reclaim the focus and move it) 168.66 324.33 T +(elsewhere.) 152.1 312.33 T +-0.18 (If you really want to abandon the focus in Tk 4.0 so that keyboard events are ignored,) 170.1 300.33 P +(you can create a dummy window with no key bindings \050set its binding tags to an empty) 152.1 288.33 T +(string to be sure\051, make sure that is never mapped, and give it the input focus.) 152.1 276.33 T +0 F +(2.5) 127.41 246.33 T +(Better focus events) 152.1 246.33 T +3 F +-0.13 (Tk 3.6 has a quirky event model for) 152.1 230.33 P +5 F +-0.32 (FocusIn) 296.77 230.33 P +3 F +-0.13 ( and) 338.75 230.33 P +5 F +-0.32 (FocusOut) 357.92 230.33 P +3 F +-0.13 ( events: when the window) 405.89 230.33 P +-0.23 (manager gives the focus to a toplevel, Tk generates a) 152.1 218.33 P +5 F +-0.55 (FocusIn) 364.36 218.33 P +3 F +-0.23 ( event for the toplevel and) 406.33 218.33 P +(another) 152.1 206.33 T +5 F +(FocusIn) 184.57 206.33 T +3 F +( event for the focus window) 226.55 206.33 T +(, but no events for any other windows.) 337.76 206.33 T +(When the window manager moves the focus somewhere else,) 152.1 194.33 T +5 F +(FocusOut) 400.79 194.33 T +3 F +( events are gen-) 448.77 194.33 T +-0 (erated for these same two windows. In Tk 4.0,) 152.1 182.33 P +5 F +-0 (FocusIn) 339.73 182.33 P +3 F +-0 ( and) 381.71 182.33 P +5 F +-0 (FocusOut) 401.13 182.33 P +3 F +-0 ( events are gen-) 449.11 182.33 P +-0.26 (erated in the same way as) 152.1 170.33 P +5 F +-0.63 (Enter) 255.43 170.33 P +3 F +-0.26 ( and) 285.41 170.33 P +5 F +-0.63 (Leave) 304.31 170.33 P +3 F +-0.26 ( events: when the focus arrives, a) 334.29 170.33 P +5 F +-0.63 (FocusIn) 467.89 170.33 P +3 F +-0.05 (event is generated for each window from the toplevel down to the focus window) 152.1 158.33 P +-0.05 (, with dif-) 472.5 158.33 P +FMENDPAGE +%%EndPage: "8" 9 +%%Page: "9" 9 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(3 T) 98.1 668.33 T +(ext widgets) 111.43 668.33 T +0 F +(9) 506.54 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +-0.33 (ferent detail \336elds for dif) 152.1 632.33 P +-0.33 (ferent windows \050see Xlib documentation for information on these) 250.53 632.33 P +(values\051. The reverse happens when the focus leaves a window) 152.1 620.33 T +(.) 399.57 620.33 T +0 F +(2.6) 127.41 590.33 T +(Porting issues) 152.1 590.33 T +3 F +(If you didn\325) 152.1 574.33 T +(t have any special focus-related code in Tk 3.6, then you shouldn\325) 199.66 574.33 T +(t need to) 462.9 574.33 T +(make any changes for 4.0; things will just work better) 152.1 562.33 T +(. If you wrote code in Tk 3.6 to get) 366.96 562.33 T +(around the weaknesses with its focus mechanism, then you should remove most or all of) 152.1 550.33 T +(that code. For example, if you implemented keyboard traversal yourself, or if you built) 152.1 538.33 T +(your own mechanism to remember a separate focus window for each toplevel and give it) 152.1 526.33 T +(the input focus whenever the toplevel gets the focus, you can simply remove this code,) 152.1 514.33 T +-0.33 (since Tk 4.0 performs these functions for you. If you wrote code that depends on the weird) 152.1 502.33 P +-0.03 (event model in Tk 3.6, that code will need to be rewritten for Tk 4.0. The Tk 4.0 model is) 152.1 490.33 P +(general enough to duplicate any ef) 152.1 478.33 T +(fects that were possible in Tk 3.6.) 289.86 478.33 T +98.1 434.98 512.1 438 C +152.1 436.2 512.1 436.2 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 436.49 143.1 436.49 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(3) 134.63 442 T +(T) 152.1 442 T +(ext widgets) 158.54 442 T +3 10 Q +(T) 152.1 418.31 T +(ext widgets have under) 157.51 418.31 T +(gone a major overhaul for Tk 4.0 and they have improved in) 249.76 418.31 T +(many ways. The changes to text widgets are almost entirely upward-compatible from Tk) 152.1 406.31 T +(3.6.) 152.1 394.31 T +0 F +(3.1) 127.41 364.31 T +(Embedded windows.) 152.1 364.31 T +3 F +(Tk 3.6 supported two kinds of annotations in texts: marks and tags. In Tk 4.0 a third kind) 152.1 348.31 T +-0.04 (of annotation is available: an embedded window) 152.1 336.31 P +-0.04 (. This allows you to embed other widgets) 344.99 336.31 P +(inside a text widget, mixed in with the text. The text widget acts as a geometry manager) 152.1 324.31 T +(for these windows, laying them out and wrapping them just as if each embedded window) 152.1 312.31 T +(were a single character in the text. Y) 152.1 300.31 T +(ou can even have texts with nothing in them but) 297.64 300.31 T +(embedded windows. The) 152.1 288.31 T +5 F +(window) 254.8 288.31 T +3 F +( widget command for text widgets provides several) 290.78 288.31 T +(options to manage embedded windows.) 152.1 276.31 T +0 F +(3.2) 127.41 246.31 T +(More options for tags.) 152.1 246.31 T +3 F +(In Tk 4.0 tags support many new options providing additional control over how informa-) 152.1 230.31 T +(tion is displayed. Here is a summary of the new options:) 152.1 218.31 T +3 12 Q +(\245) 152.1 203.31 T +3 10 Q +(Y) 162.9 203.31 T +(ou can now specify tab stops with the) 169.12 203.31 T +5 F +(-tabs) 321.79 203.31 T +3 F +( option. Each tab stop can use left, cen-) 351.78 203.31 T +(ter) 162.9 191.31 T +(, right, or numeric justi\336cation. T) 173.04 191.31 T +(ab stops can also be speci\336ed for the widget as a) 305.6 191.31 T +(whole.) 162.9 179.31 T +3 12 Q +(\245) 152.1 164.31 T +3 10 Q +(Y) 162.9 164.31 T +(ou can specify justi\336cation \050left, center or right\051 with the) 169.12 164.31 T +5 F +(-justify) 398.12 164.31 T +3 F +( option.) 446.09 164.31 T +FMENDPAGE +%%EndPage: "9" 10 +%%Page: "10" 10 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(10) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 12 Q +0 X +(\245) 152.1 632.33 T +3 10 Q +(Y) 162.9 632.33 T +(ou can now specify line spacing with three options,) 169.12 632.33 T +5 F +(-spacing1) 376.75 632.33 T +3 F +(,) 430.72 632.33 T +5 F +(-spacing2) 435.72 632.33 T +3 F +(, and) 489.69 632.33 T +5 F +(-) 162.9 620.2 T +(spacing3) 168.9 620.2 T +3 F +(, which control the spacing above a line, between wrapped lines, and) 216.87 620.2 T +(below a line.) 162.9 608.06 T +3 12 Q +(\245) 152.1 593.06 T +3 10 Q +(Y) 162.9 593.06 T +(ou can now specify mar) 169.12 593.06 T +(gins with the) 264.41 593.06 T +5 F +(-lmargin1) 318.55 593.06 T +3 F +(,) 372.52 593.06 T +5 F +(-lmargin2) 377.52 593.06 T +3 F +(, and) 431.49 593.06 T +5 F +(-rmargin) 453.42 593.06 T +3 F +(options.) 162.9 580.92 T +3 12 Q +(\245) 152.1 565.92 T +3 10 Q +-0.25 (Y) 162.9 565.92 P +-0.25 (ou can now adjust the vertical position of text \050e.g. for superscripts or subscripts\051 with) 169.12 565.92 P +(the) 162.9 553.79 T +5 F +(-offset) 177.61 553.79 T +3 F +( option.) 219.59 553.79 T +3 12 Q +(\245) 152.1 538.79 T +3 10 Q +-0.03 (Y) 162.9 538.79 P +-0.03 (ou can now specify the wrapping style \050word wrapping, character wrapping, or none\051) 169.12 538.79 P +(with the) 162.9 526.65 T +5 F +(-wrap) 197.88 526.65 T +3 F +( option.) 227.86 526.65 T +3 12 Q +(\245) 152.1 511.65 T +3 10 Q +(Y) 162.9 511.65 T +(ou can now request overstriking with the) 169.12 511.65 T +5 F +(-overstrike) 334.83 511.65 T +3 F +( option.) 400.8 511.65 T +0 F +(3.3) 127.41 481.65 T +(Bindings) 152.1 481.65 T +3 F +-0.19 (The default bindings for text widgets have been completely rewritten in Tk 4.0. They now) 152.1 465.65 P +(support almost all of the Motif behavior \050everything except add mode and secondary) 152.1 453.52 T +-0.36 (selections\051. They also include a substantial subset of the Emacs bindings for cursor motion) 152.1 441.38 P +(and basic editing. The) 152.1 429.24 T +5 F +(tk_strictMotif) 242.87 429.24 T +3 F +( variable disables the Emacs bindings.) 326.82 429.24 T +0 F +(3.4) 127.41 399.24 T +(Miscellaneous new features) 152.1 399.24 T +3 F +(In addition to the major changes described above, text widgets also include the following) 152.1 383.24 T +(new features:) 152.1 371.11 T +1 F +(Horizontal scr) 162.9 356.11 T +(olling) 224.07 356.11 T +3 F +(. T) 247.95 356.11 T +(ext widgets can now be scrolled horizontally as well as verti-) 258.36 356.11 T +(cally) 162.9 343.97 T +(, using the) 181.68 343.97 T +5 F +(-) 225.55 343.97 T +(xscrollcommand) 231.54 343.97 T +3 F +( option and the) 315.5 343.97 T +5 F +(xview) 377.68 343.97 T +3 F +( widget command.) 407.67 343.97 T +1 F +(Sear) 162.9 328.97 T +(ching) 182.15 328.97 T +3 F +(. T) 205.48 328.97 T +(ext widgets have a new) 215.88 328.97 T +5 F +(search) 311.64 328.97 T +3 F +( widget command, which provides ef) 347.62 328.97 T +(\336-) 495.67 328.97 T +-0.19 (cient searching of text widgets using either exact matching, glob-style matching, or reg-) 162.9 316.83 P +(ular expressions. Y) 162.9 304.7 T +(ou can search forwards or backwards.) 238.79 304.7 T +1 F +(Mark gravity) 162.9 289.7 T +3 F +(. In Tk 3.6 marks always had \322right gravity\323, which means they stick to) 219.71 289.7 T +(the character on the right side of the mark; if you insert at the position of a mark, the) 162.9 277.56 T +-0.1 (new character goes before the mark. In Tk 4.0 you can specify whether marks have left) 162.9 265.42 P +(or right gravity) 162.9 253.29 T +(.) 222.77 253.29 T +1 F +(Scr) 162.9 238.29 T +(een information) 177.15 238.29 T +3 F +(. In Tk 4.0 there are two new widget commands for text widgets) 245.16 238.29 T +(that return information about the screen layout. The) 162.9 226.15 T +5 F +(dlineinfo) 371.92 226.15 T +3 F +( widget command) 425.89 226.15 T +(returns the bounding box of a display line \050all the information displayed on one line of) 162.9 214.02 T +(the window) 162.9 201.88 T +(, which may be either a whole line of text or a partial line if wrapping has) 209.16 201.88 T +(occurred\051. The) 162.9 189.74 T +5 F +(bbox) 224.23 189.74 T +3 F +( widget command returns the screen area occupied by a single) 248.21 189.74 T +(character) 162.9 177.61 T +(.) 198.97 177.61 T +1 F +(Extended insert command) 162.9 162.61 T +3 F +(. The) 275.06 162.61 T +5 F +(insert) 298.1 162.61 T +3 F +( widget command now supports an addi-) 334.08 162.61 T +-0.32 (tional ar) 162.9 150.47 P +-0.32 (gument giving a list of tags to apply to the new characters. Y) 195.43 150.47 P +-0.32 (ou can also include) 434 150.47 P +(several text and tag ar) 162.9 138.33 T +(guments in a single) 250.42 138.33 T +5 F +(insert) 330.38 138.33 T +3 F +( command.) 366.36 138.33 T +FMENDPAGE +%%EndPage: "10" 11 +%%Page: "11" 11 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(4 Better Motif compliance) 98.1 668.33 T +0 F +(1) 501.54 668.33 T +(1) 506.54 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +1 F +0 X +(See command) 162.9 632.33 T +3 F +(. There is a new) 222.03 632.33 T +5 F +(see) 288.08 632.33 T +3 F +( widget command, which adjusts the view in the) 306.07 632.33 T +(widget if needed to ensure that a particular character is visible in the window) 162.9 620.29 T +(.) 470.07 620.29 T +0 F +(3.5) 127.41 590.29 T +(Porting issues: tag stickiness, change in end) 152.1 590.29 T +3 F +(There are two changes in text widgets that may require modi\336cations to Tk 3.6 scripts.) 152.1 574.29 T +-0.06 (The \336rst change has to do with tag stickiness. In Tk 3.6, tags are sticky to the right: if you) 152.1 562.24 P +(insert new text just after a tagged range, the new text acquires the tags of the preceding) 152.1 550.19 T +(character) 152.1 538.14 T +(. If you insert text before a tagged range in Tk 3.6, the new characters do not) 188.17 538.14 T +-0.34 (acquire the tags of the range. In Tk 4.0, tags are not sticky on either side: new text acquires) 152.1 526.09 P +(a tag from surrounding characters only if the tag is present on both sides of the insertion) 152.1 514.05 T +(position. The sticky behavior in Tk 3.6 was rarely useful and special code was often) 152.1 502 T +(needed to work around it. Y) 152.1 489.95 T +(ou should be able to eliminate this code in Tk 4.0.) 263.24 489.95 T +(The second incompatible change in text widgets is that the index) 170.1 477.95 T +5 F +(end) 431.32 477.95 T +3 F +( now refers to) 449.31 477.95 T +-0.14 (the position just after the \336nal newline in the text, whereas in Tk 3.6 it referred to the posi-) 152.1 465.9 P +-0.1 (tion just before the \336nal newline. This makes it possible to apply tags to the \336nal newline,) 152.1 453.86 P +(which was not possible in Tk 3.6, but you may need to modify your scripts if you depend) 152.1 441.81 T +(on the old position of) 152.1 429.76 T +5 F +(end) 240.11 429.76 T +3 F +(.) 258.1 429.76 T +98.1 386.4 512.1 389.43 C +152.1 387.63 512.1 387.63 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 387.92 143.1 387.92 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(4) 134.63 393.43 T +(Better Motif compliance) 152.1 393.43 T +3 10 Q +(All of the widgets have been modi\336ed in Tk 4.0 to improve their Motif compliance. This) 152.1 369.74 T +-0.3 (was done by adding features that were missing and reworking the bindings to comply with) 152.1 357.69 P +(Motif conventions. I believe that the widgets are now completely Motif compliant except) 152.1 345.64 T +(for the following missing features:) 152.1 333.6 T +3 12 Q +(\245) 152.1 318.6 T +3 10 Q +(There is no support for secondary selections.) 162.9 318.6 T +3 12 Q +(\245) 152.1 303.6 T +3 10 Q +(There is no support for \322add mode\323 in widgets such as texts and listboxes.) 162.9 303.6 T +3 12 Q +(\245) 152.1 288.6 T +3 10 Q +(There is no support for drag and drop.) 162.9 288.6 T +-0.02 (Please let me know if you \336nd any other discrepancies between the Tk widgets and Motif) 152.1 273.59 P +(widgets. W) 152.1 261.55 T +(e plan to eliminate the remaining incompatibilities over the next year or two.) 196.82 261.55 T +98.1 218.19 512.1 221.21 C +152.1 219.41 512.1 219.41 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 219.7 143.1 219.7 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(5) 134.63 225.21 T +(W) 152.1 225.21 T +(idget changes) 163.31 225.21 T +3 10 Q +-0.07 (All of the Tk 4.0 widgets have been improved over their 3.6 counterparts, mostly in small) 152.1 201.52 P +-0.23 (and backwards compatible ways. Here is a summary of the widget improvements; see Sec-) 152.1 189.48 P +(tion 13 for information about incompatible changes.) 152.1 177.43 T +3 12 Q +(\245) 152.1 162.43 T +3 10 Q +(All widgets now have a) 162.9 162.43 T +5 F +(cget) 259.78 162.43 T +3 F +( command, which provides an easier way to retrieve the) 283.76 162.43 T +(value of a con\336guration option. In other situations where con\336guration options are) 162.9 150.38 T +(used, such as for menu entries or text tags, a) 162.9 138.33 T +5 F +(cget) 342.21 138.33 T +3 F +( command is also available.) 366.2 138.33 T +FMENDPAGE +%%EndPage: "11" 12 +%%Page: "12" 12 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(12) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 12 Q +0 X +(\245) 152.1 632.33 T +3 10 Q +-0.22 (All widgets now have) 162.9 632.33 P +5 F +-0.53 (-highlightthickness) 251.96 632.33 P +3 F +-0.22 (,) 365.9 632.33 P +5 F +-0.53 (-highlightbackground) 370.68 632.33 P +3 F +-0.22 (, and) 490.61 632.33 P +5 F +(-) 162.9 620.33 T +(highlightcolor) 168.9 620.33 T +3 F +( options for displaying a highlight ring when the widget \050or one) 252.85 620.33 T +(of its descendants\051 has the input focus.) 162.9 608.33 T +3 12 Q +(\245) 152.1 593.33 T +3 10 Q +(Entry widgets now support justi\336cation and provide a) 162.9 593.33 T +5 F +(-show) 379.99 593.33 T +3 F +( option for \050not\051 display-) 409.97 593.33 T +(ing passwords. They will autosize to \336t their text if) 162.9 581.33 T +5 F +(-width 0) 369.17 581.33 T +3 F +( is speci\336ed.) 417.14 581.33 T +3 12 Q +(\245) 152.1 566.33 T +3 10 Q +-0.16 (The label/button family of widgets now supports multiline text and justi\336cation, includ-) 162.9 566.33 P +(ing new options) 162.9 554.33 T +5 F +(-wraplength) 229.25 554.33 T +3 F +( and) 295.22 554.33 T +5 F +(-justify) 314.65 554.33 T +3 F +(. These features make the message) 361.97 554.33 T +-0.04 (widget obsolete. There is also a new) 162.9 542.33 P +5 F +-0.1 (-underline) 310.27 542.33 P +3 F +-0.04 ( option for highlighting a character) 370.23 542.33 P +(for keyboard traversal.) 162.9 530.33 T +3 12 Q +(\245) 152.1 515.33 T +3 10 Q +-0.23 (Listboxes now support all of the Motif selection modes, including single selection, mul-) 162.9 515.33 P +(tiple selection, and multiple disjoint selections, via the) 162.9 503.33 T +5 F +(-selectmode) 382.78 503.33 T +3 F +( option. They) 448.74 503.33 T +(will autosize to \336t their contents if) 162.9 491.33 T +5 F +(-width 0) 302.54 491.33 T +3 F +( or) 350.52 491.33 T +5 F +(-height 0) 363.84 491.33 T +3 F +( is speci\336ed. There are) 417.81 491.33 T +(new) 162.9 479.33 T +5 F +(see) 182.05 479.33 T +3 F +(,) 200.04 479.33 T +5 F +(bbox) 205.04 479.33 T +3 F +(, and) 229.02 479.33 T +5 F +(activate) 250.95 479.33 T +3 F +( widget commands.) 298.92 479.33 T +3 12 Q +(\245) 152.1 464.33 T +3 10 Q +(Canvas polygons now support) 162.9 464.33 T +5 F +(-outline) 286.16 464.33 T +3 F +( and) 334.14 464.33 T +5 F +(-width) 353.57 464.33 T +3 F +( options for drawing outlines.) 389.55 464.33 T +3 12 Q +(\245) 152.1 449.33 T +3 10 Q +-0.03 (Scale widgets now support real values as well as integers \050see the) 162.9 449.33 P +5 F +-0.08 (-resolution) 426.77 449.33 P +3 F +-0.03 ( and) 492.73 449.33 P +5 F +-0.54 (-digits) 162.9 437.33 P +3 F +-0.22 ( options\051, and they have a) 204.88 437.33 P +5 F +-0.54 (-variable) 308.73 437.33 P +3 F +-0.22 ( option to link to a T) 362.7 437.33 P +-0.22 (cl variable. They) 442.83 437.33 P +-0.28 (have two new widget commands,) 162.9 425.33 P +5 F +-0.67 (coords) 297.52 425.33 P +3 F +-0.28 ( and) 333.5 425.33 P +5 F +-0.67 (identify) 352.37 425.33 P +3 F +-0.28 (, and their bindings are now) 399.69 425.33 P +(de\336ned in T) 162.9 413.33 T +(cl rather than being hardwired in C code as in Tk 3.6.) 210.5 413.33 T +3 12 Q +(\245) 152.1 398.33 T +3 10 Q +(Scrollbar widgets now have a new interface to the controlling widget, which provides) 162.9 398.33 T +-0.04 (more \337exibility than the old style \050but the old style is still supported for compatibility\051.) 162.9 386.33 P +(There is a new option) 162.9 374.33 T +5 F +(-jump) 252 374.33 T +3 F +( to prevent continuous updates while dragging the slider) 281.98 374.33 T +(,) 505.88 374.33 T +-0.24 (and a new option) 162.9 362.33 P +5 F +-0.59 (-elementborderwidth) 232.98 362.33 P +3 F +-0.24 ( to control the border width of the arrows) 346.92 362.33 P +(and slider separately from the widget\325) 162.9 350.33 T +(s outer border) 314.18 350.33 T +(. There are four new widget com-) 369.14 350.33 T +(mands,) 162.9 338.33 T +5 F +(activate) 193.99 338.33 T +3 F +(,) 241.97 338.33 T +5 F +(delta) 246.96 338.33 T +3 F +(,) 276.95 338.33 T +5 F +(fraction) 281.95 338.33 T +3 F +(, and) 329.92 338.33 T +5 F +(identify) 351.85 338.33 T +3 F +(, and the default bindings) 399.17 338.33 T +(are now de\336ned in T) 162.9 326.33 T +(cl rather than being hardwired in C code as in Tk 3.6.) 244.91 326.33 T +3 12 Q +(\245) 152.1 311.33 T +3 10 Q +-0.13 (Menu entries now have several new con\336guration options such as) 162.9 311.33 P +5 F +-0.31 (-foreground) 426.97 311.33 P +3 F +-0.13 ( and) 492.93 311.33 P +5 F +-0.41 (-) 162.9 299.33 P +-0.41 (indicatoron) 168.9 299.33 P +3 F +-0.17 (, and tear) 234.86 299.33 P +-0.17 (-of) 271.23 299.33 P +-0.17 (f menus have been reimplemented to be more Motif-like.) 282.7 299.33 P +(New menu entries can be created in the middle of a menu using the) 162.9 287.33 T +5 F +(insert) 434.36 287.33 T +3 F +( widget) 470.34 287.33 T +(command, and there is a) 162.9 275.33 T +5 F +(type) 262.83 275.33 T +3 F +( widget command that returns the type of a menu entry) 286.81 275.33 T +(.) 505.45 275.33 T +3 12 Q +(\245) 152.1 260.33 T +3 10 Q +(Menubuttons now have a) 162.9 260.33 T +5 F +(-indicatoron) 266.16 260.33 T +3 F +( option for displaying an option menu indi-) 338.12 260.33 T +-0.38 (cator) 162.9 248.33 P +-0.38 (. There is now support for option menus via the) 182.33 248.33 P +5 F +-0.91 (tk_optionMenu) 370.9 248.33 P +3 F +-0.38 ( procedure, and) 448.86 248.33 P +(popups are simpli\336ed with the) 162.9 236.33 T +5 F +(tk_popup) 286.44 236.33 T +3 F +( procedure.) 334.42 236.33 T +3 12 Q +(\245) 152.1 221.33 T +3 10 Q +-0.03 (The variable) 162.9 221.33 P +5 F +-0.07 (tk_strictMotif) 215.57 221.33 P +3 F +-0.03 ( is used in more places to enforce even stricter Motif) 299.53 221.33 P +(compliance.) 162.9 209.33 T +FMENDPAGE +%%EndPage: "12" 13 +%%Page: "13" 13 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(6 Images) 98.1 668.33 T +0 F +(13) 500.99 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +98.1 623.98 512.1 627 C +152.1 625.2 512.1 625.2 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 625.49 143.1 625.49 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(6) 134.63 631 T +(Images) 152.1 631 T +3 10 Q +(Tk 4.0 contains a general-purpose image mechanism for displaying color pictures and) 152.1 607.31 T +(other complex objects. There is a new command,) 152.1 595.26 T +5 F +(image) 350.84 595.26 T +3 F +(, which may be used to create) 380.82 595.26 T +(image objects. For example, the command) 152.1 583.21 T +5 9 Q +(image create photo myFace -f) 179.1 568.88 T +(ile picture.ppm) 330.09 568.88 T +3 10 Q +(creates a new image named) 152.1 555.21 T +5 F +(myFace) 264.5 555.21 T +3 F +(. The image is of type) 300.48 555.21 T +5 F +(photo) 390.14 555.21 T +3 F +( \050a full-color represen-) 420.12 555.21 T +(tation that dithers on monochrome or color) 152.1 543.17 T +(-mapped displays\051 and the source data for the) 323.46 543.17 T +(image is in the \336le named) 152.1 531.12 T +5 F +(picture.ppm) 257.59 531.12 T +3 F +(. Once an image has been created, it can be) 323.56 531.12 T +-0.15 (used in many dif) 152.1 519.07 P +-0.15 (ferent places by specifying a) 218.37 519.07 P +5 F +-0.36 (-image) 334.46 519.07 P +3 F +-0.15 ( option. For example, the command) 370.44 519.07 P +5 9 Q +(label .l -image myFace) 179.1 504.74 T +3 10 Q +(will create a label widget that displays the image, and if) 152.1 491.07 T +5 F +(.c) 377.5 491.07 T +3 F +( is a canvas widget the com-) 389.49 491.07 T +(mand) 152.1 479.02 T +5 9 Q +(.c create image 400 200 -image myFace) 179.1 464.69 T +3 10 Q +(will create an image item in the canvas that displays) 152.1 451.02 T +5 F +(myFace) 363.06 451.02 T +3 F +(.) 399.04 451.02 T +(The image mechanism provides a great deal of \337exibility:) 170.1 439.02 T +3 12 Q +(\245) 152.1 424.02 T +3 10 Q +-0.18 (Once an image has been de\336ned, it can be used in many dif) 162.9 424.02 P +-0.18 (ferent places, even on dif) 397.84 424.02 P +-0.18 (fer-) 497.68 424.02 P +(ent displays.) 162.9 411.98 T +3 12 Q +(\245) 152.1 396.98 T +3 10 Q +(Images provide image commands, analogous to widget commands, that can be used to) 162.9 396.98 T +(manipulate the image; any changes in an image are automatically re\337ected in all of its) 162.9 384.93 T +(instances.) 162.9 372.88 T +3 12 Q +(\245) 152.1 357.88 T +3 10 Q +-0.21 (There can be many dif) 162.9 357.88 P +-0.21 (ferent types of images. Tk 4.0 has two built-in types,) 251.78 357.88 P +5 F +-0.51 (photo) 463.11 357.88 P +3 F +-0.21 ( and) 493.1 357.88 P +5 F +(bitmap) 162.9 345.83 T +3 F +(. Other image types can be de\336ned in C as extensions \050see the documentation) 198.88 345.83 T +-0.16 (for the) 162.9 333.79 P +5 F +-0.39 (Tk_CreateImageType) 191.44 333.79 P +3 F +-0.16 ( library procedure\051. The photo image type was imple-) 299.38 333.79 P +(mented by Paul Mackerras, based on his earlier photo widget.) 162.9 321.74 T +3 12 Q +(\245) 152.1 306.74 T +3 10 Q +(W) 162.9 306.74 T +(ithin the photo image type, there can be many dif) 171.93 306.74 T +(ferent \336le formats. In Tk 4.0, only) 368.29 306.74 T +-0.11 (PPM, PGM, and GIF formats are built-in, but other formats can be added as extensions) 162.9 294.69 P +(\050see the documentation for the) 162.9 282.64 T +5 F +(Tk_CreatePhotoImageFormat) 286.97 282.64 T +3 F +( library proce-) 436.89 282.64 T +(dure\051. Readers for XPM, TIFF) 162.9 270.59 T +(, and others are available from the T) 284.23 270.59 T +(cl community) 428.41 270.59 T +(.) 483.01 270.59 T +98.1 227.24 512.1 230.26 C +152.1 228.46 512.1 228.46 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 228.75 143.1 228.75 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(7) 134.63 234.26 T +(Color management) 152.1 234.26 T +3 10 Q +(Tk 3.6 suf) 152.1 210.57 T +(fers from a relatively weak mechanism for managing colors. It uses only the) 192.73 210.57 T +(default colormap for a screen, and if all the entries in that colormap \336ll up then Tk) 152.1 198.52 T +(switches to monochrome mode and \322rounds\323 all future colors to black or white. This) 152.1 186.48 T +(approach is becoming increasingly unpleasant because of applications such as Frame and) 152.1 174.43 T +(W) 152.1 162.38 T +(eb browsers that use up all the entries in the default colormap.) 160.74 162.38 T +(Tk 4.0 has a much more powerful color management mechanism. If a colormap \336lls) 170.1 150.38 T +(up, Tk allocates future colors by picking the closest match from the available colors, so) 152.1 138.33 T +FMENDPAGE +%%EndPage: "13" 14 +%%Page: "14" 14 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(14) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +(that it need not revert to monochrome mode. Tk also manages colors better by delaying) 152.1 632.33 T +-0.3 (color allocation until colors are actually needed; in many cases, such as 3D borders, colors) 152.1 620.33 P +(are never needed. When colors are scarce Tk changes the way it displays beveled borders) 152.1 608.33 T +-0.38 (so that it uses stippling instead of additional colors for the light and dark shadows. Y) 152.1 596.33 P +-0.38 (ou can) 484.01 596.33 P +(\336nd out whether a colormap has \336lled up using the new command) 152.1 584.33 T +5 F +(winfo colormap-) 418.59 584.33 T +(full) 152.1 572.33 T +3 F +(.) 176.09 572.33 T +-0.26 (Tk 4.0 also allows you to allocate new colormaps for toplevel and frame widgets with) 170.1 560.33 P +(the) 152.1 548.33 T +5 F +(-colormap) 166.81 548.33 T +3 F +( option, and you change the visual type in these widgets \050with the) 220.78 548.33 T +5 F +(-) 152.1 536.33 T +(visual) 158.1 536.33 T +3 F +( option\051 to take advantage of visuals other than the default visual for a screen.) 194.08 536.33 T +(New commands) 152.1 524.33 T +5 F +(winfo visualsavailable) 219.27 524.33 T +3 F +( and) 351.2 524.33 T +5 F +(wm colormapwindows) 370.63 524.33 T +3 F +( have) 478.57 524.33 T +(been added to help manage colormaps and visuals.) 152.1 512.33 T +(The default color scheme in Tk 4.0 has changed from a tan palette \050\322bisque\323\051 to a) 170.1 500.33 T +(gray palette, which seems to becoming standard for Motif. There is a new T) 152.1 488.33 T +(cl procedure) 454.78 488.33 T +5 F +-0.36 (tk_setPalette) 152.1 476.33 P +3 F +-0.15 ( that changes the palette of an application on the \337y) 230.06 476.33 P +-0.15 (, and there is also a) 433.89 476.33 P +(procedure) 152.1 464.33 T +5 F +(tk_bisque) 194.56 464.33 T +3 F +( to restore the palette to the old bisque colors.) 248.53 464.33 T +(The Tk 3.6 color model mechanism is no longer necessary so it has been removed in) 170.1 452.33 T +(Tk 4.0. If you want to \336nd out whether a screen is monochrome or color) 152.1 440.33 T +(, you cannot use) 440.38 440.33 T +(the) 152.1 428.33 T +5 F +(tk colormodel) 166.81 428.33 T +3 F +( command anymore; use) 244.77 428.33 T +5 F +(winfo depth) 345.25 428.33 T +3 F +( instead.) 411.22 428.33 T +98.1 384.98 512.1 388 C +152.1 386.2 512.1 386.2 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 386.49 143.1 386.49 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(8) 134.63 392 T +(Event handling: \336leevent and after) 152.1 392 T +3 10 Q +(Tk 4.0 contains several improvements in the area of event handling besides those already) 152.1 368.31 T +(mentioned for bindings:) 152.1 356.31 T +3 12 Q +(\245) 152.1 341.31 T +3 10 Q +(There is a new command) 162.9 341.31 T +5 F +(f) 265.87 341.31 T +(ileevent) 271.87 341.31 T +3 F +( for performing event-driven I/O to and from) 319.84 341.31 T +-0.12 (\336les. The) 162.9 329.31 P +5 F +-0.29 (f) 202.35 329.31 P +-0.29 (ileevent) 208.35 329.31 P +3 F +-0.12 ( command is modelled very closely after Mark Diekhans\325) 256.33 329.31 P +5 F +-0.29 (add-) 488.11 329.31 P +(input) 162.9 317.31 T +3 F +( extension, which has been used widely with Tk 3.6.) 192.88 317.31 T +3 12 Q +(\245) 152.1 302.31 T +3 10 Q +-0.34 (The) 162.9 302.31 P +5 F +-0.82 (after) 180.6 302.31 P +3 F +-0.34 ( command has two new options,) 210.58 302.31 P +5 F +-0.82 (idle) 339.82 302.31 P +3 F +-0.34 ( and) 363.81 302.31 P +5 F +-0.82 (cancel) 382.55 302.31 P +3 F +-0.34 (.) 418.53 302.31 P +5 F +-0.82 (After idle) 423.19 302.31 P +3 F +-0.34 ( can be) 482.33 302.31 P +-0.2 (used to schedule a script as an \322idle handler\323, which means it runs the next time that Tk) 162.9 290.31 P +(enters the event loop and \336nds no work to do.) 162.9 278.31 T +5 F +(After cancel) 348.06 278.31 T +3 F +( may be used to delete) 420.02 278.31 T +(a previously-scheduled) 162.9 266.31 T +5 F +(after) 257.83 266.31 T +3 F +( script, so that it will no longer be invoked.) 287.81 266.31 T +98.1 222.95 512.1 225.98 C +152.1 224.18 512.1 224.18 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 224.46 143.1 224.46 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(9) 134.63 229.98 T +(Multiple displays) 152.1 229.98 T +3 10 Q +(Although Tk has always allowed a single application to open windows on several dis-) 152.1 206.29 T +(plays, the support for multiple displays is weak in Tk 3.6. For example, many of the bind-) 152.1 194.29 T +(ings break if users work simultaneously in windows on dif) 152.1 182.29 T +(ferent displays, and) 385.94 182.29 T +(mechanisms like the selection and the input focus have insuf) 152.1 170.29 T +(\336cient support for multiple) 394.26 170.29 T +(displays.) 152.1 158.29 T +FMENDPAGE +%%EndPage: "14" 15 +%%Page: "15" 15 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(10 The send command) 98.1 668.33 T +0 F +(15) 500.99 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +-0.33 (Tk 4.0 contains numerous modi\336cations to improve the handling of multiple displays.) 170.1 632.33 P +-0.18 (Several commands, such as) 152.1 620.24 P +5 F +-0.44 (selection) 263.78 620.24 P +3 F +-0.18 (,) 317.76 620.24 P +5 F +-0.44 (send) 322.57 620.24 P +3 F +-0.18 (, and) 346.55 620.24 P +5 F +-0.44 (focus) 368.12 620.24 P +3 F +-0.18 (, have a new) 398.1 620.24 P +5 F +-0.44 (-displayof) 449.82 620.24 P +3 F +(ar) 152.1 608.15 T +(gument so that you can select a particular display) 159.69 608.15 T +(. In addition, the bindings have been) 356.12 608.15 T +(reworked to handle interactions occurring simultaneously on dif) 152.1 596.05 T +(ferent displays. W) 408.13 596.05 T +(ith Tk) 480.73 596.05 T +(4.0 it should be possible to create applications that really use multiple displays gracefully) 152.1 583.96 T +(.) 508.44 583.96 T +98.1 540.6 512.1 543.63 C +152.1 541.83 512.1 541.83 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 542.12 143.1 542.12 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(10) 127.96 547.63 T +(The send command) 152.1 547.63 T +3 10 Q +-0.2 (The) 152.1 523.94 P +5 F +-0.48 (send) 169.94 523.94 P +3 F +-0.2 ( command has been completely overhauled for Tk 4.0 to eliminate several prob-) 193.93 523.94 P +(lems in Tk 3.6 and add a number of new features:) 152.1 511.85 T +3 12 Q +(\245) 152.1 496.85 T +3 10 Q +(Tk 3.6 aborts a) 162.9 496.85 T +5 F +(send) 225.36 496.85 T +3 F +( command if no response is received within 5 seconds; this made) 249.34 496.85 T +(it very dif) 162.9 484.75 T +(\336cult to invoke long-running commands. Tk 4.0 eliminates the timeout and) 202.14 484.75 T +(uses a dif) 162.9 472.66 T +(ferent mechanism to tell if the tar) 200.47 472.66 T +(get application has crashed.) 333.53 472.66 T +3 12 Q +(\245) 152.1 457.66 T +3 10 Q +-0.36 (The) 162.9 457.66 P +5 F +-0.87 (winfo interps) 180.58 457.66 P +3 F +-0.36 ( command no longer returns the names of applications that have) 257.66 457.66 P +(exited or crashed.) 162.9 445.57 T +3 12 Q +(\245) 152.1 430.57 T +3 10 Q +(Asynchronous sends are possible using the) 162.9 430.57 T +5 F +(-async) 336.67 430.57 T +3 F +( switch.) 372.65 430.57 T +3 12 Q +(\245) 152.1 415.57 T +3 10 Q +(Commands can be sent to displays other than that of the root window) 162.9 415.57 T +(, using the) 439.3 415.57 T +5 F +(-) 162.9 403.47 T +(displayof) 168.9 403.47 T +3 F +( switch.) 222.87 403.47 T +3 12 Q +(\245) 152.1 388.47 T +3 10 Q +(W) 162.9 388.47 T +(indow server security is now checked on each) 171.93 388.47 T +5 F +(send) 357.89 388.47 T +3 F +(, so Tk 4.0 deals better with) 381.88 388.47 T +(changes in the security of the server) 162.9 376.38 T +(.) 306.12 376.38 T +3 12 Q +(\245) 152.1 361.38 T +3 10 Q +(More complete error information \050including the) 162.9 361.38 T +5 F +(errorCode) 356.09 361.38 T +3 F +( and) 410.06 361.38 T +5 F +(errorInfo) 429.49 361.38 T +3 F +( vari-) 483.46 361.38 T +(ables\051 is propagated back to the sender after errors.) 162.9 349.29 T +3 12 Q +(\245) 152.1 334.29 T +3 10 Q +(Y) 162.9 334.29 T +(ou can query and change the name of an application with the) 169.12 334.29 T +5 F +(tk appname) 414.48 334.29 T +3 F +( com-) 474.45 334.29 T +(mand.) 162.9 322.19 T +(Unfortunately the improvements to the Tk 4.0) 152.1 307.19 T +5 F +(send) 338.65 307.19 T +3 F +( mechanism required substantial) 362.63 307.19 T +(changes to the transport protocol for sends; this makes it impossible for Tk 4.0 applica-) 152.1 295.1 T +(tions to communicate with Tk 3.6 applications via) 152.1 283.01 T +5 F +(send) 355.04 283.01 T +3 F +(. The new transport protocol is) 379.02 283.01 T +(more \337exible than the old protocol, so it should be possible to make protocol improve-) 152.1 270.91 T +(ments in an upward-compatible way) 152.1 258.82 T +(.) 296.9 258.82 T +98.1 215.47 512.1 218.49 C +152.1 216.69 512.1 216.69 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 216.98 143.1 216.98 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(1) 128.62 222.49 T +(1) 134.63 222.49 T +(The selection and clipboard) 152.1 222.49 T +3 10 Q +(In Tk 3.6 the selection mechanism can deal only with the display of the root window and) 152.1 198.8 T +-0.13 (with the primary selection; there is no support for multiple displays, secondary selections,) 152.1 186.71 P +(or the clipboard. Tk 4.0 eliminates all of these shortcomings. The) 152.1 174.61 T +5 F +(-displayof) 415.82 174.61 T +3 F +( option) 475.78 174.61 T +-0.12 (can be used to specify a particular display in the selection command, and there is now full) 152.1 162.52 P +(access to all of the X selection types. Tk 4.0 also includes a new) 152.1 150.43 T +5 F +(clipboard) 411.36 150.43 T +3 F +( command) 465.33 150.43 T +(for manipulating the clipboard.) 152.1 138.33 T +FMENDPAGE +%%EndPage: "15" 16 +%%Page: "16" 16 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(16) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +98.1 623.98 512.1 627 C +152.1 625.2 512.1 625.2 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 625.49 143.1 625.49 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(12) 127.96 631 T +(Miscellaneous changes) 152.1 631 T +3 10 Q +(Here is a quick summary of the remaining changes in Tk 4.0:) 152.1 607.31 T +3 12 Q +(\245) 152.1 592.31 T +3 10 Q +-0.17 (The) 162.9 592.31 P +5 F +-0.42 (wish) 180.76 592.31 P +3 F +-0.17 ( application has been modi\336ed so that the) 204.75 592.31 P +5 F +-0.42 (-f) 371.58 592.31 P +-0.42 (ile) 383.57 592.31 P +3 F +-0.17 ( switch is no longer needed) 401.56 592.31 P +(or recommended. This makes) 162.9 580.31 T +5 F +(wish) 283.64 580.31 T +3 F +( just like) 307.63 580.31 T +5 F +(tclsh) 344.56 580.31 T +3 F +(, where you specify the script \336le) 374.54 580.31 T +(as the \336rst ar) 162.9 568.31 T +(gument to the program, e.g.) 214.07 568.31 T +5 F +(wish foo.tcl) 327.33 568.31 T +3 F +(. The) 399.29 568.31 T +5 F +(-f) 422.33 568.31 T +(ile) 434.32 568.31 T +3 F +( switch is still) 452.31 568.31 T +(permitted for backward compatibility) 162.9 556.31 T +(, but its use is deprecated.) 311.87 556.31 T +3 12 Q +(\245) 152.1 541.31 T +5 10 Q +(Wish) 162.9 541.31 T +3 F +( now sets the application\325) 186.89 541.31 T +(s class from the application name \050what appears in the) 288.49 541.31 T +-0.37 (title bar of the window by default\051, rather than always using) 162.9 529.31 P +5 F +-0.88 (Tk) 400.9 529.31 P +3 F +-0.37 ( as the class as in Tk 3.6.) 412.89 529.31 P +(This makes application-speci\336c options easier to use.) 162.9 517.31 T +3 12 Q +(\245) 152.1 502.31 T +3 10 Q +(T) 162.9 502.31 T +(oplevel windows are now resizable by default, whereas in Tk 3.6 they were not. Y) 168.31 502.31 T +(ou) 496.22 502.31 T +(can use the) 162.9 490.31 T +5 F +(wm resizable) 209.8 490.31 T +3 F +( command to make windows non-reiszable.) 281.77 490.31 T +3 12 Q +(\245) 152.1 475.31 T +3 10 Q +(Tk 4.0 patches around an Xlib bug whereby long-running applications tended to reach) 162.9 475.31 T +(the end of the space of X resource ids, wrap around to 0 again, and then crash. Tk now) 162.9 463.31 T +(reuses resource identi\336ers so that wrap-around should never occur) 162.9 451.31 T +(.) 427.14 451.31 T +3 12 Q +(\245) 152.1 436.31 T +3 10 Q +-0.13 (There is a new) 162.9 436.31 P +5 F +-0.31 (winfo manager) 223.43 436.31 P +3 F +-0.13 ( command that tells which geometry manager is con-) 301.08 436.31 P +(trolling a particular widget.) 162.9 424.31 T +3 12 Q +(\245) 152.1 409.31 T +3 10 Q +(There is a new) 162.9 409.31 T +5 F +(bell) 223.96 409.31 T +3 F +( command that does what its name suggests.) 247.94 409.31 T +3 12 Q +(\245) 152.1 394.31 T +3 10 Q +(There are new) 162.9 394.31 T +5 F +(winfo pointerx) 222.56 394.31 T +3 F +(,) 306.51 394.31 T +5 F +(winfo pointery) 311.51 394.31 T +3 F +(, and) 394.81 394.31 T +5 F +(winfo pointerxy) 416.74 394.31 T +3 F +(commands that can be used to query the position of the mouse pointer) 162.9 382.31 T +(.) 442.17 382.31 T +98.1 338.95 512.1 341.98 C +152.1 340.18 512.1 340.18 2 L +0.5 H +2 Z +0 X +0 K +N +98.1 340.46 143.1 340.46 2 L +0 Z +N +40.5 63 571.5 729 C +0 12 Q +0 X +0 K +(13) 127.96 345.98 T +(Summary of Incompatibilites) 152.1 345.98 T +3 10 Q +-0.24 (This section lists all of the incompatible changes in Tk 4.0 that may require changes in T) 152.1 322.29 P +-0.24 (cl) 502.62 322.29 P +-0.22 (scripts written for T) 152.1 310.29 P +-0.22 (cl 3.6. Each incompatibility is described in terms of the problem it pro-) 230.42 310.29 P +(duces when you run your Tk 3.6 script under Tk 4.0 and a possible work-around. Only) 152.1 298.29 T +(T) 152.1 286.29 T +(cl-level incompatibilities are covered here. For incompatible changes at the C level, see) 157.51 286.29 T +(the) 152.1 274.29 T +5 F +(README) 166.81 274.29 T +3 F +( and) 202.79 274.29 T +5 F +(changes) 222.22 274.29 T +3 F +( \336les in the distribution. The problems and solutions are) 264.2 274.29 T +(roughly in order of importance, with the most important problems \336rst.) 152.1 262.29 T +1 F +(Pr) 152.1 247.29 T +(oblem #1:) 162.46 247.29 T +3 F +(When you change the background color of a widget, a small ring in the) 206.88 247.29 T +(default background color remains around the edge of the widget.) 152.1 235.29 T +2 F +(Solution:) 170.1 223.29 T +3 F +(This is the focus traversal highlight, whose color is speci\336ed separately) 209.25 223.29 T +(from) 170.1 211.29 T +5 F +(-background) 192.03 211.29 T +3 F +(; use the) 257.99 211.29 T +5 F +(-highlightbackground) 293.8 211.29 T +3 F +( option to change the) 413.74 211.29 T +(color of the highlight. Or) 170.1 199.29 T +(, you can set) 269.92 199.29 T +5 F +(-highlightthickness) 322.38 199.29 T +3 F +( to 0 to eliminate) 436.31 199.29 T +(the traversal highlight altogether) 170.1 187.29 T +(.) 299.74 187.29 T +1 F +(Pr) 152.1 172.29 T +(oblem #2:) 162.46 172.29 T +3 F +(Bindings de\336ned for a widget no longer replace the corresponding class) 206.88 172.29 T +(bindings, so unwanted class bindings get invoked in addition to the widget bindings.) 152.1 160.29 T +FMENDPAGE +%%EndPage: "16" 17 +%%Page: "17" 17 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(13 Summary of Incompatibilites) 98.1 668.33 T +0 F +(17) 500.99 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +2 F +0 X +(Solution:) 170.1 632.33 T +3 F +(Add a) 209.25 632.33 T +5 F +(break) 235.89 632.33 T +3 F +( command at the end of the widget binding, or rework the) 265.88 632.33 T +(widget binding so that it\325) 170.1 620.33 T +(s OK for the class binding to execute.) 270.05 620.33 T +1 F +(Pr) 152.1 605.33 T +(oblem #3:) 162.46 605.33 T +3 F +(Bindings on toplevel windows are invoked when events occur for internal) 206.88 605.33 T +(windows inside the toplevels.) 152.1 593.33 T +2 F +(Solution:) 170.1 581.33 T +3 F +(Use the) 209.25 581.33 T +5 F +(%W) 242 581.33 T +3 F +( substitution to extract the name of the window where the event) 253.99 581.33 T +(actually occurred, and only execute the rest of the binding script if this matches the) 170.1 569.33 T +(name of the toplevel.) 170.1 557.33 T +1 F +-0.15 (Pr) 152.1 542.33 P +-0.15 (oblem #4:) 162.46 542.33 P +3 F +-0.15 (The) 206.58 542.33 P +5 F +-0.37 (-command) 224.46 542.33 P +3 F +-0.15 ( option for a cascade menu entry is no longer invoked when) 272.44 542.33 P +(the submenu is posted.) 152.1 530.33 T +2 F +(Solution:) 170.1 518.33 T +3 F +(Use the) 209.25 518.33 T +5 F +(-postcommand) 242 518.33 T +3 F +( option for the submenu instead.) 313.96 518.33 T +1 F +(Pr) 152.1 503.33 T +(oblem #5:) 162.46 503.33 T +3 F +(The) 206.88 503.33 T +5 F +(-geometry) 224.92 503.33 T +3 F +( option is no longer supported by listboxes, frames, and) 278.89 503.33 T +(toplevels.) 152.1 491.33 T +2 F +(Solution:) 170.1 479.33 T +3 F +(Use the) 209.25 479.33 T +5 F +(-width) 242 479.33 T +3 F +( and) 277.98 479.33 T +5 F +(-height) 297.41 479.33 T +3 F +( options instead.) 339.39 479.33 T +1 F +(Pr) 152.1 464.33 T +(oblem #6:) 162.46 464.33 T +3 F +(The procedure) 206.88 464.33 T +5 F +(tk_listboxSingleSelect) 267.38 464.33 T +3 F +( no longer exists.) 399.3 464.33 T +2 F +(Solution:) 170.1 452.33 T +3 F +(Use the) 209.25 452.33 T +5 F +(-selectmode) 242 452.33 T +3 F +( option on the listbox instead.) 307.96 452.33 T +1 F +(Pr) 152.1 437.33 T +(oblem #7:) 162.46 437.33 T +3 F +(Canvases no longer have a) 206.88 437.33 T +5 F +(-scrollincrement) 315.96 437.33 T +3 F +( option.) 411.91 437.33 T +2 F +(Solution:) 170.1 425.33 T +3 F +(Use the new) 209.25 425.33 T +5 F +(-xscrollincrement) 261.15 425.33 T +3 F +( and) 363.09 425.33 T +5 F +(-yscrollincrement) 382.52 425.33 T +3 F +(options instead.) 170.1 413.33 T +1 F +(Pr) 152.1 398.33 T +(oblem #8:) 162.46 398.33 T +3 F +(The) 206.88 398.33 T +5 F +(tk colormodel) 224.92 398.33 T +3 F +( command no longer exists.) 302.88 398.33 T +2 F +-0.28 (Solution:) 170.1 386.33 P +3 F +-0.28 (T) 208.97 386.33 P +-0.28 (o \336nd out whether a window is monochrome or color) 214.37 386.33 P +-0.28 (, use) 424.34 386.33 P +5 F +-0.68 (winfo depth) 444.6 386.33 P +3 F +(to extract the window\325) 170.1 374.33 T +(s depth; a depth of 1 means monochrome.) 259.76 374.33 T +1 F +-0.08 (Pr) 152.1 359.33 P +-0.08 (oblem #9:) 162.46 359.33 P +3 F +-0.08 (The class of Tk applications is no longer) 206.72 359.33 P +5 F +-0.19 (Tk) 370.97 359.33 P +3 F +-0.08 (, so options speci\336ed for the) 382.96 359.33 P +5 F +-0.19 (Tk) 497.69 359.33 P +3 F +(class in your) 152.1 347.33 T +5 F +(.Xdefaults) 205.12 347.33 T +3 F +( \336le are no longer used.) 265.09 347.33 T +2 F +(Solution:) 170.1 335.33 T +3 F +(Modify your) 209.25 335.33 T +5 F +(.Xdefaults) 262.55 335.33 T +3 F +( \336le \050and any T) 322.52 335.33 T +(cl code that sets options\051 to) 382.88 335.33 T +(specify the name of the application \050with the \336rst letter capitalized\051 as the class) 170.1 323.33 T +(instead of) 170.1 311.33 T +5 F +(Tk) 211.74 311.33 T +3 F +(.) 223.73 311.33 T +1 F +-0.15 (Pr) 152.1 296.33 P +-0.15 (oblem #10:) 162.46 296.33 P +3 F +-0.15 (When text is added to a text widget just after a tagged area, the new text no) 211.57 296.33 P +(longer receives the tag.) 152.1 284.33 T +2 F +-0.1 (Solution:) 170.1 272.33 P +3 F +-0.1 (Explicitly tag the new text with the desired tags. If you want the tags on the) 209.15 272.33 P +-0.08 (new text to be the same as those at some other point in the text, you can use the) 170.1 260.33 P +5 F +-0.2 (tag) 488.31 260.33 P +(names) 170.1 248.33 T +3 F +( widget command to query existing tags.) 200.08 248.33 T +1 F +(Pr) 152.1 233.33 T +(oblem #1) 162.46 233.33 T +(1:) 200.5 233.33 T +3 F +(W) 211.33 233.33 T +(idgets appear lar) 220.36 233.33 T +(ger than they did in Tk 3.6.) 286.24 233.33 T +2 F +(Solution:) 170.1 221.33 T +3 F +(There are two issues here. The \336rst is that all widgets now have a focus tra-) 209.25 221.33 T +-0.24 (versal highlight ring that turns dark when the widget has the focus; this is required for) 170.1 209.33 P +(Motif compliance but you can eliminate it by specifying a 0 value for the) 170.1 197.33 T +5 F +( -high-) 462.4 197.33 T +(lightthickness) 170.1 185.33 T +3 F +( option. The second issue is that the default padding for buttons) 254.05 185.33 T +-0.17 (and menubuttons has been increased to match the sizes of Motif widgets. If you don\325) 170.1 173.33 P +-0.17 (t) 506.99 173.33 P +(mind being dif) 170.1 161.33 T +(ferent from Motif, you can set the) 228.78 161.33 T +5 F +(-padx) 366.45 161.33 T +3 F +( and) 396.44 161.33 T +5 F +(-) 415.86 161.33 T +(pady) 421.86 161.33 T +3 F +( options back to) 445.85 161.33 T +FMENDPAGE +%%EndPage: "17" 18 +%%Page: "18" 18 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(18) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +3 F +0 X +(their Tk 3.6 values \050use the) 170.1 632.33 T +5 F +(conf) 281.41 632.33 T +(igure) 305.4 632.33 T +3 F +( widget command in Tk 3.6 to see what the) 335.38 632.33 T +(old values were\051.) 170.1 620.33 T +1 F +(Pr) 152.1 605.33 T +(oblem #12:) 162.46 605.33 T +3 F +(Listboxes now return the selection as a string with newlines separating the) 211.88 605.33 T +(values, rather than a T) 152.1 593.33 T +(cl, list.) 240.49 593.33 T +2 F +(Solution:) 170.1 581.33 T +3 F +(Modify your code to handle the new format. Y) 209.25 581.33 T +(ou can convert the selection) 395.06 581.33 T +(back into the old list format with a script like the following:) 170.1 569.33 T +5 9 Q +(split [selection get] \134n) 179.1 555 T +1 10 Q +(Pr) 152.1 541.33 T +(oblem #13:) 162.46 541.33 T +3 F +(Tk 4.0 applications cannot) 211.88 541.33 T +5 F +(send) 320.42 541.33 T +3 F +( to or be sent from Tk 3.6 applications.) 344.4 541.33 T +2 F +(Solution:) 170.1 529.33 T +3 F +(The only solution is to upgrade all your applications to Tk 4.0.) 209.25 529.33 T +1 F +-0.17 (Pr) 152.1 514.33 P +-0.17 (oblem #14:) 162.46 514.33 P +3 F +-0.17 (In texts,) 211.54 514.33 P +5 F +-0.4 (end) 245.91 514.33 P +3 F +-0.17 ( now refers to a position just after the \336nal newline, instead of) 263.9 514.33 P +(the \336nal newline.) 152.1 502.33 T +2 F +-0.08 (Solution:) 170.1 490.33 P +3 F +-0.08 (If you wish to refer to the \336nal newline, use the index) 209.17 490.33 P +5 F +-0.19 (end-1char) 424.98 490.33 P +3 F +-0.08 ( instead) 478.95 490.33 P +(of) 170.1 478.33 T +5 F +(end) 180.92 478.33 T +3 F +(.) 198.91 478.33 T +1 F +(Pr) 152.1 463.33 T +(oblem #15:) 162.46 463.33 T +3 F +(In entry widgets,) 211.88 463.33 T +5 F +(sel.last) 281.83 463.33 T +3 F +( now refers to the character just after the last) 329.8 463.33 T +(selected one, rather than the last selected one. The second index for the) 152.1 451.33 T +5 F +(delete) 438.81 451.33 T +3 F +( widget) 474.79 451.33 T +(command has changed in the same way) 152.1 439.33 T +(.) 309.66 439.33 T +2 F +(Solution:) 170.1 427.33 T +3 F +(Add one to the values used in your scripts.) 209.25 427.33 T +1 F +(Pr) 152.1 412.33 T +(oblem #16:) 162.46 412.33 T +3 F +(Because) 211.88 412.33 T +5 F +(Any) 247.68 412.33 T +3 F +( is implicit in all bindings, bindings trigger when extra modi-) 265.67 412.33 T +(\336ers are present, whereas they didn\325) 152.1 400.33 T +(t trigger in Tk 3.6.) 296.24 400.33 T +2 F +(Solution:) 170.1 388.33 T +3 F +(In most cases it\325) 209.25 388.33 T +(s probably \336ne to ignore the extra modi\336ers. If you really) 273.93 388.33 T +-0.12 (don\325) 170.1 376.33 P +-0.12 (t want any actions to be taken when extra modi\336ers are present, create additional) 188.24 376.33 P +(bindings for the cases with extra modi\336ers, and specify a single blank character \050or) 170.1 364.33 T +(any script that does nothing\051 as the script for those bindings. Alternatively) 170.1 352.33 T +(, you can) 465.93 352.33 T +(use the) 170.1 340.33 T +5 F +(%s) 200.63 340.33 T +3 F +( substitution to extract the mouse and modi\336er state in the event binding,) 212.63 340.33 T +(then you can test this value for modi\336ers you do or don\325) 170.1 328.33 T +(t want.) 394.5 328.33 T +1 F +(Pr) 152.1 313.33 T +(oblem #17:) 162.46 313.33 T +3 F +(In scrollbars there is no longer a) 211.88 313.33 T +5 F +(-foreground) 343.17 313.33 T +3 F +( or) 409.13 313.33 T +5 F +(-activefore-) 422.45 313.33 T +(ground) 152.1 301.33 T +3 F +( option, and) 188.08 301.33 T +5 F +(-background) 238.05 301.33 T +3 F +( has a dif) 304.02 301.33 T +(ferent meaning.) 340.2 301.33 T +2 F +-0.4 (Solution:) 170.1 289.33 P +3 F +-0.4 (Use) 208.85 289.33 P +5 F +-0.96 (-troughcolor) 226.49 289.33 P +3 F +-0.4 ( everywhere that you used) 298.45 289.33 P +5 F +-0.96 (-background) 403.87 289.33 P +3 F +-0.4 ( in Tk 3.6,) 469.83 289.33 P +5 F +(-background) 170.1 277.33 T +3 F +( everywhere you used to use) 236.06 277.33 T +5 F +(-foreground) 352.08 277.33 T +3 F +(, and) 418.04 277.33 T +5 F +(-activeback-) 439.97 277.33 T +(ground) 170.1 265.33 T +3 F +( everywhere you used to use) 206.08 265.33 T +5 F +(-activeforeground) 322.1 265.33 T +3 F +(.) 424.04 265.33 T +1 F +(Pr) 152.1 250.33 T +(oblem #18:) 162.46 250.33 T +3 F +(Options for colors seem to have changed in scale widgets.) 211.88 250.33 T +2 F +(Solution:) 170.1 238.33 T +3 F +(Use) 209.25 238.33 T +5 F +(-background) 227.29 238.33 T +3 F +( where you used to use) 293.25 238.33 T +5 F +(-sliderforeground) 387.07 238.33 T +3 F +(,) 489.02 238.33 T +5 F +(-) 170.1 226.33 T +(troughcolor) 176.1 226.33 T +3 F +( where you used to use) 242.06 226.33 T +5 F +(-background) 335.88 226.33 T +3 F +(, and) 401.84 226.33 T +5 F +( -activeback-) 421.27 226.33 T +(ground) 170.1 214.33 T +3 F +( everywhere you used to use) 206.08 214.33 T +5 F +(-activeforeground) 322.1 214.33 T +3 F +(.) 424.04 214.33 T +1 F +(Pr) 152.1 199.33 T +(oblem #19:) 162.46 199.33 T +3 F +(Scale widgets no longer accept hexadecimal or octal numbers in the) 211.88 199.33 T +5 F +(set) 485.84 199.33 T +3 F +(command or the) 152.1 187.33 T +5 F +(-from) 219.55 187.33 T +3 F +( and) 249.54 187.33 T +5 F +(-to) 268.97 187.33 T +3 F +( options.) 286.96 187.33 T +2 F +(Solution:) 170.1 175.33 T +3 F +(Use) 209.25 175.33 T +5 F +(format) 227.29 175.33 T +3 F +( or) 263.27 175.33 T +5 F +(expr) 276.59 175.33 T +3 F +( to convert the values to decimal.) 300.58 175.33 T +1 F +(Pr) 152.1 160.33 T +(oblem #20:) 162.46 160.33 T +3 F +(In checkbuttons, radiobuttons, and menu entries, the) 211.88 160.33 T +5 F +(-selector) 423.4 160.33 T +3 F +( option) 477.37 160.33 T +(no longer exists.) 152.1 148.33 T +FMENDPAGE +%%EndPage: "18" 19 +%%Page: "19" 19 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(13 Summary of Incompatibilites) 98.1 668.33 T +0 F +(19) 500.99 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +2 F +0 X +(Solution:) 170.1 632.33 T +3 F +(Use) 209.25 632.33 T +5 F +(-selectcolor) 227.29 632.33 T +3 F +( instead of) 299.25 632.33 T +5 F +(-select) 343.39 632.33 T +3 F +(. T) 385.36 632.33 T +(o specify that no indicator) 395.77 632.33 T +(should be drawn at all, use the) 170.1 620.33 T +5 F +(-indicatoron) 293.9 620.33 T +3 F +( option instead of setting) 365.86 620.33 T +5 F +(-select) 467.2 620.33 T +3 F +(to an empty string.) 170.1 608.33 T +1 F +-0.12 (Pr) 152.1 593.33 P +-0.12 (oblem #21:) 162.46 593.33 P +3 F +-0.12 (The indices of menu entries have changed, and operations on menu entry 0) 211.64 593.33 P +(no longer work.) 152.1 581.33 T +2 F +(Solution:) 170.1 569.33 T +3 F +(This is because menus now have a tearof) 209.25 569.33 T +(f entry at the top by default, and) 372.55 569.33 T +(this occupies entry 0, so your \336rst entry is now entry 1. Y) 170.1 557.33 T +(ou can either set the) 398.95 557.33 T +5 F +(-) 170.1 545.33 T +(tearoff) 176.1 545.33 T +3 F +( option to 0 to eliminate the tearof) 218.07 545.33 T +(f entry or add 1 to all the indices you) 354.2 545.33 T +(use in your scripts.) 170.1 533.33 T +1 F +-0.22 (Pr) 152.1 518.33 P +-0.22 (oblem #22:) 162.46 518.33 P +3 F +-0.22 (The) 211.44 518.33 P +5 F +-0.53 (enable) 229.26 518.33 P +3 F +-0.22 ( and) 265.24 518.33 P +5 F +-0.53 (disable) 284.23 518.33 P +3 F +-0.22 ( widget commands are no longer supported by) 326.21 518.33 P +(menus.) 152.1 506.33 T +2 F +(Solution:) 170.1 494.33 T +3 F +(Use the) 209.25 494.33 T +5 F +(-state) 242 494.33 T +3 F +( con\336guration option instead.) 277.98 494.33 T +1 F +(Pr) 152.1 479.33 T +(oblem #23:) 162.46 479.33 T +3 F +(The) 211.88 479.33 T +5 F +(activate) 229.92 479.33 T +3 F +( and) 277.89 479.33 T +5 F +(deactivate) 297.32 479.33 T +3 F +( widget commands are no longer sup-) 357.29 479.33 T +(ported by buttons, checkbuttons, radiobuttons, and menus.) 152.1 467.33 T +2 F +(Solution:) 170.1 455.33 T +3 F +(Use the) 209.25 455.33 T +5 F +(-state) 242 455.33 T +3 F +( con\336guration option instead.) 277.98 455.33 T +1 F +(Pr) 152.1 440.33 T +(oblem #24:) 162.46 440.33 T +3 F +(Canvas arc items no longer use the) 211.88 440.33 T +5 F +(-f) 353.72 440.33 T +(ill) 365.71 440.33 T +3 F +( and) 383.7 440.33 T +5 F +(-stipple) 403.13 440.33 T +3 F +( options for) 451.11 440.33 T +(drawing when the) 152.1 428.33 T +5 F +(-style) 226.21 428.33 T +3 F +( option is) 262.19 428.33 T +5 F +(arc) 301.9 428.33 T +3 F +(.) 319.89 428.33 T +2 F +(Solution:) 170.1 416.33 T +3 F +(Use the) 209.25 416.33 T +5 F +(-outline) 242 416.33 T +3 F +( and) 289.97 416.33 T +5 F +(-outlinestipple) 309.4 416.33 T +3 F +( options instead.) 399.35 416.33 T +1 F +-0.29 (Pr) 152.1 401.33 P +-0.29 (oblem #25:) 162.46 401.33 P +3 F +-0.29 (The variable) 211.29 401.33 P +5 F +-0.7 (tkVersion) 263.43 401.33 P +3 F +-0.29 ( no longer exists \050it has been obsolete for several) 317.4 401.33 P +(releases\051.) 152.1 389.33 T +2 F +(Solution:) 170.1 377.33 T +3 F +(Use) 209.25 377.33 T +5 F +(tk_version) 227.29 377.33 T +3 F +( instead.) 287.26 377.33 T +1 F +(Pr) 152.1 362.33 T +(oblem #26:) 162.46 362.33 T +3 F +(The syntax of the) 211.88 362.33 T +5 F +(scan) 284.05 362.33 T +3 F +( widget commands for texts has changed.) 308.03 362.33 T +2 F +(Solution:) 170.1 350.33 T +3 F +(Modify your code to use the new syntax.) 209.25 350.33 T +1 F +(Pr) 152.1 335.33 T +(oblem #27:) 162.46 335.33 T +5 F +(wish) 211.88 335.33 T +3 F +( no longer recognizes the) 235.86 335.33 T +5 F +(-help) 338.84 335.33 T +3 F +( option.) 368.82 335.33 T +2 F +(Solution:) 170.1 323.33 T +3 F +(Implement this option yourself in your) 209.25 323.33 T +5 F +(wish) 366.38 323.33 T +3 F +( scripts.) 390.37 323.33 T +1 F +(Pr) 152.1 308.33 T +(oblem #28:) 162.46 308.33 T +3 F +(Tk 4.0 always prints real numbers such as canvas coordinates with a deci-) 211.88 308.33 T +(mal point. This can cause syntax errors if you later use them in situations where integers) 152.1 296.33 T +(are expected.) 152.1 284.33 T +2 F +(Solution:) 170.1 272.33 T +3 F +(Change your code so that real numbers work OK, or use the) 209.25 272.33 T +5 F +(expr) 451.57 272.33 T +3 F +( com-) 475.55 272.33 T +(mand \050with the) 170.1 260.33 T +5 F +(round) 233.12 260.33 T +3 F +( function\051 to convert the numbers to integers.) 263.1 260.33 T +1 F +(Pr) 152.1 245.33 T +(oblem #29:) 162.46 245.33 T +3 F +(The) 211.88 245.33 T +5 F +(pack info) 229.92 245.33 T +3 F +( command returns dif) 283.89 245.33 T +(ferent information, and) 369.48 245.33 T +5 F +(pack) 464.41 245.33 T +(newinfo) 152.1 233.33 T +3 F +( no longer exists.) 194.08 233.33 T +2 F +(Solution:) 170.1 221.33 T +3 F +(Use) 209.25 221.33 T +5 F +(pack info) 227.29 221.33 T +3 F +( where you used to use) 281.26 221.33 T +5 F +(pack newinfo) 375.08 221.33 T +3 F +(.) 447.04 221.33 T +5 F +(Pack info) 452.04 221.33 T +3 F +(was obsolete, so it has been eliminated.) 170.1 209.33 T +1 F +(Pr) 152.1 194.33 T +(oblem #30:) 162.46 194.33 T +3 F +(The) 211.88 194.33 T +5 F +(view) 229.92 194.33 T +3 F +( widget command for entries no longer exists, nor does the) 253.9 194.33 T +5 F +(-) 152.1 182.33 T +(scrollcommand) 158.1 182.33 T +3 F +( option.) 236.05 182.33 T +2 F +-0.29 (Solution:) 170.1 170.33 P +3 F +-0.29 (Use) 208.96 170.33 P +5 F +-0.69 (xview) 226.71 170.33 P +3 F +-0.29 ( where you used to use) 256.7 170.33 P +5 F +-0.69 (view) 348.8 170.33 P +3 F +-0.29 (; use) 372.78 170.33 P +5 F +-0.69 (-xscrollcommand) 393.31 170.33 P +3 F +-0.29 ( where) 483.26 170.33 P +(you used to use) 170.1 158.33 T +5 F +(-scrollcommand) 234.51 158.33 T +3 F +(.) 318.46 158.33 T +FMENDPAGE +%%EndPage: "19" 20 +%%Page: "20" 20 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(20) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +1 F +0 X +(Pr) 152.1 632.33 T +(oblem #31:) 162.46 632.33 T +3 F +(The) 211.88 632.33 T +5 F +(-padx) 229.92 632.33 T +3 F +( and) 259.9 632.33 T +5 F +(-pady) 279.33 632.33 T +3 F +( options are ignored for the button family of wid-) 309.31 632.33 T +(gets if a bitmap or image is being displayed: the padding is always 0.) 152.1 620.02 T +2 F +-0.27 (Solution:) 170.1 608.02 P +3 F +-0.27 (Pack the button inside a frame, with extra padding in the frame. Or) 208.98 608.02 P +-0.27 (, redo the) 472.94 608.02 P +(image or bitmap to incorporate padding into it.) 170.1 595.71 T +1 F +(Pr) 152.1 580.71 T +(oblem #32:) 162.46 580.71 T +3 F +(In radiobuttons, the) 211.88 580.71 T +5 F +(-value) 292.38 580.71 T +3 F +( option no longer defaults to the name of the) 328.36 580.71 T +(widget; it defaults to an empty string.) 152.1 568.4 T +2 F +(Solution:) 170.1 556.4 T +3 F +(Specify the widget\325) 209.25 556.4 T +(s name explicitly as the value of the option.) 286.98 556.4 T +1 F +(Pr) 152.1 541.4 T +(oblem #33:) 162.46 541.4 T +3 F +(The) 211.88 541.4 T +5 F +(-menu) 229.92 541.4 T +3 F +( option for menubuttons and cascade menu entries may refer) 259.9 541.4 T +(only to a child of the menubutton or menu.) 152.1 529.08 T +2 F +(Solution:) 170.1 517.08 T +3 F +(Rename menus to meet this requirement.) 209.25 517.08 T +1 F +(Pr) 152.1 502.08 T +(oblem #34:) 162.46 502.08 T +3 F +(The interpretation of) 211.88 502.08 T +5 F +(@y) 297.09 502.08 T +3 F +( in menus has changed: it never returns) 309.08 502.08 T +5 F +(none) 467.86 502.08 T +3 F +(,) 491.84 502.08 T +(even if the y-coordinate is outside the menu \050it returns the index of the closest entry\051.) 152.1 489.77 T +2 F +(Solution:) 170.1 477.77 T +3 F +(If you care about this distinction, check the y-coordinate explicitly to see if) 209.25 477.77 T +-0.17 (it is less than 0 or greater than or equal to the window\325) 170.1 465.46 P +-0.17 (s height \050use) 385.7 465.46 P +5 F +-0.41 (winfo height) 438.21 465.46 P +3 F +(to get the height\051.) 170.1 453.15 T +1 F +-0.13 (Pr) 152.1 438.15 P +-0.13 (oblem #35:) 162.46 438.15 P +3 F +-0.13 (The) 211.62 438.15 P +5 F +-0.3 (invoke) 229.54 438.15 P +3 F +-0.13 ( and) 265.52 438.15 P +5 F +-0.3 (activate) 284.7 438.15 P +3 F +-0.13 ( widget commands for menus no longer post) 332.67 438.15 P +(cascaded submenus.) 152.1 425.83 T +2 F +(Solution:) 170.1 413.83 T +3 F +(Use the) 209.25 413.83 T +5 F +(postcascade) 242 413.83 T +3 F +( widget command to post submenus.) 307.96 413.83 T +1 F +(Pr) 152.1 398.83 T +(oblem #36:) 162.46 398.83 T +3 F +(The selection tar) 211.88 398.83 T +(gets) 278.31 398.83 T +5 F +(APPLICATION) 296.91 398.83 T +3 F +( and) 362.87 398.83 T +5 F +(WINDOW_NAME) 382.3 398.83 T +3 F +( are no longer) 448.27 398.83 T +(supported.) 152.1 386.52 T +2 F +(Solution:) 170.1 374.52 T +3 F +(Use tar) 209.25 374.52 T +(gets) 237.65 374.52 T +5 F +(TK_APPLICATION) 256.25 374.52 T +3 F +( and) 340.21 374.52 T +5 F +(TK_WINDOW) 359.64 374.52 T +3 F +( instead.) 413.61 374.52 T +1 F +(Pr) 152.1 359.52 T +(oblem #37:) 162.46 359.52 T +3 F +(There is no longer a default focus.) 211.88 359.52 T +2 F +(Solution:) 170.1 347.52 T +3 F +(None: modify your code not to depend on this feature.) 209.25 347.52 T +1 F +(Pr) 152.1 332.52 T +(oblem #38:) 162.46 332.52 T +3 F +(The) 211.88 332.52 T +5 F +(focus) 229.92 332.52 T +3 F +( command now returns an empty string to indicate that the) 259.9 332.52 T +(application doesn\325) 152.1 320.21 T +(t have the input focus, instead of) 225.48 320.21 T +5 F +(none) 358.17 320.21 T +3 F +(.) 382.15 320.21 T +2 F +(Solution:) 170.1 308.21 T +3 F +(Modify your code to check for an empty string instead of) 209.25 308.21 T +5 F +(none) 440.47 308.21 T +3 F +(.) 464.46 308.21 T +1 F +(Pr) 152.1 293.21 T +(oblem #39:) 162.46 293.21 T +5 F +(FocusIn) 211.88 293.21 T +3 F +( and) 253.85 293.21 T +5 F +(FocusOut) 273.28 293.21 T +3 F +( events are delivered to more windows than) 321.26 293.21 T +(they used to be.) 152.1 280.9 T +2 F +-0.02 (Solution:) 170.1 268.9 P +3 F +-0.02 (Modify your code to use the new set of events. The old event set was some-) 209.23 268.9 P +(what bizarre, and the new set matches more closely what happens elsewhere, such as) 170.1 256.58 T +(with) 170.1 244.27 T +5 F +(Enter) 190.37 244.27 T +3 F +( and) 220.35 244.27 T +5 F +(Leave) 239.78 244.27 T +3 F +( events.) 269.77 244.27 T +1 F +-0.28 (Pr) 152.1 229.27 P +-0.28 (oblem #40:) 162.46 229.27 P +5 F +-0.67 (wm maxsize) 211.32 229.27 P +3 F +-0.28 ( and) 270.62 229.27 P +5 F +-0.67 (wm minsize) 289.49 229.27 P +3 F +-0.28 ( no longer accept empty ar) 348.79 229.27 P +-0.28 (guments. This) 453.52 229.27 P +(means that you cannot use these commands to make windows non-resizable.) 152.1 216.96 T +2 F +(Solution:) 170.1 204.96 T +3 F +(Use the) 209.25 204.96 T +5 F +(wm resizable) 242 204.96 T +3 F +( command to make windows resizable.) 313.96 204.96 T +1 F +(Pr) 152.1 189.96 T +(oblem #41:) 162.46 189.96 T +3 F +(In the placer) 211.88 189.96 T +(, if you specify both) 261.43 189.96 T +5 F +(-x) 344.15 189.96 T +3 F +( and) 356.15 189.96 T +5 F +(-relx) 375.58 189.96 T +3 F +( then they add, instead of) 405.56 189.96 T +(the most recent speci\336cation replacing the earlier one. Ditto for) 152.1 177.65 T +5 F +(-y) 407.74 177.65 T +3 F +( and) 419.73 177.65 T +5 F +(-rely) 439.16 177.65 T +3 F +(,) 468.5 177.65 T +5 F +(-width) 473.49 177.65 T +3 F +(and) 152.1 165.33 T +5 F +(-relwidth) 169.03 165.33 T +3 F +(, and) 223 165.33 T +5 F +(-height) 244.93 165.33 T +3 F +( and) 286.91 165.33 T +5 F +(-relheight) 306.33 165.33 T +3 F +(.) 366.3 165.33 T +2 F +(Solution:) 170.1 153.33 T +3 F +(If you no longer want one of these options to be used, set it to 0 explicitly) 209.25 153.33 T +(.) 503.14 153.33 T +1 F +(Pr) 152.1 138.33 T +(oblem #42:) 162.46 138.33 T +3 F +(The command \322) 211.88 138.33 T +5 F +(focus none) 276.27 138.33 T +3 F +(\323 doesn\325) 336.24 138.33 T +(t work in Tk 4.0.) 369.64 138.33 T +FMENDPAGE +%%EndPage: "20" 21 +%%Page: "21" 21 +612 792 0 FMBEGINPAGE +4 10 Q +0 X +0 K +(13 Summary of Incompatibilites) 98.1 668.33 T +0 F +(21) 500.99 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +2 F +0 X +(Solution:) 170.1 632.33 T +3 F +(Create a dummy widget that is never mapped and set the focus to that wid-) 209.25 632.33 T +(get.) 170.1 620.33 T +1 F +(Pr) 152.1 605.33 T +(oblem #43:) 162.46 605.33 T +5 F +(%D) 211.88 605.33 T +3 F +( substitutions are no longer supported in bindings, nor are the event) 223.87 605.33 T +(types) 152.1 593.33 T +5 F +(CirculateRequest) 175.7 593.33 T +3 F +(,) 271.64 593.33 T +5 F +(Conf) 276.64 593.33 T +(igureRequest) 300.63 593.33 T +3 F +(,) 372.59 593.33 T +5 F +(MapRequest) 377.59 593.33 T +3 F +(, and) 437.55 593.33 T +5 F +(Resiz-) 459.48 593.33 T +(eRequest) 152.1 581.33 T +3 F +(.) 200.07 581.33 T +2 F +-0.25 (Solution:) 170.1 569.33 P +3 F +-0.25 (Use the name of the display instead of %D to identify a display; you can get) 209 569.33 P +(the display name with the) 170.1 557.33 T +5 F +(winfo screen) 275.31 557.33 T +3 F +( command. The desupported event types) 347.27 557.33 T +(never really worked anyway) 170.1 545.33 T +(, so there should be no code that depends on them.) 282.96 545.33 T +1 F +(Pr) 152.1 530.33 T +(oblem #44:) 162.46 530.33 T +5 F +(%) 211.88 530.33 T +3 F +( binding substitutions that return window identi\336ers, such as) 217.87 530.33 T +5 F +(%a) 461.63 530.33 T +3 F +( and) 473.62 530.33 T +5 F +(%S) 493.05 530.33 T +3 F +(,) 505.05 530.33 T +(now produce hexadecimal results instead of decimal.) 152.1 518.33 T +2 F +(Solution:) 170.1 506.33 T +3 F +(Use the) 209.25 506.33 T +5 F +(format) 242 506.33 T +3 F +( command to turn them back to decimal.) 277.98 506.33 T +1 F +(Pr) 152.1 491.33 T +(oblem #45:) 162.46 491.33 T +5 F +(Enter) 211.88 491.33 T +3 F +(,) 241.46 491.33 T +5 F +(Leave) 246.46 491.33 T +3 F +(,) 276.44 491.33 T +5 F +(FocusIn) 281.44 491.33 T +3 F +(, and) 323.42 491.33 T +5 F +(FocusOut) 345.34 491.33 T +3 F +( events with detail) 393.32 491.33 T +5 F +(Notify-) 468.83 491.33 T +(Inferior) 152.1 479.33 T +3 F +( are now ignored by the binding mechanism, so they\325re not visible to T) 200.07 479.33 T +(cl) 483.08 479.33 T +(scripts.) 152.1 467.33 T +2 F +-0.13 (Solution:) 170.1 455.33 P +3 F +-0.13 (In most cases, T) 209.12 455.33 P +-0.13 (cl scripts work better if these bindings are ignored. Y) 273 455.33 P +-0.13 (ou can) 483.49 455.33 P +(still use C code to access these events if you really need them. Or) 170.1 443.33 T +(, create bindings on) 431.18 443.33 T +-0.33 (the inferior windows and use) 170.1 431.33 P +5 F +-0.8 (NotifyAncestor) 286.96 431.33 P +3 F +-0.33 ( bindings on the children instead of) 370.91 431.33 P +5 F +(NotifyInferior) 170.1 419.33 T +3 F +( bindings on the parent.) 254.05 419.33 T +FMENDPAGE +%%EndPage: "21" 22 +%%Page: "22" 22 +612 792 0 FMBEGINPAGE +0 10 Q +0 X +0 K +(22) 98.1 668.33 T +4 F +(Tk4.0 Overview and Porting Guide) 359.34 668.33 T +98.1 660.6 512.1 660.6 2 L +0.25 H +0 Z +N +98.1 135 512.1 639 R +7 X +V +FMENDPAGE +%%EndPage: "22" 23 +%%Trailer +%%BoundingBox: 0 0 612 792 +%%Pages: 22 1 +%%DocumentFonts: Helvetica-Bold +%%+ Times-Bold +%%+ Times-Italic +%%+ Times-Roman +%%+ Helvetica +%%+ Courier +%%+ Courier-Oblique diff --git a/doc/tkerror.n b/doc/tkerror.n new file mode 100644 index 0000000..c892a64 --- /dev/null +++ b/doc/tkerror.n @@ -0,0 +1,38 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) tkerror.n 1.19 97/10/31 12:58:53 +'\" +.so man.macros +.TH tkerror n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tkerror \- Command invoked to process background errors +.SH SYNOPSIS +\fBtkerror \fImessage\fR +.BE + +.SH DESCRIPTION +.PP +Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to +\fBbgerror\fR because the event loop (which is what usually invokes +it) is now part of Tcl. For backward compatibility +the \fBbgerror\fR provided by the current Tk version still +tries to call \fBtkerror\fR if there is one (or an auto loadable one), +so old script defining that error handler should still work, but you +should anyhow modify your scripts to use \fBbgerror\fR instead +of \fBtkerror\fR because that support for the old name might vanish +in the near future. If that call fails, \fBbgerror\fR +posts a dialog showing the error and offering to see the stack trace +to the user. If you want your own error management you should +directly override \fBbgerror\fR instead of \fBtkerror\fR. +Documentation for \fBbgerror\fR is available as part of Tcl's +documentation. + +.SH KEYWORDS +background error, reporting diff --git a/doc/tkvars.n b/doc/tkvars.n new file mode 100644 index 0000000..947d574 --- /dev/null +++ b/doc/tkvars.n @@ -0,0 +1,72 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) tkvars.n 1.22 96/08/27 13:21:38 +'\" +.so man.macros +.TH tkvars n 4.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tkvars \- Variables used or set by Tk +.BE + +.SH DESCRIPTION +.PP +The following Tcl variables are either set or used by Tk at various times +in its execution: +.TP 15 +\fBtk_library\fR +This variable holds the file name for a directory containing a library +of Tcl scripts related to Tk. These scripts include an initialization +file that is normally processed whenever a Tk application starts up, +plus other files containing procedures that implement default behaviors +for widgets. +The initial value of \fBtcl_library\fR is set when Tk is added to +an interpreter; this is done by searching several different directories +until one is found that contains an appropriate Tk startup script. +If the \fBTK_LIBRARY\fR environment variable exists, then +the directory it names is checked first. +If \fBTK_LIBRARY\fR isn't set or doesn't refer to an appropriate +directory, then Tk checks several other directories based on a +compiled-in default location, the location of the Tcl library directory, +the location of the binary containing the application, and the current +working directory. +The variable can be modified by an application to switch to a different +library. +.TP +\fBtk_patchLevel\fR +Contains a decimal integer giving the current patch level for Tk. +The patch level is incremented for each new release or patch, and +it uniquely identifies an official version of Tk. +.TP +\fBtkPriv\fR +This variable is an array containing several pieces of information +that are private to Tk. The elements of \fBtkPriv\fR are used by +Tk library procedures and default bindings. +They should not be accessed by any code outside Tk. +.TP +\fBtk_strictMotif\fR +This variable is set to zero by default. +If an application sets it to one, then Tk attempts to adhere as +closely as possible to Motif look-and-feel standards. +For example, active elements such as buttons and scrollbar +sliders will not change color when the pointer passes over them. +.TP 15 +\fBtk_version\fR +Tk sets this variable in the interpreter for each application. +The variable holds the current version number of the Tk +library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and +\fIminor\fR are integers. The major version number increases in +any Tk release that includes changes that are not backward compatible +(i.e. whenever existing Tk applications and scripts may have to change to +work with the new release). The minor version number increases with +each new release of Tk, except that it resets to zero whenever the +major version number changes. + +.SH KEYWORDS +variables, version diff --git a/doc/tkwait.n b/doc/tkwait.n new file mode 100644 index 0000000..6446768 --- /dev/null +++ b/doc/tkwait.n @@ -0,0 +1,51 @@ +'\" +'\" Copyright (c) 1992 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) tkwait.n 1.13 96/07/31 08:19:23 +'\" +.so man.macros +.TH tkwait n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tkwait \- Wait for variable to change or window to be destroyed +.SH SYNOPSIS +\fBtkwait variable \fIname\fR +.sp +\fBtkwait visibility \fIname\fR +.sp +\fBtkwait window \fIname\fR +.BE + +.SH DESCRIPTION +.PP +The \fBtkwait\fR command waits for one of several things to happen, +then it returns without taking any other actions. +The return value is always an empty string. +If the first argument is \fBvariable\fR (or any abbreviation of +it) then the second argument is the name of a global variable and the +command waits for that variable to be modified. +If the first argument is \fBvisibility\fR (or any abbreviation +of it) then the second argument is the name of a window and the +\fBtkwait\fR command waits for a change in its +visibility state (as indicated by the arrival of a VisibilityNotify +event). This form is typically used to wait for a newly-created +window to appear on the screen before taking some action. +If the first argument is \fBwindow\fR (or any abbreviation +of it) then the second argument is the name of a window and the +\fBtkwait\fR command waits for that window to be destroyed. +This form is typically used to wait for a user to finish interacting +with a dialog box before using the result of that interaction. +.PP +While the \fBtkwait\fR command is waiting it processes events in +the normal fashion, so the application will continue to respond +to user interactions. +If an event handler invokes \fBtkwait\fR again, the nested call +to \fBtkwait\fR must complete before the outer call can complete. + +.SH KEYWORDS +variable, visibility, wait, window diff --git a/doc/toplevel.n b/doc/toplevel.n new file mode 100644 index 0000000..567ef33 --- /dev/null +++ b/doc/toplevel.n @@ -0,0 +1,163 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) toplevel.n 1.29 97/10/31 12:58:53 +'\" +.so man.macros +.TH toplevel n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +toplevel \- Create and manipulate toplevel widgets +.SH SYNOPSIS +\fBtoplevel\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-borderwidth \-highlightbackground \-highlightthickness \-takefocus +\-cursor \-highlightcolor \-relief +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-background background Background +This option is the same as the standard \fBbackground\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 colors will be consumed from its colormap for its background +and border. +.OP \-class class Class +Specifies a class for the window. +This class will be used when querying the option database for +the window's other options, and it will also be used later for +other purposes such as bindings. +The \fBclass\fR option may not be changed with the \fBconfigure\fR +widget command. +.OP \-colormap colormap Colormap +Specifies a colormap to use for the window. +The value may be either \fBnew\fR, in which case a new colormap is +created for the window and its children, or the name of another +window (which must be on the same screen and have the same visual +as \fIpathName\fR), in which case the new window will use the colormap +from the specified window. +If the \fBcolormap\fR option is not specified, the new window +uses the default colormap of its screen. +This option may not be changed with the \fBconfigure\fR +widget command. +.VS 8.0 br +.OP \-container container Container +The value must be a boolean. If true, it means that this window will +be used as a container in which some other application will be embedded +(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). +The window will support the appropriate window manager protocols for +things like geometry requests. The window should not have any +children of its own in this application. +This option may not be changed with the \fBconfigure\fR +widget command. +.VE +.OP \-height height Height +Specifies the desired height for the window in any of the forms +acceptable to \fBTk_GetPixels\fR. +If this option is less than or equal to zero then the window will +not request any size at all. +.VS 8.0 br +.OP \-menu menu Menu +Specifies a menu widget to be used as a menubar. On the Macintosh, the +menubar will be displayed accross the top of the main monitor. On +Microsoft Windows and all UNIX platforms, the menu will appear accross +the toplevel window as part of the window dressing maintained by the +window manager. +.VE +.OP \-screen "" "" +Specifies the screen on which to place the new window. +Any valid screen name may be used, even one associated with a +different display. +Defaults to the same screen as its parent. +This option is special in that it may not be specified via the option +database, and it may not be modified with the \fBconfigure\fR +widget command. +.VS 8.0 br +.OP \-use use Use +This option is used for embedding. If the value isn't an empty string, +it must be the the window identifier of a container window, specified as +a hexadecimal string like the ones returned by the \fBwinfo id\fR +command. The toplevel widget will be created as a child of the given +container instead of the root window for the screen. If the container +window is in a Tk application, it must be a frame or toplevel widget for +which the \fB\-container\fR option was specified. +This option may not be changed with the \fBconfigure\fR +widget command. +.VE +.OP \-visual visual Visual +Specifies visual information for the new window in any of the +forms accepted by \fBTk_GetVisual\fR. +If this option is not specified, the new window will use the default +visual for its screen. +The \fBvisual\fR option may not be modified with the \fBconfigure\fR +widget command. +.OP \-width width Width +Specifies the desired width for the window in any of the forms +acceptable to \fBTk_GetPixels\fR. +If this option is less than or equal to zero then the window will +not request any size at all. +.BE + +.SH DESCRIPTION +.PP +The \fBtoplevel\fR command creates a new toplevel widget (given +by the \fIpathName\fR argument). Additional +options, described above, may be specified on the command line +or in the option database +to configure aspects of the toplevel such as its background color +and relief. The \fBtoplevel\fR command returns the +path name of the new window. +.PP +A toplevel is similar to a frame except that it is created as a +top-level window: its X parent is the root window of a screen +rather than the logical parent from its path name. The primary +purpose of a toplevel is to serve as a container for dialog boxes +and other collections of widgets. The only visible features +of a toplevel are its background color and an optional 3-D border +to make the toplevel appear raised or sunken. + +.SH "WIDGET COMMAND" +.PP +The \fBtoplevel\fR command creates a new Tcl command whose +name is the same as the path name of the toplevel's window. This +command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIPathName\fR is the name of the command, which is the same as +the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. The following +commands are possible for toplevel widgets: +.TP +\fIpathName \fBcget\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 \fBtoplevel\fR +command. +.TP +\fIpathName \fBconfigure\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 describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). 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 \fBtoplevel\fR +command. + +.SH BINDINGS +.PP +When a new toplevel is created, it has no default event bindings: +toplevels are not intended to be interactive. + +.SH KEYWORDS +toplevel, widget diff --git a/doc/winfo.n b/doc/winfo.n new file mode 100644 index 0000000..d96e9b9 --- /dev/null +++ b/doc/winfo.n @@ -0,0 +1,330 @@ +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) winfo.n 1.45 97/01/25 13:45:04 +'\" +.so man.macros +.TH winfo n 4.3 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +winfo \- Return window-related information +.SH SYNOPSIS +\fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBwinfo\fR command is used to retrieve information about windows +managed by Tk. It can take any of a number of different forms, +depending on the \fIoption\fR argument. The legal forms are: +.TP +\fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR +Returns a decimal string giving the integer identifier for the +atom whose name is \fIname\fR. If no atom exists with the name +\fIname\fR then a new one is created. +If the \fB\-displayof\fR option is given then the atom is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +.TP +\fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR +Returns the textual name for the atom whose integer identifier is +\fIid\fR. +If the \fB\-displayof\fR option is given then the identifier is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +This command is the inverse of the \fBwinfo atom\fR command. +It generates an error if no such atom exists. +.TP +\fBwinfo cells \fIwindow\fR +Returns a decimal string giving the number of cells in the +color map for \fIwindow\fR. +.TP +\fBwinfo children \fIwindow\fR +Returns a list containing the path names of all the children +of \fIwindow\fR. The list is in stacking order, with the lowest +window first. Top-level windows are returned as children +of their logical parents. +.TP +\fBwinfo class \fIwindow\fR +Returns the class name for \fIwindow\fR. +.TP +\fBwinfo colormapfull \fIwindow\fR +Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 +otherwise. The colormap for a window is ``known'' to be full if the last +attempt to allocate a new color on that window failed and this +application hasn't freed any colors in the colormap since the +failed allocation. +.TP +\fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR +Returns the path name for the window containing the point given +by \fIrootX\fR and \fIrootY\fR. +\fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. +any form acceptable to \fBTk_GetPixels\fR) in the coordinate +system of the root window (if a virtual-root window manager is in +use then the coordinate system of the virtual root window is used). +If the \fB\-displayof\fR option is given then the coordinates refer +to the screen containing \fIwindow\fR; otherwise they refer to the +screen of the application's main window. +If no window in this application contains the point then an empty +string is returned. +In selecting the containing window, children are given higher priority +than parents and among siblings the highest one in the stacking order is +chosen. +.TP +\fBwinfo depth \fIwindow\fR +Returns a decimal string giving the depth of \fIwindow\fR (number +of bits per pixel). +.TP +\fBwinfo exists \fIwindow\fR +Returns 1 if there exists a window named \fIwindow\fR, 0 if no such +window exists. +.TP +\fBwinfo fpixels \fIwindow\fR \fInumber\fR +Returns a floating-point value giving the number of pixels +in \fIwindow\fR corresponding to the distance given by \fInumber\fR. +\fINumber\fR may be specified in any of the forms acceptable +to \fBTk_GetScreenMM\fR, such as ``2.0c'' or ``1i''. +The return value may be fractional; for an integer value, use +\fBwinfo pixels\fR. +.TP +\fBwinfo geometry \fIwindow\fR +Returns the geometry for \fIwindow\fR, in the form +\fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are +in pixels. +.TP +\fBwinfo height \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's height in pixels. +When a window is first created its height will be 1 pixel; the +height will eventually be changed by a geometry manager to fulfill +the window's needs. +If you need the true height immediately after creating a widget, +invoke \fBupdate\fR to force the geometry manager to arrange it, +or use \fBwinfo reqheight\fR to get the window's requested height +instead of its actual height. +.TP +\fBwinfo id \fIwindow\fR +.VS +Returns a hexadecimal string giving a low-level platform-specific +identifier for \fIwindow\fR. On Unix platforms, this is the X +window identifier. Under Windows, this is the Windows +HWND. On the Macintosh the value has no meaning outside Tk. +.VE +.TP +\fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? +Returns a list whose members are the names of all Tcl interpreters +(e.g. all Tk-based applications) currently registered for a particular display. +If the \fB\-displayof\fR option is given then the return value refers +to the display of \fIwindow\fR; otherwise it refers to +the display of the application's main window. +.TP +\fBwinfo ismapped \fIwindow\fR +Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. +.TP +\fBwinfo manager \fIwindow\fR +Returns the name of the geometry manager currently +responsible for \fIwindow\fR, or an empty string if \fIwindow\fR +isn't managed by any geometry manager. +The name is usually the name of the Tcl command for the geometry +manager, such as \fBpack\fR or \fBplace\fR. +If the geometry manager is a widget, such as canvases or text, the +name is the widget's class command, such as \fBcanvas\fR. +.TP +\fBwinfo name \fIwindow\fR +Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed +to its full path name). +The command \fBwinfo name .\fR will return the name of the application. +.TP +\fBwinfo parent \fIwindow\fR +Returns the path name of \fIwindow\fR's parent, or an empty string +if \fIwindow\fR is the main window of the application. +.TP +\fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR +Returns the path name of the window whose X identifier is \fIid\fR. +\fIId\fR must be a decimal, hexadecimal, or octal integer and must +correspond to a window in the invoking application. +If the \fB\-displayof\fR option is given then the identifier is looked +up on the display of \fIwindow\fR; otherwise it is looked up on +the display of the application's main window. +.TP +\fBwinfo pixels \fIwindow\fR \fInumber\fR +Returns the number of pixels in \fIwindow\fR corresponding +to the distance given by \fInumber\fR. +\fINumber\fR may be specified in any of the forms acceptable +to \fBTk_GetPixels\fR, such as ``2.0c'' or ``1i''. +The result is rounded to the nearest integer value; for a +fractional result, use \fBwinfo fpixels\fR. +.TP +\fBwinfo pointerx \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, returns the +pointer's x coordinate, measured in pixels in the screen's root window. +If a virtual root window is in use on the screen, the position is +measured in the virtual root. +If the mouse pointer isn't on the same screen as \fIwindow\fR then +-1 is returned. +.TP +\fBwinfo pointerxy \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, returns a list +with two elements, which are the pointer's x and y coordinates measured +in pixels in the screen's root window. +If a virtual root window is in use on the screen, the position +is computed in the virtual root. +If the mouse pointer isn't on the same screen as \fIwindow\fR then +both of the returned coordinates are -1. +.TP +\fBwinfo pointery \fIwindow\fR +If the mouse pointer is on the same screen as \fIwindow\fR, returns the +pointer's y coordinate, measured in pixels in the screen's root window. +If a virtual root window is in use on the screen, the position +is computed in the virtual root. +If the mouse pointer isn't on the same screen as \fIwindow\fR then +-1 is returned. +.TP +\fBwinfo reqheight \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's requested height, +in pixels. This is the value used by \fIwindow\fR's geometry +manager to compute its geometry. +.TP +\fBwinfo reqwidth \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's requested width, +in pixels. This is the value used by \fIwindow\fR's geometry +manager to compute its geometry. +.TP +\fBwinfo rgb \fIwindow color\fR +Returns a list containing three decimal values, which are the +red, green, and blue intensities that correspond to \fIcolor\fR in +the window given by \fIwindow\fR. \fIColor\fR +may be specified in any of the forms acceptable for a color +option. +.TP +\fBwinfo rootx \fIwindow\fR +Returns a decimal string giving the x-coordinate, in the root +window of the screen, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo rooty \fIwindow\fR +Returns a decimal string giving the y-coordinate, in the root +window of the screen, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo screen \fIwindow\fR +Returns the name of the screen associated with \fIwindow\fR, in +the form \fIdisplayName\fR.\fIscreenIndex\fR. +.TP +\fBwinfo screencells \fIwindow\fR +Returns a decimal string giving the number of cells in the default +color map for \fIwindow\fR's screen. +.TP +\fBwinfo screendepth \fIwindow\fR +Returns a decimal string giving the depth of the root window +of \fIwindow\fR's screen (number of bits per pixel). +.TP +\fBwinfo screenheight \fIwindow\fR +Returns a decimal string giving the height of \fIwindow\fR's screen, +in pixels. +.TP +\fBwinfo screenmmheight \fIwindow\fR +Returns a decimal string giving the height of \fIwindow\fR's screen, +in millimeters. +.TP +\fBwinfo screenmmwidth \fIwindow\fR +Returns a decimal string giving the width of \fIwindow\fR's screen, +in millimeters. +.TP +\fBwinfo screenvisual \fIwindow\fR +Returns one of the following strings to indicate the default visual +class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, +\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or +\fBtruecolor\fR. +.TP +\fBwinfo screenwidth \fIwindow\fR +Returns a decimal string giving the width of \fIwindow\fR's screen, +in pixels. +.TP +\fBwinfo server \fIwindow\fR +Returns a string containing information about the server for +\fIwindow\fR's display. The exact format of this string may vary +from platform to platform. For X servers the string +has the form ``\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR'' +where \fImajor\fR and \fIminor\fR are the version and revision +numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR +is the name of the vendor for the server, and \fIvendorRelease\fR +is an integer release number provided by the server. +.TP +\fBwinfo toplevel \fIwindow\fR +Returns the path name of the top-level window containing \fIwindow\fR. +.TP +\fBwinfo viewable \fIwindow\fR +Returns 1 if \fIwindow\fR and all of its ancestors up through the +nearest toplevel window are mapped. Returns 0 if any of these +windows are not mapped. +.TP +\fBwinfo visual \fIwindow\fR +Returns one of the following strings to indicate the visual +class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, +\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or +\fBtruecolor\fR. +.TP +\fBwinfo visualid \fIwindow\fR +Returns the X identifier for the visual for \fIwindow\fR. +.TP +\fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? +Returns a list whose elements describe the visuals available for +\fIwindow\fR's screen. +Each element consists of a visual class followed by an integer depth. +The class has the same form as returned by \fBwinfo visual\fR. +The depth gives the number of bits per pixel in the visual. +In addition, if the \fBincludeids\fR argument is provided, then the +depth is followed by the X identifier for the visual. +.TP +\fBwinfo vrootheight \fIwindow\fR +Returns the height of the virtual root window associated with \fIwindow\fR +if there is one; otherwise returns the height of \fIwindow\fR's screen. +.TP +\fBwinfo vrootwidth \fIwindow\fR +Returns the width of the virtual root window associated with \fIwindow\fR +if there is one; otherwise returns the width of \fIwindow\fR's screen. +.TP +\fBwinfo vrootx \fIwindow\fR +Returns the x-offset of the virtual root window associated with \fIwindow\fR, +relative to the root window of its screen. +This is normally either zero or negative. +Returns 0 if there is no virtual root window for \fIwindow\fR. +.TP +\fBwinfo vrooty \fIwindow\fR +Returns the y-offset of the virtual root window associated with \fIwindow\fR, +relative to the root window of its screen. +This is normally either zero or negative. +Returns 0 if there is no virtual root window for \fIwindow\fR. +.TP +\fBwinfo width \fIwindow\fR +Returns a decimal string giving \fIwindow\fR's width in pixels. +When a window is first created its width will be 1 pixel; the +width will eventually be changed by a geometry manager to fulfill +the window's needs. +If you need the true width immediately after creating a widget, +invoke \fBupdate\fR to force the geometry manager to arrange it, +or use \fBwinfo reqwidth\fR to get the window's requested width +instead of its actual width. +.TP +\fBwinfo x \fIwindow\fR +Returns a decimal string giving the x-coordinate, in \fIwindow\fR's +parent, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). +.TP +\fBwinfo y \fIwindow\fR +Returns a decimal string giving the y-coordinate, in \fIwindow\fR's +parent, of the +upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it +has no border). + +.SH KEYWORDS +atom, children, class, geometry, height, identifier, information, interpreters, +mapped, parent, path name, screen, virtual root, width, window diff --git a/doc/wish.1 b/doc/wish.1 new file mode 100644 index 0000000..8ee5368 --- /dev/null +++ b/doc/wish.1 @@ -0,0 +1,186 @@ +'\" +'\" Copyright (c) 1991-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) wish.1 1.30 97/10/31 12:58:43 +'\" +.so man.macros +.TH wish 1 8.0 Tk "Tk Applications" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +wish \- Simple windowing shell +.SH SYNOPSIS +\fBwish\fR ?\fIfileName arg arg ...\fR? +.SH OPTIONS +.IP "\fB\-colormap \fInew\fR" 20 +Specifies that the window should have a new private colormap instead of +using the default colormap for the screen. +.IP "\fB\-display \fIdisplay\fR" 20 +Display (and screen) on which to display window. +.IP "\fB\-geometry \fIgeometry\fR" 20 +Initial geometry to use for window. If this option is specified, its +value is stored in the \fBgeometry\fR global variable of the application's +Tcl interpreter. +.IP "\fB\-name \fIname\fR" 20 +Use \fIname\fR as the title to be displayed in the window, and +as the name of the interpreter for \fBsend\fR commands. +.IP "\fB\-sync\fR" 20 +Execute all X server commands synchronously, so that errors +are reported immediately. This will result in much slower +execution, but it is useful for debugging. +.VS 8.0 br +.IP "\fB\-use\fR \fIid\fR" 20 +Specifies that the main window for the application is to be embedded in +the window whose identifier is \fIid\fR, instead of being created as an +independent toplevel window. \fIId\fR must be specified in the same +way as the value for the \fB\-use\fR option for toplevel widgets (i.e. +it has a form like that returned by the \fBwinfo id\fR command). +.VE +.IP "\fB\-visual \fIvisual\fR" 20 +Specifies the visual to use for the window. +\fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR +procedure. +.IP "\fB\-\|\-\fR" 20 +Pass all remaining arguments through to the script's \fBargv\fR +variable without interpreting them. +This provides a mechanism for passing arguments such as \fB\-name\fR +to a script instead of having \fBwish\fR interpret them. +.BE + +.SH DESCRIPTION +.PP +\fBWish\fR is a simple program consisting of the Tcl command +language, the Tk toolkit, and a main program that reads commands +from standard input or from a file. +It creates a main window and then processes Tcl commands. +If \fBwish\fR is invoked with no arguments, or with a first argument +that starts with ``\-'', then it reads Tcl commands interactively from +standard input. +It will continue processing commands until all windows have been +deleted or until end-of-file is reached on standard input. +If there exists a file \fB.wishrc\fR in the home directory of +the user, \fBwish\fR evaluates the file as a Tcl script +just before reading the first command from standard input. +.PP +If \fBwish\fR is invoked with an initial \fIfileName\fR argument, then +\fIfileName\fR is treated as the name of a script file. +\fBWish\fR will evaluate the script in \fIfileName\fR (which +presumably creates a user interface), then it will respond to events +until all windows have been deleted. +Commands will not be read from standard input. +There is no automatic evaluation of \fB.wishrc\fR in this +case, but the script file can always \fBsource\fR it if desired. + +.SH "OPTIONS" +.PP +\fBWish\fR automatically processes all of the command-line options +described in the \fBOPTIONS\fR summary above. +Any other command-line arguments besides these are passed through +to the application using the \fBargc\fR and \fBargv\fR variables +described later. + +.SH "APPLICATION NAME AND CLASS" +.PP +The name of the application, which is used for purposes such as +\fBsend\fR commands, is taken from the \fB\-name\fR option, +if it is specified; otherwise it is taken from \fIfileName\fR, +if it is specified, or from the command name by which +\fBwish\fR was invoked. In the last two cases, if the name contains a ``/'' +character, then only the characters after the last slash are used +as the application name. +.PP +The class of the application, which is used for purposes such as +specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults +file, is the same as its name except that the first letter is +capitalized. + +.SH "VARIABLES" +.PP +\fBWish\fR sets the following Tcl variables: +.TP 15 +\fBargc\fR +Contains a count of the number of \fIarg\fR arguments (0 if none), +not including the options described above. +.TP 15 +\fBargv\fR +Contains a Tcl list whose elements are the \fIarg\fR arguments +that follow a \fB\-\|\-\fR option or don't match any of the +options described in OPTIONS above, in order, or an empty string +if there are no such arguments. +.TP 15 +\fBargv0\fR +Contains \fIfileName\fR if it was specified. +Otherwise, contains the name by which \fBwish\fR was invoked. +.TP 15 +\fBgeometry\fR +If the \fB\-geometry\fR option is specified, \fBwish\fR copies its +value into this variable. If the variable still exists after +\fIfileName\fR has been evaluated, \fBwish\fR uses the value of +the variable in a \fBwm geometry\fR command to set the main +window's geometry. +.TP 15 +\fBtcl_interactive\fR +Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR +was not specified and standard input is a terminal-like +device), 0 otherwise. + +.SH "SCRIPT FILES" +.PP +If you create a Tcl script in a file whose first line is +.CS +\fB#!/usr/local/bin/wish\fR +.CE +then you can invoke the script file directly from your shell if +you mark it as executable. +This assumes that \fBwish\fR has been installed in the default +location in /usr/local/bin; if it's installed somewhere else +then you'll have to modify the above line to match. +Many UNIX systems do not allow the \fB#!\fR line to exceed about +30 characters in length, so be sure that the \fBwish\fR executable +can be accessed with a short file name. +.PP +An even better approach is to start your script files with the +following three lines: +.CS +\fB#!/bin/sh +# the next line restarts using wish \e +exec wish "$0" "$@"\fR +.CE +This approach has three advantages over the approach in the previous +paragraph. First, the location of the \fBwish\fR binary doesn't have +to be hard-wired into the script: it can be anywhere in your shell +search path. Second, it gets around the 30-character file name limit +in the previous approach. +Third, this approach will work even if \fBwish\fR is +itself a shell script (this is done on some systems in order to +handle multiple architectures or operating systems: the \fBwish\fR +script selects one of several binaries to run). The three lines +cause both \fBsh\fR and \fBwish\fR to process the script, but the +\fBexec\fR is only executed by \fBsh\fR. +\fBsh\fR processes the script first; it treats the second +line as a comment and executes the third line. +The \fBexec\fR statement cause the shell to stop processing and +instead to start up \fBwish\fR to reprocess the entire script. +When \fBwish\fR starts up, it treats all three lines as comments, +since the backslash at the end of the second line causes the third +line to be treated as part of the comment on the second line. + +.SH PROMPTS +.PP +When \fBwish\fR is invoked interactively it normally prompts for each +command with ``\fB% \fR''. You can change the prompt by setting the +variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable +\fBtcl_prompt1\fR exists then it must consist of a Tcl script +to output a prompt; instead of outputting a prompt \fBwish\fR +will evaluate the script in \fBtcl_prompt1\fR. +The variable \fBtcl_prompt2\fR is used in a similar way when +a newline is typed but the current command isn't yet complete; +if \fBtcl_prompt2\fR isn't set then no prompt is output for +incomplete commands. + +.SH KEYWORDS +shell, toolkit diff --git a/doc/wm.n b/doc/wm.n new file mode 100644 index 0000000..d1986b6 --- /dev/null +++ b/doc/wm.n @@ -0,0 +1,503 @@ +'\" +'\" Copyright (c) 1991-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) wm.n 1.37 96/10/14 11:07:58 +'\" +.so man.macros +.TH wm n 4.3 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +wm \- Communicate with window manager +.SH SYNOPSIS +\fBwm\fR \fIoption window \fR?\fIargs\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBwm\fR command is used to interact with window managers in +order to control such things as the title for a window, its geometry, +or the increments in terms of which it may be resized. The \fBwm\fR +command can take any of a number of different forms, depending on +the \fIoption\fR argument. All of the forms expect at least one +additional argument, \fIwindow\fR, which must be the path name of a +top-level window. +.PP +The legal forms for the \fBwm\fR command are: +.TP +\fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? +If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR +are all specified, then they will be passed to the window manager +and the window manager should use them to enforce a range of +acceptable aspect ratios for \fIwindow\fR. The aspect ratio of +\fIwindow\fR (width/length) will be constrained to lie +between \fIminNumer\fR/\fIminDenom\fR and \fImaxNumer\fR/\fImaxDenom\fR. +If \fIminNumer\fR etc. are all specified as empty strings, then +any existing aspect ratio restrictions are removed. +If \fIminNumer\fR etc. are specified, then the command returns an +empty string. Otherwise, it returns +a Tcl list containing four elements, which are the current values +of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR +(if no aspect restrictions are in effect, then an empty string is +returned). +.TP +\fBwm client \fIwindow\fR ?\fIname\fR? +If \fIname\fR is specified, this command stores \fIname\fR (which +should be the name of +the host on which the application is executing) in \fIwindow\fR's +\fBWM_CLIENT_MACHINE\fR property for use by the window manager or +session manager. +The command returns an empty string in this case. +If \fIname\fR isn't specified, the command returns the last name +set in a \fBwm client\fR command for \fIwindow\fR. +If \fIname\fR is specified as an empty string, the command deletes the +\fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. +.TP +\fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? +This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR +property, which provides information to the window managers about +windows that have private colormaps. +If \fIwindowList\fR isn't specified, the command returns a list +whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR +property. +If \fIwindowList\fR is specified, it consists of a list of window +path names; the command overwrites the \fBWM_COLORMAP_WINDOWS\fR +property with the given windows and returns an empty string. +The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a +list of the internal windows within \fIwindow\fR whose colormaps differ +from their parents. +The order of the windows in the property indicates a priority order: +the window manager will attempt to install as many colormaps as possible +from the head of this list when \fIwindow\fR gets the colormap focus. +If \fIwindow\fR is not included among the windows in \fIwindowList\fR, +Tk implicitly adds it at the end of the \fBWM_COLORMAP_WINDOWS\fR +property, so that its colormap is lowest in priority. +If \fBwm colormapwindows\fR is not invoked, Tk will automatically set +the property for each top-level window to all the internal windows +whose colormaps differ from their parents, followed by the top-level +itself; the order of the internal windows is undefined. +See the ICCCM documentation for more information on the +\fBWM_COLORMAP_WINDOWS\fR property. +.TP +\fBwm command \fIwindow\fR ?\fIvalue\fR? +If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's +\fBWM_COMMAND\fR property for use by the window manager or +session manager and returns an empty string. +\fIValue\fR must have proper list structure; the elements should +contain the words of the command used to invoke the application. +If \fIvalue\fR isn't specified then the command returns the last value +set in a \fBwm command\fR command for \fIwindow\fR. +If \fIvalue\fR is specified as an empty string, the command +deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. +.TP +\fBwm deiconify \fIwindow\fR +Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. +This is done by mapping the window. If the window has never been +mapped then this command will not map the window, but it will ensure +that when the window is first mapped it will be displayed +in de-iconified form. Returns an empty string. +.TP +\fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? +If \fBactive\fR or \fBpassive\fR is supplied as an optional argument +to the command, then it specifies the focus model for \fIwindow\fR. +In this case the command returns an empty string. If no additional +argument is supplied, then the command returns the current focus +model for \fIwindow\fR. +An \fBactive\fR focus model means that \fIwindow\fR will claim the +input focus for itself or its descendants, even at times when +the focus is currently in some other application. \fBPassive\fR means that +\fIwindow\fR will never claim the focus for itself: the window manager +should give the focus to \fIwindow\fR at appropriate times. However, +once the focus has been given to \fIwindow\fR or one of its descendants, +the application may re-assign the focus among \fIwindow\fR's descendants. +The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command +assumes a passive model of focusing. +.TP +\fBwm frame \fIwindow\fR +.VS +If \fIwindow\fR has been reparented by the window manager into a +decorative frame, the command returns the platform specific window +identifier for the outermost frame that contains \fIwindow\fR (the +window whose parent is the root or virtual root). If \fIwindow\fR +hasn't been reparented by the window manager then the command returns +the platform specific window identifier for \fIwindow\fR. +.VE +.TP +\fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? +If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR +is changed and an empty string is returned. Otherwise the current +geometry for \fIwindow\fR is returned (this is the most recent +geometry specified either by manual resizing or +in a \fBwm geometry\fR command). \fINewGeometry\fR has +the form \fB=\fIwidth\fBx\fIheight\fB\(+-\fIx\fB\(+-\fIy\fR, where +any of \fB=\fR, \fIwidth\fBx\fIheight\fR, or \fB\(+-\fIx\fB\(+-\fIy\fR +may be omitted. \fIWidth\fR and \fIheight\fR are positive integers +specifying the desired dimensions of \fIwindow\fR. If \fIwindow\fR +is gridded (see GRIDDED GEOMETRY MANAGEMENT below) then the dimensions +are specified in grid units; otherwise they are specified in pixel +units. \fIX\fR and \fIy\fR specify the desired location of +\fIwindow\fR on the screen, in pixels. +If \fIx\fR is preceded by \fB+\fR, it specifies +the number of pixels between the left edge of the screen and the left +edge of \fIwindow\fR's border; if preceded by \fB\-\fR then +\fIx\fR specifies the number of pixels +between the right edge of the screen and the right edge of \fIwindow\fR's +border. If \fIy\fR is preceded by \fB+\fR then it specifies the +number of pixels between the top of the screen and the top +of \fIwindow\fR's border; if \fIy\fR is preceded by \fB\-\fR then +it specifies the number of pixels between the bottom of \fIwindow\fR's +border and the bottom of the screen. +If \fInewGeometry\fR is specified as an empty string then any +existing user-specified geometry for \fIwindow\fR is cancelled, and +the window will revert to the size requested internally by its +widgets. +.TP +\fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? +This command indicates that \fIwindow\fR is to be managed as a +gridded window. +It also specifies the relationship between grid units and pixel units. +\fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid +units corresponding to the pixel dimensions requested internally +by \fIwindow\fR using \fBTk_GeometryRequest\fR. \fIWidthInc\fR +and \fIheightInc\fR specify the number of pixels in each horizontal +and vertical grid unit. +These four values determine a range of acceptable sizes for +\fIwindow\fR, corresponding to grid-based widths and heights +that are non-negative integers. +Tk will pass this information to the window manager; during +manual resizing, the window manager will restrict the window's size +to one of these acceptable sizes. +Furthermore, during manual resizing the window manager will display +the window's current size in terms of grid units rather than pixels. +If \fIbaseWidth\fR etc. are all specified as empty strings, then +\fIwindow\fR will no longer be managed as a gridded window. If +\fIbaseWidth\fR etc. are specified then the return value is an +empty string. +Otherwise the return value is a Tcl list containing +four elements corresponding to the current \fIbaseWidth\fR, +\fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if +\fIwindow\fR is not currently gridded, then an empty string +is returned. +Note: this command should not be needed very often, since the +\fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option +provide easier access to the same functionality. +.TP +\fBwm group \fIwindow\fR ?\fIpathName\fR? +If \fIpathName\fR is specified, it gives the path name for the leader of +a group of related windows. The window manager may use this information, +for example, to unmap all of the windows in a group when the group's +leader is iconified. \fIPathName\fR may be specified as an empty string to +remove \fIwindow\fR from any group association. If \fIpathName\fR is +specified then the command returns an empty string; otherwise it +returns the path name of \fIwindow\fR's current group leader, or an empty +string if \fIwindow\fR isn't part of any group. +.TP +\fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? +If \fIbitmap\fR is specified, then it names a bitmap in the standard +forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). +This bitmap is passed to the window manager to be displayed in +\fIwindow\fR's icon, and the command returns an empty string. If +an empty string is specified for \fIbitmap\fR, then any current icon +bitmap is cancelled for \fIwindow\fR. +If \fIbitmap\fR is specified then the command returns an empty string. +Otherwise it returns the name of +the current icon bitmap associated with \fIwindow\fR, or an empty +string if \fIwindow\fR has no icon bitmap. +.TP +\fBwm iconify \fIwindow\fR +Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR hasn't +yet been mapped for the first time, this command will arrange for +it to appear in the iconified state when it is eventually mapped. +.TP +\fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? +If \fIbitmap\fR is specified, then it names a bitmap in the standard +forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). +This bitmap is passed to the window manager to be used as a mask +in conjunction with the \fBiconbitmap\fR option: where the mask +has zeroes no icon will be displayed; where it has ones, the bits +from the icon bitmap will be displayed. If +an empty string is specified for \fIbitmap\fR then any current icon +mask is cancelled for \fIwindow\fR (this is equivalent to specifying +a bitmap of all ones). If \fIbitmap\fR is specified +then the command returns an empty string. Otherwise it +returns the name of the current icon mask associated with +\fIwindow\fR, or an empty string if no mask is in effect. +.TP +\fBwm iconname \fIwindow\fR ?\fInewName\fR? +If \fInewName\fR is specified, then it is passed to the window +manager; the window manager should display \fInewName\fR inside +the icon associated with \fIwindow\fR. In this case an empty +string is returned as result. If \fInewName\fR isn't specified +then the command returns the current icon name for \fIwindow\fR, +or an empty string if no icon name has been specified (in this +case the window manager will normally display the window's title, +as specified with the \fBwm title\fR command). +.TP +\fBwm iconposition \fIwindow\fR ?\fIx y\fR? +If \fIx\fR and \fIy\fR are specified, they are passed to the window +manager as a hint about where to position the icon for \fIwindow\fR. +In this case an empty string is returned. If \fIx\fR and \fIy\fR are +specified as empty strings then any existing icon position hint is cancelled. +If neither \fIx\fR nor \fIy\fR is specified, then the command returns +a Tcl list containing two values, which are the current icon position +hints (if no hints are in effect then an empty string is returned). +.TP +\fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? +If \fIpathName\fR is specified, it is the path name for a window to +use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then +\fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR +is de-iconified then \fIpathName\fR will be unmapped again. If +\fIpathName\fR is specified as an empty string then any existing +icon window association for \fIwindow\fR will be cancelled. If +the \fIpathName\fR argument is specified then an empty string is +returned. Otherwise the command returns the path name of the +current icon window for \fIwindow\fR, or an empty string if there +is no icon window currently specified for \fIwindow\fR. +Button press events are disabled for \fIwindow\fR as long as it is +an icon window; this is needed in order to allow window managers +to ``own'' those events. +Note: not all window managers support the notion of an icon window. +.TP +\fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? +If \fIwidth\fR and \fIheight\fR are specified, they give +the maximum permissible dimensions for \fIwindow\fR. +For gridded windows the dimensions are specified in +grid units; otherwise they are specified in pixel units. +The window manager will restrict the window's dimensions to be +less than or equal to \fIwidth\fR and \fIheight\fR. +If \fIwidth\fR and \fIheight\fR are +specified, then the command returns an empty string. Otherwise +it returns a Tcl list with two elements, which are the +maximum width and height currently in effect. +The maximum size defaults to the size of the screen. +If resizing has been disabled with the \fBwm resizable\fR command, +then this command has no effect. +See the sections on geometry management below for more information. +.TP +\fBwm minsize \fIwindow\fR ?\fIwidth height\fR? +If \fIwidth\fR and \fIheight\fR are specified, they give the +minimum permissible dimensions for \fIwindow\fR. +For gridded windows the dimensions are specified in +grid units; otherwise they are specified in pixel units. +The window manager will restrict the window's dimensions to be +greater than or equal to \fIwidth\fR and \fIheight\fR. +If \fIwidth\fR and \fIheight\fR are +specified, then the command returns an empty string. Otherwise +it returns a Tcl list with two elements, which are the +minimum width and height currently in effect. +The minimum size defaults to one pixel in each dimension. +If resizing has been disabled with the \fBwm resizable\fR command, +then this command has no effect. +See the sections on geometry management below for more information. +.TP +\fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? +If \fIboolean\fR is specified, it must have a proper boolean form and +the override-redirect flag for \fIwindow\fR is set to that value. +If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is +returned to indicate whether or not the override-redirect flag +is currently set for \fIwindow\fR. +Setting the override-redirect flag for a window causes +it to be ignored by the window manager; among other things, this means +that the window will not be reparented from the root window into a +decorative frame and the user will not be able to manipulate the +window using the normal window manager mechanisms. +.TP +\fBwm positionfrom \fIwindow\fR ?\fIwho\fR? +If \fIwho\fR is specified, it must be either \fBprogram\fR or +\fBuser\fR, or an abbreviation of one of these two. It indicates +whether \fIwindow\fR's current position was requested by the +program or by the user. Many window managers ignore program-requested +initial positions and ask the user to manually position the window; if +\fBuser\fR is specified then the window manager should position the +window at the given place without asking the user for assistance. +If \fIwho\fR is specified as an empty string, then the current position +source is cancelled. +If \fIwho\fR is specified, then the command returns an empty string. +Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the +source of the window's current position, or an empty string if +no source has been specified yet. Most window managers interpret +``no source'' as equivalent to \fBprogram\fR. +Tk will automatically set the position source to \fBuser\fR +when a \fBwm geometry\fR command is invoked, unless the source has +been set explicitly to \fBprogram\fR. +.TP +\fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? +This command is used to manage window manager protocols such as +\fBWM_DELETE_WINDOW\fR. +\fIName\fR is the name of an atom corresponding to a window manager +protocol, such as \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR +or \fBWM_TAKE_FOCUS\fR. +If both \fIname\fR and \fIcommand\fR are specified, then \fIcommand\fR +is associated with the protocol specified by \fIname\fR. +\fIName\fR will be added to \fIwindow\fR's \fBWM_PROTOCOLS\fR +property to tell the window manager that the application has a +protocol handler for \fIname\fR, and \fIcommand\fR will +be invoked in the future whenever the window manager sends a +message to the client for that protocol. +In this case the command returns an empty string. +If \fIname\fR is specified but \fIcommand\fR isn't, then the current +command for \fIname\fR is returned, or an empty string if there +is no handler defined for \fIname\fR. +If \fIcommand\fR is specified as an empty string then the current +handler for \fIname\fR is deleted and it is removed from the +\fBWM_PROTOCOLS\fR property on \fIwindow\fR; an empty string is +returned. +Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the +command returns a list of all the protocols for which handlers +are currently defined for \fIwindow\fR. +.RS +.PP +Tk always defines a protocol handler for \fBWM_DELETE_WINDOW\fR, even if +you haven't asked for one with \fBwm protocol\fR. +If a \fBWM_DELETE_WINDOW\fR message arrives when you haven't defined +a handler, then Tk handles the message by destroying the window for +which it was received. +.RE +.TP +\fBwm resizable \fIwindow\fR ?\fIwidth height\fR? +This command controls whether or not the user may interactively +resize a top-level window. If \fIwidth\fR and \fIheight\fR are +specified, they are boolean values that determine whether the +width and height of \fIwindow\fR may be modified by the user. +In this case the command returns an empty string. +If \fIwidth\fR and \fIheight\fR are omitted then the command +returns a list with two 0/1 elements that indicate whether the +width and height of \fIwindow\fR are currently resizable. +By default, windows are resizable in both dimensions. +If resizing is disabled, then the window's size will be the size +from the most recent interactive resize or \fBwm geometry\fR +command. If there has been no such operation then +the window's natural size will be used. +.TP +\fBwm sizefrom \fIwindow\fR ?\fIwho\fR? +If \fIwho\fR is specified, it must be either \fBprogram\fR or +\fBuser\fR, or an abbreviation of one of these two. It indicates +whether \fIwindow\fR's current size was requested by the +program or by the user. Some window managers ignore program-requested +sizes and ask the user to manually size the window; if +\fBuser\fR is specified then the window manager should give the +window its specified size without asking the user for assistance. +If \fIwho\fR is specified as an empty string, then the current size +source is cancelled. +If \fIwho\fR is specified, then the command returns an empty string. +Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the +source of the window's current size, or an empty string if +no source has been specified yet. Most window managers interpret +``no source'' as equivalent to \fBprogram\fR. +.TP +\fBwm state \fIwindow\fR +Returns the current state of \fIwindow\fR: either \fBnormal\fR, +\fBiconic\fR, \fBwithdrawn\fR, or \fBicon\fR. The difference +between \fBiconic\fR and \fBicon\fR is that \fBiconic\fR refers +to a window that has been iconified (e.g., with the \fBwm iconify\fR +command) while \fBicon\fR refers to a window whose only purpose is +to serve as the icon for some other window (via the \fBwm iconwindow\fR +command). +.TP +\fBwm title \fIwindow\fR ?\fIstring\fR? +If \fIstring\fR is specified, then it will be passed to the window +manager for use as the title for \fIwindow\fR (the window manager +should display this string in \fIwindow\fR's title bar). In this +case the command returns an empty string. If \fIstring\fR isn't +specified then the command returns the current title for the +\fIwindow\fR. The title for a window defaults to its name. +.TP +\fBwm transient \fIwindow\fR ?\fImaster\fR? +If \fImaster\fR is specified, then the window manager is informed +that \fIwindow\fR is a transient window (e.g. pull-down menu) working +on behalf of \fImaster\fR (where \fImaster\fR is the +path name for a top-level window). Some window managers will use +this information to manage \fIwindow\fR specially. If \fImaster\fR +is specified as an empty string then \fIwindow\fR is marked as not +being a transient window any more. If \fImaster\fR is specified, +then the command returns an empty string. Otherwise the command +returns the path name of \fIwindow\fR's current master, or an +empty string if \fIwindow\fR isn't currently a transient window. +.TP +\fBwm withdraw \fIwindow\fR +Arranges for \fIwindow\fR to be withdrawn from the screen. This +causes the window to be unmapped and forgotten about by the window +manager. If the window +has never been mapped, then this command +causes the window to be mapped in the withdrawn state. Not all +window managers appear to know how to handle windows that are +mapped in the withdrawn state. +Note: it sometimes seems to be necessary to withdraw a +window and then re-map it (e.g. with \fBwm deiconify\fR) to get some +window managers to pay attention to changes in window attributes +such as group. + +.SH "GEOMETRY MANAGEMENT" +.PP +By default a top-level window appears on the screen in its +\fInatural size\fR, which is the one determined internally by its +widgets and geometry managers. +If the natural size of a top-level window changes, then the window's size +changes to match. +A top-level window can be given a size other than its natural size in two ways. +First, the user can resize the window manually using the facilities +of the window manager, such as resize handles. +Second, the application can request a particular size for a +top-level window using the \fBwm geometry\fR command. +These two cases are handled identically by Tk; in either case, +the requested size overrides the natural size. +You can return the window to its natural by invoking \fBwm geometry\fR +with an empty \fIgeometry\fR string. +.PP +Normally a top-level window can have any size from one pixel in each +dimension up to the size of its screen. +However, you can use the \fBwm minsize\fR and \fBwm maxsize\fR commands +to limit the range of allowable sizes. +The range set by \fBwm minsize\fR and \fBwm maxsize\fR applies to +all forms of resizing, including the window's natural size as +well as manual resizes and the \fBwm geometry\fR command. +You can also use the command \fBwm resizable\fR to completely +disable interactive resizing in one or both dimensions. + +.SH "GRIDDED GEOMETRY MANAGEMENT" +.PP +Gridded geometry management occurs when one of the widgets of an +application supports a range of useful sizes. +This occurs, for example, in a text editor where the scrollbars, +menus, and other adornments are fixed in size but the edit widget +can support any number of lines of text or characters per line. +In this case, it is usually desirable to let the user specify the +number of lines or characters-per-line, either with the +\fBwm geometry\fR command or by interactively resizing the window. +In the case of text, and in other interesting cases also, only +discrete sizes of the window make sense, such as integral numbers +of lines and characters-per-line; arbitrary pixel sizes are not useful. +.PP +Gridded geometry management provides support for this kind of +application. +Tk (and the window manager) assume that there is a grid of some +sort within the application and that the application should be +resized in terms of \fIgrid units\fR rather than pixels. +Gridded geometry management is typically invoked by turning on +the \fBsetGrid\fR option for a widget; it can also be invoked +with the \fBwm grid\fR command or by calling \fBTk_SetGrid\fR. +In each of these approaches the particular widget (or sometimes +code in the application as a whole) specifies the relationship between +integral grid sizes for the window and pixel sizes. +To return to non-gridded geometry management, invoke +\fBwm grid\fR with empty argument strings. +.PP +When gridded geometry management is enabled then all the dimensions specified +in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands +are treated as grid units rather than pixel units. +Interactive resizing is also carried out in even numbers of grid units +rather than pixels. + +.SH BUGS +.PP +Most existing window managers appear to have bugs that affect the +operation of the \fBwm\fR command. For example, some changes won't +take effect if the window is already active: the window will have +to be withdrawn and de-iconified in order to make the change happen. + +.SH KEYWORDS +aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager diff --git a/license.terms b/license.terms new file mode 100644 index 0000000..03ca6fc --- /dev/null +++ b/license.terms @@ -0,0 +1,39 @@ +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. |
