summaryrefslogtreecommitdiffstats
path: root/tools/testfiles/tcompound.h5.xml
Commit message (Expand)AuthorAgeFilesLines
* [svn-r7542] Purpose:Quincey Koziol2003-10-051-165/+165
* [svn-r7329] Purpose:Quincey Koziol2003-08-081-16/+16
* [svn-r7276] Purpose:Robert E. McGrath2003-07-291-185/+224
* [svn-r4150] Bill Wendling2001-07-091-0/+8
* [svn-r3680] Purpose:Bill Wendling2001-03-211-121/+121
* [svn-r3506] Robert E. McGrath2001-02-231-121/+121
* [svn-r3485] Robert E. McGrath2001-02-221-2/+2
* [svn-r3408] Purpose:Robert E. McGrath2001-02-141-0/+280
generated by cgit v0.12 at 2025-01-26 06:42:20 (GMT)
: + 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 <> 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}; diff --git a/changes b/changes new file mode 100644 index 0000000..e01c4a8 --- /dev/null +++ b/changes @@ -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 {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 +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. was treated the same as ). Modified to +allow explicit request for shift modifier, like . + +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 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 . + +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 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 instead of . + +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 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 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 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 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 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 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 <>, <>, <>, +and <> 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 was +reported as , but 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., <> was defined as and +. 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 <>, <>, and <> +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 " +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 <> {script}" or +"$text tag bind sel <> {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 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 <> +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 / 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 <> 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 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, +<> 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 + +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 +#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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \fR +\fB#include \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 \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 \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 \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 \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 \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 \fR +\fB#include \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 + +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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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 . + +.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 \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 \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 \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 \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 \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 \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 \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 \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 \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 \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\fR will match +the event, but \fB\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\fR +is equivalent to \fB\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\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\fR is equivalent to +\fB\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 <> +event add <> +event add <> +bind Entry <> {puts Paste} +bind Entry <> {puts Scroll} +.CE +If the user types Control-y, the \fB<>\fR binding +will be invoked, but if the user presses button 2 then one of +either the \fB<>\fR or the \fB<>\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\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\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 preventi