From f110d4e2a4b45b23f037e22b18041093a18a028f Mon Sep 17 00:00:00 2001 From: stanton Date: Tue, 29 Sep 1998 00:25:04 +0000 Subject: initial tk8.1a2 version FossilOrigin-Name: 644396f2dabc649ad5784768cfe962017d991df1 --- README | 181 +-- changes | 141 ++- compat/stdlib.h | 4 +- doc/3DBorder.3 | 101 +- doc/ConfigWidg.3 | 5 +- doc/CrtWindow.3 | 2 +- doc/GetAnchor.3 | 50 +- doc/GetBitmap.3 | 122 +- doc/GetColor.3 | 154 ++- doc/GetCursor.3 | 135 +- doc/GetFont.3 | 110 +- doc/GetJustify.3 | 54 +- doc/GetPixels.3 | 71 +- doc/GetRelief.3 | 54 +- doc/SetOptions.3 | 502 ++++++++ doc/dde.n | 100 ++ doc/loadTk.n | 58 +- doc/send.n | 19 +- generic/prolog.ps | 284 +++++ generic/tk.h | 477 +++++-- generic/tk3d.c | 621 +++++++-- generic/tk3d.h | 33 +- generic/tkArgv.c | 18 +- generic/tkBind.c | 1183 +++++++++-------- generic/tkBitmap.c | 612 ++++++++- generic/tkButton.c | 1495 +++++++++++++--------- generic/tkButton.h | 243 ++-- generic/tkCanvArc.c | 19 +- generic/tkCanvBmap.c | 22 +- generic/tkCanvImg.c | 16 +- generic/tkCanvLine.c | 16 +- generic/tkCanvPoly.c | 13 +- generic/tkCanvPs.c | 456 +++++-- generic/tkCanvText.c | 399 +++--- generic/tkCanvUtil.c | 4 +- generic/tkCanvWind.c | 14 +- generic/tkCanvas.c | 87 +- generic/tkClipboard.c | 19 +- generic/tkCmds.c | 246 ++-- generic/tkColor.c | 514 +++++++- generic/tkColor.h | 29 +- generic/tkConfig.c | 2509 +++++++++++++++++++++++++----------- generic/tkConsole.c | 9 +- generic/tkCursor.c | 574 ++++++++- generic/tkEntry.c | 564 +++++---- generic/tkFileFilter.c | 3 +- generic/tkFocus.c | 147 ++- generic/tkFont.c | 1363 ++++++++++++++------ generic/tkFont.h | 76 +- generic/tkFrame.c | 8 +- generic/tkGet.c | 99 +- generic/tkGrab.c | 29 +- generic/tkGrid.c | 74 +- generic/tkImage.c | 24 +- generic/tkImgBmap.c | 19 +- generic/tkImgGIF.c | 20 +- generic/tkImgPPM.c | 10 +- generic/tkImgPhoto.c | 9 +- generic/tkInitScript.h | 12 +- generic/tkInt.h | 60 +- generic/tkListbox.c | 58 +- generic/tkMacWinMenu.c | 4 +- generic/tkMain.c | 43 +- generic/tkMenu.c | 2210 +++++++++++++++++++------------- generic/tkMenu.h | 171 +-- generic/tkMenuDraw.c | 233 ++-- generic/tkMenubutton.c | 6 +- generic/tkMessage.c | 8 +- generic/tkObj.c | 659 ++++++++++ generic/tkOldConfig.c | 996 +++++++++++++++ generic/tkOption.c | 29 +- generic/tkPack.c | 12 +- generic/tkPlace.c | 8 +- generic/tkRectOval.c | 23 +- generic/tkScale.c | 28 +- generic/tkScrollbar.c | 51 +- generic/tkSelect.c | 48 +- generic/tkSquare.c | 390 +++--- generic/tkTest.c | 1343 ++++++++++++++++++-- generic/tkText.c | 183 +-- generic/tkText.h | 48 +- generic/tkTextBTree.c | 59 +- generic/tkTextDisp.c | 438 +++---- generic/tkTextImage.c | 16 +- generic/tkTextIndex.c | 616 +++++++-- generic/tkTextMark.c | 18 +- generic/tkTextTag.c | 43 +- generic/tkTextWind.c | 20 +- generic/tkTrig.c | 6 +- generic/tkUtil.c | 77 +- generic/tkVisual.c | 11 +- generic/tkWindow.c | 235 +++- library/bgerror.tcl | 10 +- library/button.tcl | 6 +- library/clrpick.tcl | 90 +- library/comdlg.tcl | 49 +- library/console.tcl | 36 +- library/demos/style.tcl | 2 +- library/dialog.tcl | 21 +- library/entry.tcl | 66 +- library/focus.tcl | 8 +- library/images/logo.eps | 2091 ++++++++++++++++++++++++++++++ library/images/pwrdLogo.eps | 1897 ++++++++++++++++++++++++++++ library/images/pwrdLogo100.gif | Bin 0 -> 1615 bytes library/images/pwrdLogo150.gif | Bin 0 -> 2489 bytes library/images/pwrdLogo175.gif | Bin 0 -> 2981 bytes library/images/pwrdLogo200.gif | Bin 0 -> 3491 bytes library/images/pwrdLogo75.gif | Bin 0 -> 1171 bytes library/listbox.tcl | 16 +- library/menu.tcl | 70 +- library/msgbox.tcl | 47 +- library/optMenu.tcl | 4 +- library/palette.tcl | 48 +- library/safetk.tcl | 108 +- library/scale.tcl | 22 +- library/scrlbar.tcl | 36 +- library/tclIndex | 3 + library/tearoff.tcl | 34 +- library/text.tcl | 96 +- library/tk.tcl | 46 +- library/tkfbox.tcl | 282 +++-- library/xmfbox.tcl | 573 ++++++--- mac/MW_TkHeader.pch | 78 +- mac/README | 107 +- mac/bugs.doc | 8 +- mac/tkMac.h | 39 +- mac/tkMacAppInit.c | 6 +- mac/tkMacBitmap.c | 29 +- mac/tkMacButton.c | 428 +++++-- mac/tkMacClipboard.c | 4 +- mac/tkMacConfig.c | 45 + mac/tkMacCursor.c | 60 +- mac/tkMacDefault.h | 5 +- mac/tkMacDialog.c | 776 +++++------- mac/tkMacEmbed.c | 186 ++- mac/tkMacFont.c | 1984 +++++++++++++++++++++++++---- mac/tkMacHLEvents.c | 8 +- mac/tkMacInit.c | 4 +- mac/tkMacInt.h | 21 +- mac/tkMacKeyboard.c | 70 +- mac/tkMacLibrary.r | 4 +- mac/tkMacMenu.c | 546 +++++--- mac/tkMacPort.h | 5 +- mac/tkMacProjects.sit.hqx | 800 ++++++++++++ mac/tkMacResource.r | 24 +- mac/tkMacSend.c | 330 ++++- mac/tkMacShLib.exp | 2 - mac/tkMacSubwindows.c | 130 +- mac/tkMacTest.c | 3 +- mac/tkMacWindowMgr.c | 126 +- mac/tkMacWm.c | 222 ++-- mac/tkMacXStubs.c | 7 +- tests/all | 23 +- tests/bind.test | 96 +- tests/bitmap.test | 99 ++ tests/border.test | 176 +++ tests/button.test | 371 +++--- tests/canvText.test | 4 +- tests/canvas.test | 15 +- tests/clrpick.test | 8 +- tests/color.test | 129 +- tests/config.test | 823 ++++++++++++ tests/cursor.test | 99 ++ tests/defs | 28 +- tests/entry.test | 291 +++-- tests/filebox.test | 7 +- tests/font.test | 847 ++++++++----- tests/get.test | 81 ++ tests/macFont.test | 180 ++- tests/menu.test | 438 ++++--- tests/menuDraw.test | 4 +- tests/msgbox.test | 16 +- tests/obj.test | 37 + tests/safe.test | 60 +- tests/scale.test | 18 +- tests/send.test | 656 ---------- tests/textDisp.test | 2 +- tests/textIndex.test | 474 +++++-- tests/textMark.test | 2 +- tests/textTag.test | 11 +- tests/tk.test | 4 +- tests/unixFont.test | 8 +- tests/unixMenu.test | 10 +- tests/unixSend.test | 657 ++++++++++ tests/unixWm.test | 33 +- tests/winDialog.test | 316 +++++ tests/winMenu.test | 27 +- tests/winSend.test | 415 ++++++ tests/winfo.test | 12 +- tests/xmfbox.test | 146 +++ unix/Makefile.in | 71 +- unix/README | 14 +- unix/configure.in | 25 +- unix/mkLinks | 120 +- unix/tkAppInit.c | 13 +- unix/tkUnix.c | 5 +- unix/tkUnixButton.c | 50 +- unix/tkUnixConfig.c | 45 + unix/tkUnixCursor.c | 19 +- unix/tkUnixDefault.h | 5 +- unix/tkUnixDialog.c | 207 --- unix/tkUnixEmbed.c | 4 +- unix/tkUnixEvent.c | 84 +- unix/tkUnixFont.c | 2738 +++++++++++++++++++++++++++++++--------- unix/tkUnixInit.c | 12 +- unix/tkUnixInt.h | 6 +- unix/tkUnixKey.c | 90 ++ unix/tkUnixMenu.c | 480 ++++--- unix/tkUnixPort.h | 9 +- unix/tkUnixSelect.c | 44 +- unix/tkUnixSend.c | 39 +- unix/tkUnixWm.c | 246 +++- unix/tkUnixXId.c | 7 +- win/README | 35 +- win/makefile.bc | 20 +- win/makefile.vc | 12 +- win/rc/tk.rc | 34 +- win/tkWin.h | 7 +- win/tkWin32Dll.c | 38 +- win/tkWin3d.c | 6 +- win/tkWinButton.c | 76 +- win/tkWinClipboard.c | 6 +- win/tkWinColor.c | 6 +- win/tkWinConfig.c | 60 + win/tkWinCursor.c | 7 +- win/tkWinDefault.h | 5 +- win/tkWinDialog.c | 1580 ++++++++++++++--------- win/tkWinEmbed.c | 9 +- win/tkWinFont.c | 2124 ++++++++++++++++++++++++++++--- win/tkWinInit.c | 4 +- win/tkWinInt.h | 14 +- win/tkWinKey.c | 72 +- win/tkWinMenu.c | 667 ++++++---- win/tkWinPort.h | 4 +- win/tkWinScrlbr.c | 4 +- win/tkWinSend.c | 1182 ++++++++++++++++- win/tkWinTest.c | 230 ++++ win/tkWinWindow.c | 13 +- win/tkWinWm.c | 120 +- win/tkWinX.c | 64 +- win/winMain.c | 61 +- xlib/X11/X.h | 6 +- xlib/X11/Xlib.h | 2 +- 243 files changed, 38923 insertions(+), 12601 deletions(-) create mode 100644 doc/SetOptions.3 create mode 100644 doc/dde.n create mode 100644 generic/prolog.ps create mode 100644 generic/tkObj.c create mode 100644 generic/tkOldConfig.c create mode 100644 library/images/logo.eps create mode 100644 library/images/pwrdLogo.eps create mode 100644 library/images/pwrdLogo100.gif create mode 100644 library/images/pwrdLogo150.gif create mode 100644 library/images/pwrdLogo175.gif create mode 100644 library/images/pwrdLogo200.gif create mode 100644 library/images/pwrdLogo75.gif create mode 100644 mac/tkMacConfig.c create mode 100644 mac/tkMacProjects.sit.hqx create mode 100644 tests/bitmap.test create mode 100644 tests/border.test create mode 100644 tests/config.test create mode 100644 tests/cursor.test create mode 100644 tests/get.test create mode 100644 tests/obj.test delete mode 100644 tests/send.test create mode 100644 tests/unixSend.test create mode 100644 tests/winDialog.test create mode 100644 tests/winSend.test create mode 100644 tests/xmfbox.test create mode 100644 unix/tkUnixConfig.c delete mode 100644 unix/tkUnixDialog.c create mode 100644 unix/tkUnixKey.c create mode 100644 win/tkWinConfig.c create mode 100644 win/tkWinTest.c diff --git a/README b/README index 255f0a1..1ae19d7 100644 --- a/README +++ b/README @@ -1,25 +1,28 @@ The Tk Toolkit -SCCS: @(#) README 1.47 97/11/20 12:48:16 +SCCS: @(#) README 1.51 98/02/18 18:02:32 1. Introduction --------------- This directory and its descendants contain the sources and documentation for Tk, an X11 toolkit implemented with the Tcl scripting language. The -information here corresponds to Tk 8.0p2, which is the second patch update -for Tk 8.0. This release is designed to work with Tcl 8.0p2 and may not -work with any other version of Tcl. - -Tk 8.0 is a major release with significant new features such as native -look and feel on Macintoshes and PCs, a new font mechanism, application -embedding, and proper support for Safe-Tcl. See below for details. -There should be no backward incompatibilities in Tk 8.0 that affect -scripts. This patch release fixes various bugs in Tk 8.0; there are no -feature changes relative to Tk 8.0. - -Note: with Tk 8.0 the Tk version number skipped from 4.2 to 8.0. The -jump was made in order to synchronize the Tcl and Tk version numbers. +information here constitutes the 8.1a2 release, which is the second alpha +release for Tk 8.1. This release is still in experimental form and is +intended for expert early adopters who are willing to help us find and +fix problems. The release is certain to contain bugs and is not yet +feature-complete: we will probably add new features or change some of +the existing features before the final 8.1 release. Please let us know +about any problems you uncover. + +The most important change in Tk 8.1 is that it supports the new +internationalization features in Tcl 8.1. It also contains a new +library for handling configuration options some of the widgets have been +converted to use the Tcl object facilities. For details on features, +incompatibilities, and potential problems with this release, see the +Tcl/Tk 8.1 Web page at http://sunscript.sun.com/TclTkCore/8.1.html or +refer to the "changes" file in this directory, which contains a +historical record of all changes to Tk. 2. Documentation ---------------- @@ -57,7 +60,7 @@ that summarizes the new features and discusses how to deal with the changes in Tk 4.0 that are not backwards compatible. There is also an official home for Tcl and Tk on the Web: - http://www.smli.com/research/tcl + http://sunscript.sun.com 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! @@ -75,9 +78,9 @@ Before trying to compile Tk you should do the following things: 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. + your platform, check the Tcl/Tk 8.1 Web page at + http://sunscript.sun.com/TclTkCore/8.1.html. 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 @@ -85,30 +88,30 @@ Before trying to compile Tk you should do the following things: 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 + tk8.1p1.tar.Z is a complete release for patch level 1 of Tk + version 8.1. 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 + files have names like tk8.1p1.patch, tk8.1p2.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 + tk8.1p1.patch must be applied to an unpatched Tk 8.1 release + to produce a Tk 8.1p1 release; tk8.1p2.patch can then be + applied to Tk 8.1p1 to produce Tk 8.1p2, and so on. To apply an + uncompressed patch file such as tk8.1p1.patch, invoke a shell command like the following from the directory containing this file: - patch -p < tk8.0p1.patch + patch -p < tk8.1p1.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 + gunzip -c tk8.1p1.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 + zcat tk8.1p1.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 @@ -133,121 +136,7 @@ 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 +5. Tcl/Tk newsgroup ------------------- There is a network news group "comp.lang.tcl" intended for the exchange @@ -263,7 +152,7 @@ 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 +6. Mailing lists ---------------- A couple of Mailing List have been set up to discuss Macintosh or @@ -271,11 +160,11 @@ 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 + http://www.sunlabs.com/people/raymond.johnson/mactcl-list.html -and- - http://www.sunlabs.com/research/tcl/lists/wintcl-list.html + http://sunscript.sun.com/win/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: diff --git a/changes b/changes index e01c4a8..e7b2123 100644 --- a/changes +++ b/changes @@ -2,7 +2,7 @@ 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 +SCCS: @(#) changes 1.268 98/02/18 18:06:42 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 @@ -4010,19 +4010,19 @@ 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) 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/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 +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 @@ -4127,3 +4127,128 @@ widgets. (JI) Apple Universal Headers V. 3.0 so we can compile with CW Pro 2.0 (JI) ----------------- Released 8.0p2, 11/25/97 ----------------------- + +11/25/97 (security bug fix + added feature) Tk Safe Init now asks +the master's safe::TkInit for the 'argv' to use. This is transparently +dealt with by the safe::loadTk API. New optional "-display displayName" +argument to safe::loadTk, and the "-use" argument accepts both window +Ids and Tk window names: see loadTk(n). Made the ":0.0" default display +work on the Mac as it works on Windows and Unix. (DL) + +12/3/97 (bug fix/optimization) Removed unneeded and potentially dangerous +instances of double evaluations if "if" and "expr" statements from +the library files. It is recommended that unless you need a double +evaluation you always use "expr {...}" instead of "expr ..." and +"if {...} ..." instead of "if ... ...". It will also be faster +thanks to the byte compiler. (DL) + +12/3/97 (new feature) Added support for browser/plugin style embedding, +and made various other fixes to get the plugin working on the Mac. (JI) + +12/8/97 (bug fix) on Windows, using "winfo pathname" before "." was mapped +was crashing. (DL) + +---- Shipped as part of the plugin2.0b5 as 8.0p2Plugin1, Dec 8th 97 ---- + +12/97 (bug fix) more Macintosh embeding fixes needed for the plugin. (JI) + +Jan/9/98 (improvement) Allow applications to have custom init script +without having to patch the Tk core: Tk_Init will use an existing +"tkInit" proc if one exists in the interp where one tries to install Tk +instead of defining it's own (tkInit is the transient proc defined in +generic/tkInitScript.h that searches and sources tk.tcl and defines +the 'correct' tk_library). (DL) + +---- Shipped as part of the plugin2.0 as 8.0p2Plugin2, Jan 15th 98 ---- + +---------------------------------------------------------- +Changes for Tk 8.0 go above this line. +Changes for Tk 8.1 go below this line. +---------------------------------------------------------- + +1/16/98 (new feature) Tk now supports international characters sets: + - Font display mechanism overhauled to display Unicode strings + containing full set of international characters. You do not need + Unicode fonts on your system in order to use tk or see international + characters. For those familiar with the Japanese or Chinese patches, + there is no "-kanjifont" option. Characters from any available fonts + will automatically be used if the widget's originally selected font is + not capable of displaying a given character. + - Textual widgets are international aware. For instance, cursor + positioning commands would now move the cursor forwards/back by 1 + international character, not by 1 byte. + - Input Method Editors (IMEs) work on Mac and Windows. Unix is still in + progress. + +7/7/97 (new feature) The send command now works for Microsoft +Windows. It is implemented using Dynamic Data Exchange, and a new +command, dde, allows Tk to send more generic DDE commands to other +applications. (SRP) + +11/3/97 (new feature) Major overhaul of code that manages configuration +options to use Tcl_Obj structures instead of strings: + - There is a new set of procedures including Tk_CreateOptionTable, + Tk_InitOptions, and Tk_SetOptions, which replace Tk_ConfigureWidget + and related procedures. The old procedures are still available. + The new procedures use a new format for configuration tables. + See SetOptions.3 for more information. + - There are new procedures Tk_AllocColorFromObj, Tk_GetColorFromObj, + and Tk_FreeColorFromObj to manage colors using objects to hold the + name of the color and cache the corresponding XColor pointer. + There are similar procedures Tk_Alloc3DBorderFromObj, + Tk_AllocBitmapFromObj, Tk_AllocCursorFromObj, Tk_AllocFontFromObj, + and so on to manage borders, bitmaps, cursors, and fonts. + - The old-style procedures such as Tk_GetColor and Tk_GetBitmap no + longer take Tk_Uids for arguments; they just take strings. + - Menus, labels, buttons, checkbuttons, and radiobuttons have been + converted to use the new object-based configuration library. + (SRP & JO) + +11/7/97 (improvement) Changed code referring to "interp->result" to call +accessor functions like Tcl_SetResult(). + +12/23/97 (fix) Fixed transparency and web optimized the palette of +the images/ Tcl powered logos. (DL) + +12/16/97 (bug fix) Canvas and text "bind" subcommands generated an +error with no message if called to fetch a binding that didn't exist. +They now silently return without an error like the "bind" command. (SS) + +1/13/98 (bug fix) Keysyms for international characters were not being +reported properly under Windows. (SS) + +----------------- Released 8.1a1, 1/22/98 ----------------------- + +2/4/98 (bug fix) Calling XFreeFontNames() twice if couldn't allocate +font. (CCS) + +2/10/98 (bug fix) Inlined prolog.ps in tkCanvPs.c to make it accessible +from safe interpreters: canvas postscript now works in safe interps +(like in tk8.0plugin). (DL) + +2/11/98 (bug fix) Windows "send" to a remote interp wasn't propagating +$errorInfo correctly from the remote interp to the local invoking interp. +(CCS) + +2/11/98 (bug fix) Windows "send" should have accepted "--" to mean "no more +arguments". (CCS) + +2/11/98 (bug fix) Windows "send" was concatenating its arguments +incorrectly (not consistent with "eval", "uplevel", or Unix "send"). (CCS) + +2/18/98 (bug fix) Macintosh radiobuttons and checkbuttons now color +their backgrounds correctly under Appearance. The controls gadgets themselves +however, remain the Theme colors. (JI) + +2/18/98 (improvement) The corner pixels that peek through around the +rounded corners of the Mac button widget are now controlled by the +-highlightbackground, rather than the -background option. (JI) + +2/18/98 (improvement) Implemented the intra-application Send on the +Mac (RJ) + +2/18/98 (bug fix) Under X, a problem mapping from a fontStructPtr to an +XLFD (no XA_FONT attribute) would lead to dereferencing NULL. (CCS) + +----------------- Released 8.1a2, Feb 20 1998 ----------------------- + diff --git a/compat/stdlib.h b/compat/stdlib.h index 059ea29..5ffda0e 100644 --- a/compat/stdlib.h +++ b/compat/stdlib.h @@ -9,12 +9,12 @@ * 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. + * Copyright (c) 1994-1998 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 + * SCCS: @(#) stdlib.h 1.12 98/01/21 21:04:59 */ #ifndef _STDLIB diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index 921a948..30b4f72 100644 --- a/doc/3DBorder.3 +++ b/doc/3DBorder.3 @@ -1,24 +1,32 @@ '\" '\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) 3DBorder.3 1.25 98/01/14 13:58:56 '\" .so man.macros -.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures" +.TH Tk_Alloc3DBorderFromObj 3 8.1 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 +Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 +Tk_3DBorder +\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp Tk_3DBorder \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR .sp +Tk_3DBorder +\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp void \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR .sp @@ -49,6 +57,10 @@ XColor * GC * \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR .sp +.VS 8.1 +\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp \fBTk_Free3DBorder(\fIborder\fB)\fR .SH ARGUMENTS .AS "Tk_3DBorder" borderWidth @@ -57,10 +69,15 @@ 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 Tcl_Obj *objPtr in +.VS 8.1 +Pointer to object whose value describes color corresponding to +background (flat areas). Illuminated edges will be brighter than +this and shadowed edges will be darker than this. +.AP char *colorName in +Same as \fIobjPtr\fR except value is supplied as a string rather +than an object. +.VE .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 @@ -129,22 +146,42 @@ Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. .SH DESCRIPTION .PP These procedures provide facilities for drawing window borders in a -way that produces a three-dimensional appearance. \fBTk_Get3DBorder\fR +way that produces a three-dimensional appearance. +.VS 8.1 +\fBTk_Alloc3DBorderFromObj\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 +given by the \fItkwin\fR argument. The value of \fIobjPtr\fR +is a standard Tk color name that determines the border colors. +The color indicated by \fIobjPtr\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. +by \fIobjPtr\fR, and the shadowed portions of the border will appear +darker than \fIobjPtr\fR. .PP -\fBTk_Get3DBorder\fR returns a token that may be used in later calls +\fBTk_Alloc3DBorderFromObj\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), +for the border (e.g. a bogus color name was given) then NULL is returned and an error message is left in \fIinterp->result\fR. +If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches +information about the return value in \fIobjPtr\fR, which speeds up +future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.PP +\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except +that the color is specified with a string instead of an object. This +prevents \fBTk_Get3DBorder\fR from caching the return value, so +\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. +.PP +\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given +the window and color name used to create the border. +\fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must +already have been created with a previous call to +\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.VE .PP Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be invoked to draw the border. @@ -171,7 +208,7 @@ a groove or ridge around the exterior of the rectangle. \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 +to the color 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 @@ -228,21 +265,19 @@ bottom bevel should be drawn with 0 for both arguments. 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 +just be the color specified 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. +will return the color name that was used 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 return value corresponds to the color name that was used to +create the border. The XColor, and its associated pixel value, will remain allocated as long as \fIborder\fR exists. .PP @@ -253,10 +288,18 @@ 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. +.VS 8.1 +When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR +or \fBTk_Free3DBorder\fR should +be called to release the resources associated with it. +For \fBTk_Free3DBorderFromObj\fR the border to release is specified +with the window and color name used to create the +border; for \fBTk_Free3DBorder\fR the border to release is specified +with the Tk_3DBorder token for the border. +There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or +\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR +or \fBTk_Get3DBorder\fR. +.VE .SH KEYWORDS -3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect +3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3 index 3178580..733870c 100644 --- a/doc/ConfigWidg.3 +++ b/doc/ConfigWidg.3 @@ -5,7 +5,7 @@ '\" 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 +'\" SCCS: @(#) ConfigWidg.3 1.32 98/01/02 13:18:16 '\" .so man.macros .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" @@ -26,10 +26,11 @@ int \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR .sp int +\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR .sp \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR .SH ARGUMENTS -.AS Tk_ConfigSpec *widgRec +.AS Tk_ConfigSpec *widgRec in/out .AP Tcl_Interp *interp in Interpreter to use for returning error messages. .AP Tk_Window tkwin in diff --git a/doc/CrtWindow.3 b/doc/CrtWindow.3 index 7799ed0..561a2da 100644 --- a/doc/CrtWindow.3 +++ b/doc/CrtWindow.3 @@ -5,7 +5,7 @@ '\" 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 +'\" @(#) CrtWindow.3 1.21 96/11/01 09:42:20 '\" .so man.macros .TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" diff --git a/doc/GetAnchor.3 b/doc/GetAnchor.3 index 4c5cdfb..96ac879 100644 --- a/doc/GetAnchor.3 +++ b/doc/GetAnchor.3 @@ -1,21 +1,26 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetAnchor.3 1.11 98/01/28 13:00:43 '\" .so man.macros -.TH Tk_GetAnchor 3 "" Tk "Tk Library Procedures" +.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions +Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 +int +\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR +.VE +.sp int \fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR .sp @@ -24,35 +29,52 @@ char * .SH ARGUMENTS .AS "Tk_Anchor" *anchorPtr .AP Tcl_Interp *interp in -Interpreter to use for error reporting. +Interpreter to use for error reporting, or NULL. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value contains name of anchor point: \fBn\fR, \fBne\fR, +\fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR; +internal rep will be modified to cache corresponding Tk_Anchor. .AP char *string in -String containing name of anchor point: one of ``n'', ``ne'', ``e'', ``se'', -``s'', ``sw'', ``w'', ``nw'', or ``center''. +Same as \fIobjPtr\fR except description of anchor point is passed as +a string. +.VE .AP int *anchorPtr out Pointer to location in which to store anchor position corresponding to -\fIstring\fR. +\fIobjPtr\fR or \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 +.VS 8.1 +\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position (enumerated type \fBTk_Anchor\fR) -corresponding to \fIstring\fR, which will be one of +corresponding to \fIobjPtr\fR's value. The result 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 +that will be used to position the 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. +or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, +\fI*anchorPtr\fR is unmodified, and an error message is +stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL. +\fBTk_GetAnchorFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except +that the description of the anchor is specified with a string instead +of an object. This prevents \fBTk_GetAnchor\fR from caching the +return value, so \fBTk_GetAnchor\fR is less efficient than +\fBTk_GetAnchorFromObj\fR. +.VE .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 diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3 index efe7760..edc806c 100644 --- a/doc/GetBitmap.3 +++ b/doc/GetBitmap.3 @@ -1,23 +1,31 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetBitmap.3 1.28 98/01/14 13:58:57 '\" .so man.macros -.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures" +.TH Tk_AllocBitmapFromObj 3 8.1 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 +Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 Pixmap -\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR +\fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Pixmap +\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR +.sp +Pixmap +\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR +.VE .sp int \fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR @@ -27,16 +35,27 @@ Tk_Uid .sp \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR .sp +.VS 8.1 +\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in -Interpreter to use for error reporting. +Interpreter to use for error reporting; if NULL then no error message +is left after errors. .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 +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value describes desired bitmap; internal rep will be +modified to cache pointer to corresponding Pixmap. +.AP char *info in +Same as \fIobjPtr\fR except description of bitmap is passed as a string and +resulting Pixmap isn't cached. +.VE +.AP char *name in Name for new bitmap to be defined. .AP char *source in Data for bitmap, in standard bitmap format. @@ -52,7 +71,8 @@ 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. +Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. .BE .SH DESCRIPTION @@ -62,11 +82,13 @@ 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: +.VS 8.1 +\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap +that matches the description in \fIobjPtr\fR and is suitable for use +in \fItkwin\fR. It re-uses an existing bitmap, if possible, and +creates a new one otherwise. \fIObjPtr\fR's value must have one +of the following forms: +.VE .TP 20 \fB@\fIfileName\fR \fIFileName\fR must be the name of a file containing a bitmap @@ -166,15 +188,35 @@ A face with ballon words. A triangle with an exclamation point. .RE .LP -Under normal conditions, \fBTk_GetBitmap\fR +.VS 8.1 +Under normal conditions, \fBTk_AllocBitmapFromObj\fR returns an identifier for the requested bitmap. If an error -occurs in creating the bitmap, such as when \fIid\fR refers +occurs in creating the bitmap, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error -message is left in \fIinterp->result\fR. +message is left in \fIinterp\fR's result if \fIinterp\fR isn't +NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR. +.PP +\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except +that the description of the bitmap is specified with a string instead +of an object. This prevents \fBTk_GetBitmap\fR from caching the +return value, so \fBTk_GetBitmap\fR is less efficient than +\fBTk_AllocBitmapFromObj\fR. +.PP +\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given +the window and description used to create the bitmap. +\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap +must already have been created with a previous call to +\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.VE .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 +calls to \fBTk_AllocBitmapFromObj\fR or \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 @@ -186,7 +228,8 @@ TCL_ERROR is returned and an error message is left in 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. +by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or +\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 @@ -217,15 +260,15 @@ 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. +Tk 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. +When a bitmap is no longer used, Tk will release it automatically. This approach can substantially reduce server overhead, so -\fBTk_GetBitmap\fR should generally be used in preference to Xlib -procedures like \fBXReadBitmapFile\fR. +\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally +be used in preference to Xlib procedures like \fBXReadBitmapFile\fR. .PP -The bitmaps returned by \fBTk_GetBitmap\fR +The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \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 @@ -233,28 +276,33 @@ 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 +Given an X Pixmap argument, it returns the textual description 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. +call to \fBTk_AllocBitmapFromObj\fR or \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. +\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or +\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. +.VS 8.1 +When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or +\fBTk_FreeBitmap\fR should be called to release it. +For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified +with the same information used to create it; for +\fBTk_FreeBitmap\fR the bitmap to release is specified +with its Pixmap token. +There should be exactly one call to \fBTk_FreeBitmapFromObj\fR +or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or +\fBTk_GetBitmap\fR. +.VE .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 +a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR +consider only the immediate value of the string description. 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 diff --git a/doc/GetColor.3 b/doc/GetColor.3 index 7f89446..f989cb0 100644 --- a/doc/GetColor.3 +++ b/doc/GetColor.3 @@ -1,32 +1,44 @@ '\" -'\" Copyright (c) 1990, 1991 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1990-1991 The Regents of the University of California. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetColor.3 1.24 98/01/14 13:58:58 '\" .so man.macros -.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures" +.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors +Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors .SH SYNOPSIS .nf \fB#include \fR +.VS 8.1 .sp XColor * -\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR +\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp XColor * -\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR +\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR +.sp +XColor * +\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp +XColor * +\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR .sp char * \fBTk_NameOfColor(\fIcolorPtr\fB)\fR .sp GC -\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) +\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR +.sp +.VS 8.1 +\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR +.VE .sp \fBTk_FreeColor(\fIcolorPtr\fB)\fR .SH ARGUMENTS @@ -35,27 +47,39 @@ GC 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. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value describes desired color; internal rep will be +modified to cache pointer to corresponding (XColor *). +.AP char *name in +Same as \fIobjPtr\fR except description of color is passed as a string and +resulting (XColor *) isn't cached. +.VE .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. +call to \fBTk_AllocColorFromObj\fR, \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 +.VS 8.1 +.PP +These procedures manage the colors being used by a Tk application. +They allow colors to be shared whenever possible, so that colormap +space is preserved, and they pick closest available colors when +colormap space is exhausted. .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: +Given a textual description of a color, \fBTk_AllocColorFromObj\fR +locates a pixel value that may be used to render the color +in a particular window. The desired color is specified with an +object whose string value must have one of the following forms: +.VE .TP 20 \fIcolorname\fR Any of the valid textual names for a color defined in the @@ -76,38 +100,56 @@ 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 +.VS 8.1 +\fBTk_AllocColorFromObj\fR 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. +that may be used to draw with the color in \fItkwin\fR. +If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown +color name) then NULL is returned and an error message is stored in +\fIinterp\fR's result if \fIinterp\fR isn't NULL. +If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR +will use the closest existing color in the colormap. +\fBTk_AllocColorFromObj\fR caches information about +the return value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR. +.PP +\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except +that the description of the color is specified with a string instead +of an object. This prevents \fBTk_GetColor\fR from caching the +return value, so \fBTk_GetColor\fR is less efficient than +\fBTk_AllocColorFromObj\fR. +.PP +\fBTk_GetColorFromObj\fR returns the token for an existing color, given +the window and description used to create the color. +\fBTk_GetColorFromObj\fR doesn't actually create the color; the color +must already have been created with a previous call to +\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.VE .PP -\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database +\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that +the desired color is indicated with the \fIred\fR, \fIgreen\fR, and +\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR. +.PP +This package maintains 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 +If the same color is requested multiple times from +\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\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. +with the window server, which makes the allocation much more +efficient. These procedures also provide a portable interface that +works across all platforms. For this reason, you should generally use +\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR +instead of lower level procedures like \fBXAllocColor\fR. .PP -Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR +Since different calls to this package may return the same shared pixel value, callers should never change the color of a pixel returned by the procedures. @@ -116,15 +158,16 @@ If you need to change a color value dynamically, you should use .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 +by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value +is the string that was used 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. +only guaranteed to persist until the next call to +\fBTk_NameOfColor\fR. .PP -\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR +\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. @@ -132,15 +175,16 @@ 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. - +.VS 8.1 +When a color is no longer needed \fBTk_FreeColorFromObj\fR or +\fBTk_FreeColor\fR should be called to release it. +For \fBTk_FreeColorFromObj\fR the color to release is specified +with the same information used to create it; for +\fBTk_FreeColor\fR the color to release is specified +with a pointer to its XColor structure. +There should be exactly one call to \fBTk_FreeColorFromObj\fR +or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR, +\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR. +.VE .SH KEYWORDS -color, intensity, pixel value +color, intensity, object, pixel value diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 index 5f940c9..329498a 100644 --- a/doc/GetCursor.3 +++ b/doc/GetCursor.3 @@ -1,23 +1,31 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetCursor.3 1.24 98/01/14 13:58:59 '\" .so man.macros -.TH Tk_GetCursor 3 4.1 Tk "Tk Library Procedures" +.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor \- maintain database of cursors +Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 Tk_Cursor -\fBTk_GetCursor(\fIinterp, tkwin, nameId\fB)\fR +\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR +.sp +Tk_Cursor +\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR +.VE .sp Tk_Cursor \fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR @@ -25,6 +33,10 @@ Tk_Cursor char * \fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR .sp +.VS 8.1 +\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp \fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR .SH ARGUMENTS .AS "unsigned long" *pixelPtr @@ -32,12 +44,18 @@ char * 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. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +Description of cursor; see below for possible values. Internal rep will be +modified to cache pointer to corresponding Tk_Cursor. +.AP char *name in +Same as \fIobjPtr\fR except description of cursor is passed as a string and +resulting Tk_Cursor isn't cached. +.VE .AP char *source in -Data for cursor bitmap, in standard bitmap format. +Data for cursor cursor, in standard cursor format. .AP char *mask in -Data for mask bitmap, in standard bitmap format. +Data for mask cursor, in standard cursor format. .AP "int" width in Width of \fIsource\fR and \fImask\fR. .AP "int" height in @@ -53,7 +71,7 @@ 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 +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 @@ -63,18 +81,25 @@ have been returned by some previous call to \fBTk_GetCursor\fR or 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). +allow cursors to be named with character strings. .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 +.VS 8.1 +\fBTk_AllocCursorFromObj\fR takes as argument an object 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. \fBTk_AllocCursorFromObj\fR caches +information about the return value in \fIobjPtr\fR, which speeds up +future calls to procedures such as \fBTk_AllocCursorFromObj\fR and +\fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor, +such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR +is returned and an error message will be stored in \fIinterp\fR's result +if \fIinterp\fR isn't NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: +.VE .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 +\fIName\fR is the name of a cursor in the standard X cursor cursor, +i.e., any of the names defined in \fBcursorcursor.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 @@ -86,9 +111,10 @@ 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 +.RS +.PP +The Macintosh version of Tk supports all of the X cursors and +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 @@ -96,11 +122,12 @@ 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. +.RE .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. +files describing cursors for the cursor's source bits and mask. +Each file must be in standard X11 or X10 cursor 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 @@ -112,10 +139,27 @@ 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 +.VS 8.1 +\fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except +that the description of the cursor is specified with a string instead +of an object. This prevents \fBTk_GetCursor\fR from caching the +return value, so \fBTk_GetCursor\fR is less efficient than +\fBTk_AllocCursorFromObj\fR. +.PP +\fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given +the window and description used to create the cursor. +\fBTk_GetCursorFromObj\fR doesn't actually create the cursor; the cursor +must already have been created with a previous call to +\fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.VE +.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 +in-memory descriptions of their source and mask cursors. \fISource\fR +points to standard cursor data for the cursor's source bits, and +\fImask\fR points to standard cursor 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 @@ -135,24 +179,26 @@ cursor = Tk_GetCursorFromData(interp, tkwin, source_bits, source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue")); .CE .PP -Under normal conditions, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR +Under normal conditions \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. +occurs in creating the cursor then \fBNone\fR is returned and an error +message will be stored in \fIinterp\fR's result. .PP -\fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR maintain a +\fBTk_AllocCursorFromObj\fR, \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 +a call to \fBTk_AllocCursorFromObj\fR, \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. +create a new cursor on each call. The Tk procedures are also more +portable than the lower-level X procedures. .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 +by \fBTk_GetCursor\fR, then the return value is the \fIname\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 @@ -162,17 +208,24 @@ 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. +.VS 8.1 +When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, +or \fBTk_GetCursorFromData\fR +is no longer needed, \fBTk_FreeCursorFromObj\fR or +\fBTk_FreeCursor\fR should be called to release it. +For \fBTk_FreeCursorFromObj\fR the cursor to release is specified +with the same information used to create it; for +\fBTk_FreeCursor\fR the cursor to release is specified +with its Tk_Cursor token. 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. +each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, +or \fBTk_GetCursorFromData\fR. +.VE .SH BUGS In determining whether an existing cursor can be used to satisfy -a new request, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR +a new request, \fBTk_AllocCursorFromObj\fR, \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 diff --git a/doc/GetFont.3 b/doc/GetFont.3 index ec6c052..006ea0d 100644 --- a/doc/GetFont.3 +++ b/doc/GetFont.3 @@ -1,74 +1,122 @@ '\" '\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetFont.3 1.12 98/01/14 13:58:59 '\" .so man.macros -.TH Tk_GetFont 3 "" Tk "Tk Library Procedures" +.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts +Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 Tk_Font -\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR +\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR +.sp +Tk_Font +\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR +.sp +Tk_Font +\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR +.VE .sp char * \fBTk_NameOfFont(\fItkfont\fB)\fR .sp +.VS 8.1 +Tk_Font +\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR +.VE +.sp void \fBTk_FreeFont(\fItkfont\fB)\fR .SH ARGUMENTS .AS "const char" *tkfont .AP "Tcl_Interp" *interp in -Interpreter to use for error reporting. +Interpreter to use for error reporting. If NULL, then no error +messages are left after errors. .AP Tk_Window tkwin in -Token for window on the display in which font will be used. +Token for window in which font will be used. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +Gives name or description of font. See documentation +for the \fBfont\fR command for details on acceptable formats. +Internal rep will be modified to cache corresponding Tk_Font. .AP "const char" *string in -Name or description of desired font. See documentation for the \fBfont\fR -command for details on acceptable formats. +Same as \fIobjPtr\fR except description of font is passed as a string and +resulting Tk_Font isn't cached. +.VE .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. +.VS 8.1 +\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\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 Tk_Font token +will remain valid until +\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. +\fIObjPtr\fR can contain 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_AllocFontFromObj\fR is unsuccessful (because, +for example, \fIobjPtr\fR did not contain a valid font specification) then it +returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result +if \fIinterp\fR isn't NULL. \fBTk_AllocFontFromObj\fR caches +information about the return +value in \fIobjPtr\fR, which speeds up future calls to procedures +such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR. +.PP +\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except +that the description of the font is specified with a string instead +of an object. This prevents \fBTk_GetFont\fR from caching the +matching Tk_Font, so \fBTk_GetFont\fR is less efficient than +\fBTk_AllocFontFromObj\fR. +.PP +\fBTk_GetFontFromObj\fR returns the token for an existing font, given +the window and description used to create the font. +\fBTk_GetFontFromObj\fR doesn't actually create the font; the font +must already have been created with a previous call to +\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. The return +value is cached in \fIobjPtr\fR, which speeds up +future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR +and \fItkwin\fR. +.VE .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. +\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain +a database of all fonts they have allocated. If +the same font is requested multiple times (e.g. by different +windows or for different purposes), then a single Tk_Font will be +shared for all uses. The underlying resources will be freed automatically +when no-one is using the font anymore. .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 +\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\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. +.VS 8.1 +When a font is no longer needed, +\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to +release it. For \fBTk_FreeFontFromObj\fR the font to release is specified +with the same information used to create it; for +\fBTk_FreeFont\fR the font to release is specified +with its Tk_Font token. There should be +exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR +for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR. +.VE .SH KEYWORDS font diff --git a/doc/GetJustify.3 b/doc/GetJustify.3 index 35ec0ae..1d5622d 100644 --- a/doc/GetJustify.3 +++ b/doc/GetJustify.3 @@ -1,22 +1,26 @@ '\" '\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetJustify.3 1.12 98/01/14 13:59:00 '\" .so man.macros -.TH Tk_GetJustify 3 4.0 Tk "Tk Library Procedures" +.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles +Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles .SH SYNOPSIS .nf \fB#include \fR .sp -Tk_Justify +.VS 8.1 +int +\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR +.sp +int \fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR .sp char * @@ -24,21 +28,30 @@ char * .SH ARGUMENTS .AS "Tk_Justify" *justifyPtr .AP Tcl_Interp *interp in -Interpreter to use for error reporting. +Interpreter to use for error reporting, or NULL. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value contains name of justification style (\fBleft\fR, \fBright\fR, or +\fBcenter\fR). The +internal rep will be modified to cache corresponding justify value. .AP char *string in -String containing name of justification style (``left'', ``right'', or -``center''). +Same as \fIobjPtr\fR except description of justification style is passed as +a string. +.VE .AP int *justifyPtr out Pointer to location in which to store justify value corresponding to -\fIstring\fR. +\fIobjPtr\fR or \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: +.VS 8.1 +\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value +corresponding to \fIobjPtr\fR's value. +.VE +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 @@ -52,12 +65,23 @@ the line; as a result, the left edges of lines may be ragged. 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 +.VS 8.1 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. +If \fIobjPtr\fR doesn't contain a valid justification style +or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned, +\fI*justifyPtr\fR is unmodified, and an error message is +stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL. +\fBTk_GetJustifyFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except +that the description of the justification is specified with a string instead +of an object. This prevents \fBTk_GetJustify\fR from caching the +return value, so \fBTk_GetJustify\fR is less efficient than +\fBTk_GetJustifyFromObj\fR. +.VE .PP \fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR. Given a justify value it returns a statically-allocated string diff --git a/doc/GetPixels.3 b/doc/GetPixels.3 index 6b26eb3..07d94c8 100644 --- a/doc/GetPixels.3 +++ b/doc/GetPixels.3 @@ -1,24 +1,34 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetPixels.3 1.9 98/01/14 13:59:00 '\" .so man.macros -.TH Tk_GetPixels 3 "" Tk "Tk Library Procedures" +.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetPixels, Tk_GetScreenMM \- translate between strings and screen units +Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 +int +\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR +.VE +.sp int \fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR .sp +.VS 8.1 +int +\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR +.VE +.sp int \fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR .SH ARGUMENTS @@ -27,9 +37,15 @@ int Interpreter to use for error reporting. .AP Tk_Window tkwin in Window whose screen geometry determines the conversion between absolute -units and pixels. +units and pixels. +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value specifies a distance on the screen; +internal rep will be modified to cache converted distance. .AP char *string in -String that specifies a distance on the screen. +Same as \fIobjPtr\fR except specification of distance is passed as +a string. +.VE .AP int *intPtr out Pointer to location in which to store converted distance in pixels. .AP double *doublePtr out @@ -38,10 +54,16 @@ Pointer to location in which to store converted distance in millimeters. .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 +These procedures take as argument a specification of distance on +.VS 8.1 +the screen (\fIobjPtr\fR or \fIstring\fR) and compute the +.VE +corresponding distance either in integer pixels or floating-point millimeters. +In either case, +.VS 8.1 +\fIobjPtr\fR or \fIstring\fR +.VE +specifies a screen distance as a floating-point number followed by one of the following characters that indicates units: .TP @@ -61,16 +83,29 @@ The number specifies a distance in millimeters on the screen. 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 +.VS 8.1 +\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the +nearest even number of pixels and stores that value at \fI*intPtr\fR. +It returns \fBTCL_OK\fR under normal circumstances. +If an error occurs (e.g. \fIobjPtr\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. +in \fIinterp\fR's result if \fIinterp\fR isn't NULL. +\fBTk_GetPixelsFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except +that the screen distance is specified with a string instead +of an object. This prevents \fBTk_GetPixels\fR from caching the +return value, so \fBTk_GetAnchor\fR is less efficient than +\fBTk_GetPixelsFromObj\fR. +.PP +\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to +\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except +that they convert the screen distance to millimeters and +store a double-precision floating-point result at \fI*doublePtr\fR. +.VE .SH KEYWORDS centimeters, convert, inches, millimeters, pixels, points, screen units diff --git a/doc/GetRelief.3 b/doc/GetRelief.3 index d0eade4..37a7cb9 100644 --- a/doc/GetRelief.3 +++ b/doc/GetRelief.3 @@ -1,21 +1,26 @@ '\" '\" Copyright (c) 1990 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 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 +'\" SCCS: @(#) GetRelief.3 1.12 98/01/14 13:59:01 '\" .so man.macros -.TH Tk_GetRelief 3 "" Tk "Tk Library Procedures" +.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures" .BS .SH NAME -Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values +Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values .SH SYNOPSIS .nf \fB#include \fR .sp +.VS 8.1 +int +\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR +.VE +.sp int \fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR .sp @@ -25,12 +30,18 @@ char * .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''). +.VS 8.1 br +.AP Tcl_Obj *objPtr in/out +String value contains name of relief (one of \fBflat\fR, \fBgroove\fR, +\fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR); +internal rep will be modified to cache corresponding relief value. +.AP char *string in +Same as \fIobjPtr\fR except description of relief is passed as +a string. +.VE .AP int *reliefPtr out Pointer to location in which to store relief value corresponding to -\fIname\fR. +\fIobjPtr\fR or \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). @@ -38,20 +49,31 @@ TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE). .SH DESCRIPTION .PP -\fBTk_GetRelief\fR places in \fI*reliefPtr\fR the relief value -corresponding to \fIname\fR. This value will be one of +.VS 8.1 +\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value +corresponding to the value of \fIobjPtr\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. +If \fIobjPtr\fR doesn't contain one of the valid relief names +or an abbreviation of one of them, then TCL_ERROR is returned, +\fI*reliefPtr\fR is unmodified, and an error message +is stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL. +\fBTk_GetReliefFromObj\fR caches information about the return +value in \fIobjPtr\fR, which speeds up future calls to +\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR. +.PP +\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except +that the description of the relief is specified with a string instead +of an object. This prevents \fBTk_GetRelief\fR from caching the +return value, so \fBTk_GetRelief\fR is less efficient than +\fBTk_GetReliefFromObj\fR. +.VE .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''). +Given a relief value it returns the corresponding string (\fBflat\fR, +\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR). If \fIrelief\fR isn't a legal relief value, then ``unknown relief'' is returned. diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 new file mode 100644 index 0000000..a734395 --- /dev/null +++ b/doc/SetOptions.3 @@ -0,0 +1,502 @@ +'\" +'\" Copyright (c) 1998 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: @(#) SetOptions.3 1.6 98/01/10 15:33:01 +'\" +.so man.macros +.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +Tk_OptionTable +\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR +.sp +\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR +.sp +int +\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR +.sp +int +\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR +.sp +\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR +.sp +\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR +.sp +Tcl_Obj * +\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +.sp +Tcl_Obj * +\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +.sp +\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR +.sp +int +\fBTk_Offset(\fItype, field\fB)\fR +.SH ARGUMENTS +.AS Tk_SavedOptions "*CONST objv[]" in/out +.AP Tcl_Interp *interp in +A Tcl interpreter. Most procedures use this only for returning error +messages; if it is NULL then no error messages are returned. For +\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the +interpreter in which the option table will be used. +.AP Tk_OptionSpec *templatePtr in +Points to an array of static information that describes the configuration +options that are supported. Used to build a Tk_OptionTable. The information +pointed to by this argument must exist for the lifetime of the Tk_OptionTable. +.AP Tk_OptionTable optionTable in +Token for an option table. Must have been returned by a previous call +to \fBTk_CreateOptionTable\fR. +.AP char *recordPtr in/out +Points to structure in which values of configuration options are stored; +fields of this record are modified by procedures such as \fBTk_SetOptions\fR +and read by procedures such as \fBTk_GetOptionValue\fR. +.AP Tk_Window tkwin in +For options such as TK_OPTION_COLOR, this argument indicates +the window in which the option will be used. If \fIoptionTable\fR uses +no window-dependent options, then a NULL value may be supplied for +this argument. +.AP int objc in +Number of values in \fIobjv\fR. +.AP Tcl_Obj "*CONST objv[]" in +Command-line arguments for setting configuring options. +.AP Tk_SavedOptions *savePtr out +If not NULL, the structure pointed to by this argument is filled +in with the old values of any options that were modified and old +values are restored automatically if an error occurs in \fBTk_SetOptions\fR. +.AP int *maskPtr out +If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the +bit-wise OR of the \fItypeMask\fR fields for the options that +were modified. +.AP Tk_SavedOptions *savedPtr in/out +Points to a structure previously filled in by \fBTk_SetOptions\fR with +old values of modified options. +.AP Tcl_Obj *namePtr in +The value of this object is the name of a particular option. If NULL +is passed to \fBTk_GetOptionInfo\fR then information is returned for +all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. +.AP "type name" type in +The name of the type of a record. +.AP "field name" field in +The name of a field in records of type \fItype\fR. +.BE +.SH DESCRIPTION +.PP +These procedures handle most of the details of parsing configuration +options such as those for Tk widgets. Given a description of what +options are supported, these procedures handle all the details of +parsing options and storing their values into a C structure associated +with the widget or object. The procedures were designed primarily for +widgets in Tk, but they can also be used for other kinds of objects that +have configuration options. In the rest of this manual page ``widget'' will +be used to refer to the object whose options are being managed; in +practice the object may not actually be a widget. The term ``widget +record'' is used to refer to the C-level structure in +which information about a particular widget or object is stored. +.PP +Note: the easiest way to learn how to use these procedures is to +look at a working example. In Tk, the simplest example is the code +that implements the button family of widgets, which is an \fBtkButton.c\fR. +Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. +.PP +In order to use these procedures, the code that implements the widget +must contain a static array of Tk_OptionSpec structures. This is a +template that describes the various options supported by that class of +widget; there is a separate template for each kind of widget. The +template contains information such as the name of each option, its type, +its default value, and where the value of the option is stored in the +widget record. See TEMPLATES below for more detail. +.PP +In order to process configuration options efficiently, the static +template must be augmented with additional information that is available +only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this +dynamic information from the template and returns a Tk_OptionTable token +that describes both the static and dynamic information. All of the +other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable +token as argument. Typically, \fBTk_CreateOptionTable\fR is called the +first time that a widget of a particular class is created and the +resulting Tk_OptionTable is used in the future for all widgets of that +class. A Tk_OptionTable may be used only in a single interpreter, given +by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an +option table is no longer needed \fBTk_DeleteOptionTable\fR should be +called to free all of its resources. All of the option tables +for a Tcl interpreter are freed automatically if the interpreter is deleted. +.PP +\fBTk_InitOptions\fR is invoked when a new widget is created to set +the default values for all of the widget's configuration options. +\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) +and a pointer to a widget record (\fIrecordPtr\fR), which is the C +structure that holds information about this widget. \fBTk_InitOptions\fR +uses the information in the option table to +choose an appropriate default for each option, then it stores the default +value directly into the widget record, overwriting any information that +was already present in the widget record. \fBTk_InitOptions\fR normally +returns TCL_OK. If an error occurred while setting the default values +(e.g., because a default value was erroneous) then TCL_ERROR is returned +and an error message is left in \fIinterp\fR's result if \fIinterp\fR +isn't NULL. +.PP +\fBTk_SetOptions\fR is invoked to modify configuration options based +on information specified in a Tcl command. The command might be one that +creates a new widget, or a command that modifies options on an existing +widget. The \fIobjc\fR and \fIobjv\fR arguments describe the +values of the arguments from the Tcl command. \fIObjv\fR must contain +an even number of objects: the first object of each pair gives the name of +an option and the second object gives the new value for that option. +\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that +the new value of the option conforms to the type in \fIoptionTable\fR, +and stores the value of the option into the widget record given by +\fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns TCL_OK. If +an error occurred (such as an unknown option name or an illegal option +value) then TCL_ERROR is returned and an error message is left in +\fIinterp\fR's result if \fIinterp\fR isn't NULL. +.PP +\fBTk_SetOptions\fR has two additional features. First, if the +\fImaskPtr\fR argument isn't NULL then it points to an integer +value that is filled in with information about the options that were +modified. For each option in the template passed to +\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The +bits of this field are defined by the code that implements the widget; +for example, each bit might correspond to a particular configuration option. +Alternatively, bits might be used functionally. For example, one bit might +be used for redisplay: all options that affect the widget's display, such +that changing the option requires the widget to be redisplayed, might have +that bit set. Another bit might indicate that the geometry of the widget +must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the +\fItypeMask\fR fields from all the options that were modified and returns +this value at *\fImaskPtr\fR; the caller can then use this information +to optimize itself so that, for example, it doesn't redisplay the widget +if the modified options don't affect the widget's appearance. +.PP +The second additional feature of \fBTk_SetOptions\fR has to do with error +recovery. If an error occurs while processing configuration options, this +feature makes it possible to restore all the configuration options to their +previous values. Errors can occur either while processing options in +\fBTk_SetOptions\fR or later in the caller. In many cases the caller does +additional processing after \fBTk_SetOptions\fR returns; for example, it +might use an option value to set a trace on a variable and may detect +an error if the variable is an array instead of a scalar. Error recovery +is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument +to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized +Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR +overwrites the structure pointed to by \fIsavePtr\fR with information +about the old values of any options modified by the procedure. +If \fBTk_SetOptions\fR returns successfully, the +caller uses the structure in one of two ways. If the caller completes +its processing of the new options without any errors, then it must pass +the structure to \fBTk_FreeSavedOptions\fR so that the old values can be +freed. If the caller detects an error in its processing of the new +options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, +which will copy the old values back into the widget record and free +the new values. +If \fBTk_SetOptions\fR detects an error then it automatically restores +any options that had already been modified and leaves *\fIsavePtr\fR in +an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or +\fBTk_RestoreSavedOptions\fR. +If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then +\fBTk_SetOptions\fR frees each old option value immediately when it sets a new +value for the option. In this case, if an error occurs in the third +option, the old values for the first two options cannot be restored. +.PP +\fBTk_GetOptionValue\fR returns the current value of a configuration option +for a particular widget. The \fInamePtr\fR argument contains the name of +an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR +to lookup the option and extract its value from the widget record +pointed to by \fIrecordPtr\fR, then it returns an object containing +that value. If an error occurs (e.g., because \fInamePtr\fR contains an +unknown option name) then NULL is returned and an error message is left +in \fIinterp\fR's result unless \fIinterp\fR is NULL. +.PP +\fBTk_GetOptionInfo\fR returns information about configuration options in +a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR +argument is not NULL, it points to an object that gives the name of a +configuration option; \fBTk_GetOptionInfo\fR returns an object containing +a list with five elements, which are the name of the option, the name and +class used for the option in the option database, the default value for +the option, and the current value for the option. If the \fInamePtr\fR +argument is NULL, then \fBTk_GetOptionInfo\fR returns information about +all options in the form of a list of lists; each sublist describes one +option. Synonym options are handled differently depending on whether +\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for +each synonym option has only two elements, which are the name of the +option and the name of the other option that it refers to; if \fInamePtr\fR +is non-NULL and names a synonym option then the object returned +is the five-element list +for the other option that the synonym refers to. If an error occurs +(e.g., because \fInamePtr\fR contains an unknown option name) then NULL +is returned and an error message is left in \fIinterp\fR's result unless +\fIinterp\fR is NULL. +.PP +\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. +It frees all of the resources associated with any of the configuration +options defined in \fIrecordPtr\fR by \fIoptionTable\fR. +.PP +The \fBTk_Offset\fR macro is provided as a safe way of generating the +\fIobjOffset\fR and \fIinternalOffset\fR values for entries in +Tk_OptionSpec 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 "TEMPLATES" +.PP +The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR +via its \fItemplatePtr\fR argument describes the configuration options +supported by a particular class of widgets. Each structure specifies +one configuration option and has the following fields: +.CS +typedef struct { + Tk_OptionType \fItype\fR; + char *\fIoptionName\fR; + char *\fIdbName\fR; + char *\fIdbClass\fR; + char *\fIdefValue\fR; + int \fIobjOffset\fR; + int \fIinternalOffset\fR; + int \fIflags\fR; + ClientData \fIclientData\fR; + int \fItypeMask\fR; +} Tk_OptionSpec; +.CE +The \fItype\fR field indicates what kind of configuration option this is +(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for +an integer value). \fIType\fR determines how the +value of the option is parsed (more on this below). +The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; +it is the name used for the option in Tcl commands and passed to +procedures via the \fIobjc\fR or \fInamePtr\fR arguments. +The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR +to look up a default value for this option in the option database; if +\fIdbName\fR is NULL then the option database is not used by +\fBTk_InitOptions\fR for this option. The \fIdefValue\fR field +specifies a default value for this configuration option if no +value is specified in the option database. The \fIobjOffset\fR and +\fIinternalOffset\fR fields indicate where to store the value of this +option in widget records (more on this below); values for the \fIobjOffset\fR +and \fIinternalOffset\fR fields should always be generated with the +\fBTk_Offset\fR macro. +The \fIflags\fR field contains additional information +to control the processing of this configuration option (see below +for details). +\fIClientData\fR provides additional type-specific data needed +by certain types. For instance, for TK_OPTION_COLOR types, +\fIclientData\fR is a string giving the default value to use on +monochrome displays. See the descriptions of the different types +below for details. +The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to +return information about which options were modified; see the description +of \fBTk_SetOptions\fR above for details. +.PP +When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an +option into the widget record, they can do it in either of two ways. +If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than +or equal to zero, then the value of the option is stored as a +(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. +If the \fIinternalOffset\fR field of the Tk_OptionSpec is +greater than or equal to zero, then the value of the option is stored +in a type-specific internal form at the location in the widget record +given by \fIinternalOffset\fR. For example, if the option's type is +TK_OPTION_INT then the internal form is an integer. If the +\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the +value is not stored in that form. At least one of the offsets must be +greater than or equal to zero. +.PP +The \fIflags\fR field consists of one or more bits ORed together. At +present only a single flag is supported: TK_OPTION_NULL_OK. If +this bit is set for an option then an empty string will be accepted as +the value for the option and the resulting internal form will be a +NULL pointer or \fBNone\fR, depending on the type of the option. +If the flag is not set then empty strings will result +in errors. +TK_OPTION_NULL_OK 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. +Not all option types support the TK_OPTION_NULL_OK +flag; for those that do, there is an explicit indication of that fact +in the descriptions below. +.PP +The \fItype\fR field of each Tk_OptionSpec structure determines +how to parse the value of that configuration option. The +legal value for \fItype\fR, and the corresponding actions, are +described below. If the type requires a \fItkwin\fR value to be +passed into procedures like \fBTk_SetOptions\fR, or if it uses +the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated +explicitly; if not mentioned, the type requires neither \fItkwin\fR +nor \fIclientData\fR. +.TP +\fBTK_OPTION_ANCHOR\fR +The value must be a standard anchor position such as \fBne\fR or +\fBcenter\fR. The internal form is a Tk_Anchor value like the ones +returned by \fBTk_GetAnchorFromObj\fR. +.TP +\fBTK_OPTION_BITMAP\fR +The value must be a standard Tk bitmap name. The internal form is a +Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_BOOLEAN\fR +The value must be a standard boolean value such as \fBtrue\fR or +\fBno\fR. The internal form is an integer with value 0 or 1. +.TP +\fBTK_OPTION_BORDER\fR +The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. +The internal form is a Tk_3DBorder token like the ones returned +by \fBTk_Alloc3DBorderFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_COLOR\fR +The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. +The internal form is an (XColor *) token like the ones returned by +\fBTk_AllocColorFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_CURSOR\fR +The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. +The internal form is a Tk_Cursor token like the ones returned by +\fBTk_AllocCursorFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and when the option is set the cursor +for the window is changed by calling \fBXDefineCursor\fR. This +option type also supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_DOUBLE\fR +The string value must be a floating-point number in +the format accepted by \fBstrtol\fR. The internal form is a C +\fBdouble\fR value. +.TP +\fBTK_OPTION_END\fR +Marks the end of the template. There must be a Tk_OptionSpec structure +with \fItype\fR TK_OPTION_END at the end of each template. If the +\fIclientData\fR field of this structure isn't NULL, then it points to +an additional array of Tk_OptionSpec's, which is itself terminated by +another TK_OPTION_END entry. Templates may be chained arbitrarily +deeply. This feature allows common options to be shared by several +widget classes. +.TP +\fBTK_OPTION_FONT\fR +The value must be a standard font name such as \fBTimes 16\fR. +The internal form is a Tk_Font handle like the ones returned by +\fBTk_AllocFontFromObj\fR. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_INT\fR +The string value must be an integer in the format accepted by +\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to +specify octal or hexadecimal numbers, respectively). The internal +form is a C \fBint\fR value. +.TP +\fBTK_OPTION_JUSTIFY\fR +The value must be a standard justification value such as \fBleft\fR. +The internal form is a Tk_Justify like the values returned by +\fBTk_GetJustifyFromObj\fR. +.TP +\fBTK_OPTION_PIXELS\fR +The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. +The internal form is an integer value giving a +distance in pixels, like the values returned by +\fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field isn't +used then information about the original value of this option will be lost. +See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. +.TP +\fBTK_OPTION_RELIEF\fR +The value must be standard relief such as \fBraised\fR. +The internal form is an integer relief value such as +TK_RELIEF_RAISED. +.TP +\fBTK_OPTION_STRING\fR +The value may be any string. The internal form is a (char *) pointer +that points to a dynamically allocated copy of the value. +This option type supports the TK_OPTION_NULL_OK flag. +.TP +\fBTK_OPTION_STRING_TABLE\fR +For this type, \fIclientData\fR is a pointer to an array of strings +suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must +be one of the strings in the table, or a unique abbreviation of +one of the strings. The internal form is an integer giving the index +into the table of the matching string, like the return value +from \fBTcl_GetStringFromObj\fR. +.TP +\fBTK_OPTION_SYNONYM\fR +This type is used to provide alternative names for an option (for +example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). +The \fBclientData\fR field is a (char *) pointer that gives +the name of another option in the same table. Whenever the +synonym option is used, the information from the other option +will be used instead. +.TP +\fBTK_OPTION_WINDOW\fR +The value must be a window path name. The internal form is a +\fBTk_Window\fR token for the window. +This option type requires \fItkwin\fR to be supplied to procedures +such as \fBTk_SetOptions\fR (in order to identify the application), +and it supports the TK_OPTION_NULL_OK flag. + +.SH "STORAGE MANAGEMENT ISSUES" +.PP +If a field of a widget record has its offset stored in the \fIobjOffset\fR +or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the +procedures described here will handle all of the storage allocation and +resource management issues associated with the field. When the value +of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR +will automatically free any resources associated with the old value, such as +Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for +TK_OPTION_STRING options. For an option stored as an object using the +\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the +object pointed to by the \fIobjv\fR value from the call to +\fBTk_SetOptions\fR. The reference count for this object is incremented +when a pointer to it is stored in the widget record and decremented when +the option is modified. When the widget is deleted +\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources +associated with all options and decrement reference counts for any +objects. +.PP +However, the widget code is responsible for storing NULL or \fBNone\fR in +all pointer and token fields before invoking \fBTk_InitOptions\fR. +This is needed to allow proper cleanup in the rare case where +an error occurs in \fBTk_InitOptions\fR. + +.SH "OBJOFFSET VS. INTERNALOFFSET" +.PP +In most cases it is simplest to use the \fIinternalOffset\fR field of +a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This +makes the internal form of the value immediately available to the +widget code so the value doesn't have to be extracted from an object +each time it is used. However, there are two cases where the +\fIobjOffset\fR field is useful. The first case is for +TK_OPTION_PIXELS options. In this case, the internal form is +an integer pixel value that is valid only for a particular screen. +If the value of the option is retrieved, it will be returned as a simple +number. For example, after the command \fB.b configure \-borderwidth 2m\fR, +the command \fB.b configure \-borderwidth\fR might return 7, which is the +integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses +the original screen-independent value. Thus for TK_OPTION_PIXELS options +it is better to use the \fIobjOffset\fR field. In this case the original +value of the option is retained in the object and can be returned when +the option is retrieved. In most cases it is convenient to use the +\fIinternalOffset\fR field field as well, so that the integer value is +immediately available for use in the widget code (alternatively, +\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from +the object whenever it is needed). Note: the problem of losing information +on retrievals exists only for TK_OPTION_PIXELS options. +.PP +The second reason to use the \fIobjOffset\fR field is in order to +implement new types of options not supported by these procedures. +To implement a new type of option, use TK_OPTION_STRING as +the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field +but not the \fIinternalOffset\fR field. Then, after calling +\fBTk_SetOptions\fR, convert the object to internal form yourself. + +.SH KEYWORDS +anchor, bitmap, boolean, border, color, configuration option, +cursor, double, font, integer, justify, +pixels, relief, screen distance, synonym diff --git a/doc/dde.n b/doc/dde.n new file mode 100644 index 0000000..1df6c87 --- /dev/null +++ b/doc/dde.n @@ -0,0 +1,100 @@ +'\" +'\" Copyright (c) 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: @(#) dde.n 1.3 98/01/28 12:48:08 +'\" +.so man.macros +.TH dde n 8.1 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +dde \- Execute a Dynamic Data Exchange command +.SH SYNOPSIS +\fBdde ?\-async?\fR \fIcommand service topic \fR?\fIdata\fR? +.BE + +.SH DESCRIPTION +.PP +This command allows an application to send Dynamic Data Exchange (DDE) +command when running under Microsoft Windows. Dynamic Data Exchange is +a mechanism where applications can exchange raw data. Each DDE +transaction needs a \fIservice name\fR and a \fItopic\fR. Both the +\fIservice name\fR and \fItopic\fR are application defined; Tk uses +the service name \fBTk\fR, while the topic name is the name of the +interpreter given by \fBtk appname\fR. Other applications have their +own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel +has the service name \fBExcel\fR. +.PP +The only option to the \fBsend\fR command is: +.TP +\fB\-async\fR +Requests asynchronous invocation. This is valid only for the +\fBexecute\fR subcommand. Normally, the \fBdde execute\fR subcommand +waits until the command completes, returning appropriate error +messages. When the \fB\-async\fR option is used, the command returns +immediately, and no error information is available. +.SH "DDE COMMANDS" +.PP +The following commands are a subset of the full Dynamic Data Exchange +set of commands. +.TP +\fBdde execute \fIservice topic data\fR +\fBdde execute\fR takes the \fIdata\fR and sends it to the server +indicated by \fIservice\fR with the topic indicated by +\fItopic\fR. Typically, \fIservice\fR is the name of an application, +and \fItopic\fR is a file to work on. The \fIdata\fR field is given +to the remote application. Typically, the application treats the +\fIdata\fR field as a script, and the script is run in the +application. The command returns an error if the script did not +run. If the \fB\-async\fR flag was used, the command +returns immediately with no error. +.TP +\fBdde request \fIservice topic item\fR +\fBdde request\fR is typically used to get the value of something; the +value of a cell in Microsoft Excel or the text of a selection in +Microsoft Word. \fIservice\fR is typically the name of an application, +\fItopic\fR is typically the name of the file, and \fIitem\fR is +application-specific. The command returns the value of \fIitem\fR as +defined in the application. +.TP +\fBdde services \fIservice topic\fR +\fBdde services\fR returns a list of service-topic pairs that +currently exist on the machine. If \fIservice\fR and \fItopic\fR are +both null strings ({}), then all service-topic pairs currently +available on the system are returned. If \fIservice\fR is null and +\fItopic\fR is not, then all services with the specified topic are +returned. If \fIservice\fR is not null and \fItopic\fR is, all topics +for a given service are returned. If both are not null, if that +service-topic pair currently exists, it is returned; otherwise, null +is returned. +.SH "DDE AND TK" +Tk always has a service name of "Tk". Each different interp of all +running Tk applications has a unique name. A list of running interps +can be retrieved using the \fBwinfo interps\fR command. A given +interp's name can be set with the \fBtk appname\fR. Each interp is +available as a DDE topic. So a \fBdde services Tk {}\fR command will +return a list of service-topic pairs, where each of the currently +running interps will be a topic. +.PP +When Tk processes a \fBdde execute\fR command, the data for the +execute is run as a script in the interp named by the topic of the +\fBdde execute\fR command. +.PP +When Tk processes a \fBdde request\fR command, it returns the value of +the variable given in the dde command in the context of the interp +named by the dde topic. Tk reserves the variable "$TK$EXECUTE$RESULT" +for internal use, and \fBdde request\fR commands for that variable +will give unpredictable results. +.PP +An external application which wishes to run a script in Tk should have +that script store its result in a variable, run the \fBdde execute\fR +command, and the run \fBdde request\fR to get the value of the +variable. +.SH KEYWORDS +application, dde, name, remote execution +.SH "SEE ALSO" +tk, winfo, send + diff --git a/doc/loadTk.n b/doc/loadTk.n index 16e3532..dbe7f86 100644 --- a/doc/loadTk.n +++ b/doc/loadTk.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) loadTk.n 1.5 97/08/18 17:44:43 +'\" SCCS: @(#) loadTk.n 1.8 97/11/26 10:10:07 '\" .so man.macros .TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" @@ -13,7 +13,7 @@ .SH NAME loadTk \- Load Tk into a safe interpreter. .SH SYNOPSIS -\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? +\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? .BE Safe Tk is based on Safe Tcl, which provides a mechanism @@ -31,9 +31,15 @@ The command returns the name of the safe interpreter. If \fB\-use\fR is specified, the window identified by the specified system dependent identifier \fIwindowId\fR is used to contain the \fB``.''\fR window of the safe interpreter; it can be any valid id, eventually -referencing a window belonging to another application. -Otherwise, a new toplevel window is created for the \fB``.''\fR window of -the safe interpreter. +referencing a window belonging to another application. As a convenience, +if the window you plan to use is a Tk Window of the application you +can use the window name (eg: \fB.x.y\fR) instead of its window Id +(\fB[winfo id .x.y]\fR). +When \fB\-use\fR is not specified, +a new toplevel window is created for the \fB``.''\fR window of +the safe interpreter. On X11 if you want the embedded window +to use another display than the default one, specify it with +\fB\-display\fR. See the \fBSECURITY ISSUES\fR section below for implementation details. .SH SECURITY ISSUES @@ -41,42 +47,26 @@ See the \fBSECURITY ISSUES\fR section below for implementation details. Please read the \fBsafe\fR manual page for Tcl to learn about the basic security considerations for Safe Tcl. .PP -Information in the safe interpreter should never be trusted for security -purposes. -However, because Tk initialization of the safe interpreter do use -local information, it is unsafe if the safe interpreter -could have gained control before Tk is loaded. -This will be fixed in an upcoming release, by making Tk initialization in a -safe interpreter use only information found in the interpreter's master -instead of relying on the (un)safe interpreter state. -.PP -You should therefore use \fBsafe::loadTk $slave\fR as soon as possible -after \fBsafe::interpCreate\fR and before any code is evaluated in the safe -interpreter. -The preferred sequence is: -.CS -set slave [::safe::loadTk [::safe::interpCreate]] -.CE -If you want to prevent safe interpreters from loading Tk entirely, you -should create the interpreter as follows: -.CS -::safe::interpCreate \-nostatics \-accesspath \fI{directories...}\fR -.CE -and you must also insure that the virtual access path \fIdirectories\fR for -the interpreter does not contain a dynamically loadable version of Tk. -.PP \fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master interpreter to the virtual access path of the safe interpreter so that auto-loading will work in the safe interpreter. -It also sets \fBenv(DISPLAY)\fR in the safe interpreter to the value of -\fBenv(DISPLAY)\fR in the master interpreter, if it exists. -Finally, it sets the slave's Tcl variable \fBargv\fR to \fB\-use\fR -\fIwindowId\fR in the safe interpreter. - +.PP +.PP +Tk initialization is now safe with respect to not trusting +the slave's state for startup. \fB::safe::loadTk\fR +registers the slave's name so +when the Tk initialization (\fBTk_SafeInit\fR) is called +and in turn calls the master's \fB::safe::InitTk\fR it will +return the desired \fBargv\fR equivalent (\fB\-use\fR +\fIwindowId\fR, correct \fB\-display\fR, etc...). +.PP When \fB\-use\fR is not used, the new toplevel created is specially decorated so the user is always aware that the user interface presented comes from a potentially unsafe code and can easily delete the corresponding interpreter. +.PP +On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely +to generate a fatal X error. .SH "SEE ALSO" safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) diff --git a/doc/send.n b/doc/send.n index e949c18..fc93779 100644 --- a/doc/send.n +++ b/doc/send.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) send.n 1.18 96/08/27 13:21:47 +'\" SCCS: @(#) send.n 1.19 97/07/07 16:53:29 '\" .so man.macros .TH send n 4.0 Tk "Tk Built-In Commands" @@ -70,8 +70,8 @@ command. .SH SECURITY .PP -The \fBsend\fR command is potentially a serious security loophole, -since any application that can connect to your X server can send +The \fBsend\fR command is potentially a serious security loophole. On Unix, +any application that can connect to your X server can send scripts to your applications. These incoming scripts can use Tcl to read and write your files and invoke subprocesses under your name. @@ -87,6 +87,15 @@ list of enabled hosts is empty. This means that applications cannot connect to your server unless they use some other form of authorization such as that provide by \fBxauth\fR. - +.VS +Under Windows, any application running on the current machine can send +Dynamic Data Exchange (DDE) commands which could read and write files and start +processes. Only the local machine can connect, however, so there are +no restrictions on which processes can connect. The \fBsend\fR command +uses DDE as its transport, and a \fBdde\fR command has been added to +Tk 8.0. +.VE .SH KEYWORDS -application, name, remote execution, security, send +.VS +application, dde, name, remote execution, security, send +.VE diff --git a/generic/prolog.ps b/generic/prolog.ps new file mode 100644 index 0000000..378d503 --- /dev/null +++ b/generic/prolog.ps @@ -0,0 +1,284 @@ +%%BeginProlog +50 dict begin + +% This is a standard prolog for Postscript generated by Tk's canvas +% widget. +% SCCS: @(#) prolog.ps 1.7 96/07/08 17:52:14 + +% The definitions below just define all of the variables used in +% any of the procedures here. This is needed for obscure reasons +% explained on p. 716 of the Postscript manual (Section H.2.7, +% "Initializing Variables," in the section on Encapsulated Postscript). + +/baseline 0 def +/stipimage 0 def +/height 0 def +/justify 0 def +/lineLength 0 def +/spacing 0 def +/stipple 0 def +/strings 0 def +/xoffset 0 def +/yoffset 0 def +/tmpstip null def + +% Define the array ISOLatin1Encoding (which specifies how characters are +% encoded for ISO-8859-1 fonts), if it isn't already present (Postscript +% level 2 is supposed to define it, but level 1 doesn't). + +systemdict /ISOLatin1Encoding known not { + /ISOLatin1Encoding [ + /space /space /space /space /space /space /space /space + /space /space /space /space /space /space /space /space + /space /space /space /space /space /space /space /space + /space /space /space /space /space /space /space /space + /space /exclam /quotedbl /numbersign /dollar /percent /ampersand + /quoteright + /parenleft /parenright /asterisk /plus /comma /minus /period /slash + /zero /one /two /three /four /five /six /seven + /eight /nine /colon /semicolon /less /equal /greater /question + /at /A /B /C /D /E /F /G + /H /I /J /K /L /M /N /O + /P /Q /R /S /T /U /V /W + /X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore + /quoteleft /a /b /c /d /e /f /g + /h /i /j /k /l /m /n /o + /p /q /r /s /t /u /v /w + /x /y /z /braceleft /bar /braceright /asciitilde /space + /space /space /space /space /space /space /space /space + /space /space /space /space /space /space /space /space + /dotlessi /grave /acute /circumflex /tilde /macron /breve /dotaccent + /dieresis /space /ring /cedilla /space /hungarumlaut /ogonek /caron + /space /exclamdown /cent /sterling /currency /yen /brokenbar /section + /dieresis /copyright /ordfeminine /guillemotleft /logicalnot /hyphen + /registered /macron + /degree /plusminus /twosuperior /threesuperior /acute /mu /paragraph + /periodcentered + /cedillar /onesuperior /ordmasculine /guillemotright /onequarter + /onehalf /threequarters /questiondown + /Agrave /Aacute /Acircumflex /Atilde /Adieresis /Aring /AE /Ccedilla + /Egrave /Eacute /Ecircumflex /Edieresis /Igrave /Iacute /Icircumflex + /Idieresis + /Eth /Ntilde /Ograve /Oacute /Ocircumflex /Otilde /Odieresis /multiply + /Oslash /Ugrave /Uacute /Ucircumflex /Udieresis /Yacute /Thorn + /germandbls + /agrave /aacute /acircumflex /atilde /adieresis /aring /ae /ccedilla + /egrave /eacute /ecircumflex /edieresis /igrave /iacute /icircumflex + /idieresis + /eth /ntilde /ograve /oacute /ocircumflex /otilde /odieresis /divide + /oslash /ugrave /uacute /ucircumflex /udieresis /yacute /thorn + /ydieresis + ] def +} if + +% font ISOEncode font +% This procedure changes the encoding of a font from the default +% Postscript encoding to ISOLatin1. It's typically invoked just +% before invoking "setfont". The body of this procedure comes from +% Section 5.6.1 of the Postscript book. + +/ISOEncode { + dup length dict begin + {1 index /FID ne {def} {pop pop} ifelse} forall + /Encoding ISOLatin1Encoding def + currentdict + end + + % I'm not sure why it's necessary to use "definefont" on this new + % font, but it seems to be important; just use the name "Temporary" + % for the font. + + /Temporary exch definefont +} bind def + +% StrokeClip +% +% This procedure converts the current path into a clip area under +% the assumption of stroking. It's a bit tricky because some Postscript +% interpreters get errors during strokepath for dashed lines. If +% this happens then turn off dashes and try again. + +/StrokeClip { + {strokepath} stopped { + (This Postscript printer gets limitcheck overflows when) = + (stippling dashed lines; lines will be printed solid instead.) = + [] 0 setdash strokepath} if + clip +} bind def + +% desiredSize EvenPixels closestSize +% +% The procedure below is used for stippling. Given the optimal size +% of a dot in a stipple pattern in the current user coordinate system, +% compute the closest size that is an exact multiple of the device's +% pixel size. This allows stipple patterns to be displayed without +% aliasing effects. + +/EvenPixels { + % Compute exact number of device pixels per stipple dot. + dup 0 matrix currentmatrix dtransform + dup mul exch dup mul add sqrt + + % Round to an integer, make sure the number is at least 1, and compute + % user coord distance corresponding to this. + dup round dup 1 lt {pop 1} if + exch div mul +} bind def + +% width height string StippleFill -- +% +% Given a path already set up and a clipping region generated from +% it, this procedure will fill the clipping region with a stipple +% pattern. "String" contains a proper image description of the +% stipple pattern and "width" and "height" give its dimensions. Each +% stipple dot is assumed to be about one unit across in the current +% user coordinate system. This procedure trashes the graphics state. + +/StippleFill { + % The following code is needed to work around a NeWSprint bug. + + /tmpstip 1 index def + + % Change the scaling so that one user unit in user coordinates + % corresponds to the size of one stipple dot. + 1 EvenPixels dup scale + + % Compute the bounding box occupied by the path (which is now + % the clipping region), and round the lower coordinates down + % to the nearest starting point for the stipple pattern. Be + % careful about negative numbers, since the rounding works + % differently on them. + + pathbbox + 4 2 roll + 5 index div dup 0 lt {1 sub} if cvi 5 index mul 4 1 roll + 6 index div dup 0 lt {1 sub} if cvi 6 index mul 3 2 roll + + % Stack now: width height string y1 y2 x1 x2 + % Below is a doubly-nested for loop to iterate across this area + % in units of the stipple pattern size, going up columns then + % across rows, blasting out a stipple-pattern-sized rectangle at + % each position + + 6 index exch { + 2 index 5 index 3 index { + % Stack now: width height string y1 y2 x y + + gsave + 1 index exch translate + 5 index 5 index true matrix tmpstip imagemask + grestore + } for + pop + } for + pop pop pop pop pop +} bind def + +% -- AdjustColor -- +% Given a color value already set for output by the caller, adjusts +% that value to a grayscale or mono value if requested by the CL +% variable. + +/AdjustColor { + CL 2 lt { + currentgray + CL 0 eq { + .5 lt {0} {1} ifelse + } if + setgray + } if +} bind def + +% x y strings spacing xoffset yoffset justify stipple DrawText -- +% This procedure does all of the real work of drawing text. The +% color and font must already have been set by the caller, and the +% following arguments must be on the stack: +% +% x, y - Coordinates at which to draw text. +% strings - An array of strings, one for each line of the text item, +% in order from top to bottom. +% spacing - Spacing between lines. +% xoffset - Horizontal offset for text bbox relative to x and y: 0 for +% nw/w/sw anchor, -0.5 for n/center/s, and -1.0 for ne/e/se. +% yoffset - Vertical offset for text bbox relative to x and y: 0 for +% nw/n/ne anchor, +0.5 for w/center/e, and +1.0 for sw/s/se. +% justify - 0 for left justification, 0.5 for center, 1 for right justify. +% stipple - Boolean value indicating whether or not text is to be +% drawn in stippled fashion. If text is stippled, +% procedure StippleText must have been defined to call +% StippleFill in the right way. +% +% Also, when this procedure is invoked, the color and font must already +% have been set for the text. + +/DrawText { + /stipple exch def + /justify exch def + /yoffset exch def + /xoffset exch def + /spacing exch def + /strings exch def + + % First scan through all of the text to find the widest line. + + /lineLength 0 def + strings { + stringwidth pop + dup lineLength gt {/lineLength exch def} {pop} ifelse + newpath + } forall + + % Compute the baseline offset and the actual font height. + + 0 0 moveto (TXygqPZ) false charpath + pathbbox dup /baseline exch def + exch pop exch sub /height exch def pop + newpath + + % Translate coordinates first so that the origin is at the upper-left + % corner of the text's bounding box. Remember that x and y for + % positioning are still on the stack. + + translate + lineLength xoffset mul + strings length 1 sub spacing mul height add yoffset mul translate + + % Now use the baseline and justification information to translate so + % that the origin is at the baseline and positioning point for the + % first line of text. + + justify lineLength mul baseline neg translate + + % Iterate over each of the lines to output it. For each line, + % compute its width again so it can be properly justified, then + % display it. + + strings { + dup stringwidth pop + justify neg mul 0 moveto + stipple { + + % The text is stippled, so turn it into a path and print + % by calling StippledText, which in turn calls StippleFill. + % Unfortunately, many Postscript interpreters will get + % overflow errors if we try to do the whole string at + % once, so do it a character at a time. + + gsave + /char (X) def + { + char 0 3 -1 roll put + currentpoint + gsave + char true charpath clip StippleText + grestore + char stringwidth translate + moveto + } forall + grestore + } {show} ifelse + 0 spacing neg translate + } forall +} bind def + +%%EndProlog diff --git a/generic/tk.h b/generic/tk.h index 3e470f0..ac48a9c 100644 --- a/generic/tk.h +++ b/generic/tk.h @@ -6,12 +6,12 @@ * * Copyright (c) 1989-1994 The Regents of the University of California. * Copyright (c) 1994 The Australian National University. - * Copyright (c) 1994-1997 Sun Microsystems, Inc. + * Copyright (c) 1994-1998 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.h 1.211 97/11/20 12:44:45 + * SCCS: @(#) tk.h 1.217 98/02/18 18:33:32 */ #ifndef _TK @@ -25,6 +25,7 @@ * win/makefile.bc * win/makefile.vc * library/tk.tcl + * README, win/README, unix/README, and mac/README * * The release level should be 0 for alpha, 1 for beta, and 2 for * final/patch. The release serial value is the number that follows the @@ -38,12 +39,12 @@ */ #define TK_MAJOR_VERSION 8 -#define TK_MINOR_VERSION 0 -#define TK_RELEASE_LEVEL 2 +#define TK_MINOR_VERSION 1 +#define TK_RELEASE_LEVEL 0 #define TK_RELEASE_SERIAL 2 -#define TK_VERSION "8.0" -#define TK_PATCH_LEVEL "8.0p2" +#define TK_VERSION "8.1" +#define TK_PATCH_LEVEL "8.1a2" /* * A special definition used to allow this header file to be included @@ -97,6 +98,7 @@ typedef struct Tk_ErrorHandler_ *Tk_ErrorHandler; typedef struct Tk_Font_ *Tk_Font; typedef struct Tk_Image__ *Tk_Image; typedef struct Tk_ImageMaster_ *Tk_ImageMaster; +typedef struct Tk_OptionTable_ *Tk_OptionTable; typedef struct Tk_TextLayout_ *Tk_TextLayout; typedef struct Tk_Window_ *Tk_Window; typedef struct Tk_3DBorder_ *Tk_3DBorder; @@ -108,54 +110,164 @@ typedef struct Tk_3DBorder_ *Tk_3DBorder; typedef char *Tk_Uid; /* - * Structure used to specify how to handle argv options. + * The enum below defines the valid types for Tk configuration options + * as implemented by Tk_InitOptions, Tk_SetOptions, etc. */ -typedef struct { - char *key; /* The key string that flags the option in the - * argv array. */ - int type; /* Indicates option type; see below. */ - char *src; /* Value to be used in setting dst; usage - * depends on type. */ - char *dst; /* Address of value to be modified; usage - * depends on type. */ - char *help; /* Documentation message describing this option. */ -} Tk_ArgvInfo; +typedef enum { + TK_OPTION_BOOLEAN, + TK_OPTION_INT, + TK_OPTION_DOUBLE, + TK_OPTION_STRING, + TK_OPTION_STRING_TABLE, + TK_OPTION_COLOR, + TK_OPTION_FONT, + TK_OPTION_BITMAP, + TK_OPTION_BORDER, + TK_OPTION_RELIEF, + TK_OPTION_CURSOR, + TK_OPTION_JUSTIFY, + TK_OPTION_ANCHOR, + TK_OPTION_SYNONYM, + TK_OPTION_PIXELS, + TK_OPTION_WINDOW, + TK_OPTION_END +} Tk_OptionType; /* - * Legal values for the type field of a Tk_ArgvInfo: see the user - * documentation for details. + * Structures of the following type are used by widgets to specify + * their configuration options. Typically each widget has a static + * array of these structures, where each element of the array describes + * a single configuration option. The array is passed to + * Tk_CreateOptionTable. */ -#define TK_ARGV_CONSTANT 15 -#define TK_ARGV_INT 16 -#define TK_ARGV_STRING 17 -#define TK_ARGV_UID 18 -#define TK_ARGV_REST 19 -#define TK_ARGV_FLOAT 20 -#define TK_ARGV_FUNC 21 -#define TK_ARGV_GENFUNC 22 -#define TK_ARGV_HELP 23 -#define TK_ARGV_CONST_OPTION 24 -#define TK_ARGV_OPTION_VALUE 25 -#define TK_ARGV_OPTION_NAME_VALUE 26 -#define TK_ARGV_END 27 +typedef struct Tk_OptionSpec { + Tk_OptionType type; /* Type of option, such as TK_OPTION_COLOR; + * see definitions above. Last option in + * table must have type TK_OPTION_END. */ + char *optionName; /* Name used to specify option in Tcl + * commands. */ + char *dbName; /* Name for option in option database. */ + char *dbClass; /* Class for option in database. */ + char *defValue; /* Default value for option if not specified + * in command line, the option database, + * or the system. */ + int objOffset; /* Where in record to store a Tcl_Obj * that + * holds the value of this option, specified + * as an offset in bytes from the start of + * the record. Use the Tk_Offset macro to + * generate values for this. -1 means don't + * store the Tcl_Obj in the record. */ + int internalOffset; /* Where in record to store the internal + * representation of the value of this option, + * such as an int or XColor *. This field + * is specified as an offset in bytes + * from the start of the record. Use the + * Tk_Offset macro to generate values for it. + * -1 means don't store the internal + * representation in the record. */ + int flags; /* Any combination of the values defined + * below. */ + ClientData clientData; /* An alternate place to put option-specific + * data. Used for the monochrome default value + * for colors, etc. */ + int typeMask; /* An arbitrary bit mask defined by the + * class manager; typically bits correspond + * to certain kinds of options such as all + * those that require a redisplay when they + * change. Tk_SetOptions returns the bit-wise + * OR of the typeMasks of all options that + * were changed. */ +} Tk_OptionSpec; /* - * Flag bits for passing to Tk_ParseArgv: + * Flag values for Tk_OptionSpec structures. These flags are shared by + * Tk_ConfigSpec structures, so be sure to coordinate any changes + * carefully. */ -#define TK_ARGV_NO_DEFAULTS 0x1 -#define TK_ARGV_NO_LEFTOVERS 0x2 -#define TK_ARGV_NO_ABBREV 0x4 -#define TK_ARGV_DONT_SKIP_FIRST_ARG 0x8 +#define TK_OPTION_NULL_OK 1 + +/* + * Macro to use to fill in "offset" fields of Tk_OptionSpecs. + * Computes number of bytes from beginning of structure to a + * given field. + */ + +#ifdef offsetof +#define Tk_Offset(type, field) ((int) offsetof(type, field)) +#else +#define Tk_Offset(type, field) ((int) ((char *) &((type *) 0)->field)) +#endif + +/* + * The following two structures are used for error handling. When + * configuration options are being modified, the old values are + * saved in a Tk_SavedOptions structure. If an error occurs, then the + * contents of the structure can be used to restore all of the old + * values. The contents of this structure are for the private use + * Tk. No-one outside Tk should ever read or write any of the fields + * of these structures. + */ + +typedef struct Tk_SavedOption { + struct TkOption *optionPtr; /* Points to information that describes + * the option. */ + Tcl_Obj *valuePtr; /* The old value of the option, in + * the form of a Tcl object; may be + * NULL if the value wasn't saved as + * an object. */ + double internalForm; /* The old value of the option, in + * some internal representation such + * as an int or (XColor *). Valid + * only if optionPtr->specPtr->objOffset + * is < 0. The space must be large + * enough to accommodate a double, a + * long, or a pointer; right now it + * looks like a double is big + * enough. Also, using a double + * guarantees that the field is + * properly aligned for storing large + * values. */ +} Tk_SavedOption; + +#ifdef TCL_MEM_DEBUG +# define TK_NUM_SAVED_OPTIONS 2 +#else +# define TK_NUM_SAVED_OPTIONS 20 +#endif + +typedef struct Tk_SavedOptions { + char *recordPtr; /* The data structure in which to + * restore configuration options. */ + Tk_Window tkwin; /* Window associated with recordPtr; + * needed to restore certain options. */ + int numItems; /* The number of valid items in + * items field. */ + Tk_SavedOption items[TK_NUM_SAVED_OPTIONS]; + /* Items used to hold old values. */ + struct Tk_SavedOptions *nextPtr; /* Points to next structure in list; + * needed if too many options changed + * to hold all the old values in a + * single structure. NULL means no + * more structures. */ +} Tk_SavedOptions; /* * Structure used to describe application-specific configuration * options: indicates procedures to call to parse an option and - * to return a text string describing an option. + * to return a text string describing an option. THESE ARE + * DEPRECATED; PLEASE USE THE NEW STRUCTURES LISTED ABOVE. */ +/* + * This is a temporary flag used while tkObjConfig and new widgets + * are in development. + */ + +#ifndef __NO_OLD_CONFIG + typedef int (Tk_OptionParseProc) _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, Tk_Window tkwin, char *value, char *widgRec, int offset)); @@ -209,40 +321,15 @@ typedef struct Tk_ConfigSpec { * documentation for details. */ -#define TK_CONFIG_BOOLEAN 1 -#define TK_CONFIG_INT 2 -#define TK_CONFIG_DOUBLE 3 -#define TK_CONFIG_STRING 4 -#define TK_CONFIG_UID 5 -#define TK_CONFIG_COLOR 6 -#define TK_CONFIG_FONT 7 -#define TK_CONFIG_BITMAP 8 -#define TK_CONFIG_BORDER 9 -#define TK_CONFIG_RELIEF 10 -#define TK_CONFIG_CURSOR 11 -#define TK_CONFIG_ACTIVE_CURSOR 12 -#define TK_CONFIG_JUSTIFY 13 -#define TK_CONFIG_ANCHOR 14 -#define TK_CONFIG_SYNONYM 15 -#define TK_CONFIG_CAP_STYLE 16 -#define TK_CONFIG_JOIN_STYLE 17 -#define TK_CONFIG_PIXELS 18 -#define TK_CONFIG_MM 19 -#define TK_CONFIG_WINDOW 20 -#define TK_CONFIG_CUSTOM 21 -#define TK_CONFIG_END 22 - -/* - * Macro to use to fill in "offset" fields of Tk_ConfigInfos. - * Computes number of bytes from beginning of structure to a - * given field. - */ - -#ifdef offsetof -#define Tk_Offset(type, field) ((int) offsetof(type, field)) -#else -#define Tk_Offset(type, field) ((int) ((char *) &((type *) 0)->field)) -#endif +typedef enum { + TK_CONFIG_BOOLEAN, TK_CONFIG_INT, TK_CONFIG_DOUBLE, TK_CONFIG_STRING, + TK_CONFIG_UID, TK_CONFIG_COLOR, TK_CONFIG_FONT, TK_CONFIG_BITMAP, + TK_CONFIG_BORDER, TK_CONFIG_RELIEF, TK_CONFIG_CURSOR, + TK_CONFIG_ACTIVE_CURSOR, TK_CONFIG_JUSTIFY, TK_CONFIG_ANCHOR, + TK_CONFIG_SYNONYM, TK_CONFIG_CAP_STYLE, TK_CONFIG_JOIN_STYLE, + TK_CONFIG_PIXELS, TK_CONFIG_MM, TK_CONFIG_WINDOW, TK_CONFIG_CUSTOM, + TK_CONFIG_END +} Tk_ConfigTypes; /* * Possible values for flags argument to Tk_ConfigureWidget: @@ -251,18 +338,62 @@ typedef struct Tk_ConfigSpec { #define TK_CONFIG_ARGV_ONLY 1 /* - * Possible flag values for Tk_ConfigInfo structures. Any bits at + * Possible flag values for Tk_ConfigSpec structures. Any bits at * or above TK_CONFIG_USER_BIT may be used by clients for selecting * certain entries. Before changing any values here, coordinate with - * tkConfig.c (internal-use-only flags are defined there). + * tkOldConfig.c (internal-use-only flags are defined there). */ -#define TK_CONFIG_COLOR_ONLY 1 -#define TK_CONFIG_MONO_ONLY 2 -#define TK_CONFIG_NULL_OK 4 +#define TK_CONFIG_NULL_OK 1 +#define TK_CONFIG_COLOR_ONLY 2 +#define TK_CONFIG_MONO_ONLY 4 #define TK_CONFIG_DONT_SET_DEFAULT 8 #define TK_CONFIG_OPTION_SPECIFIED 0x10 #define TK_CONFIG_USER_BIT 0x100 +#endif /* __NO_OLD_CONFIG */ + +/* + * Structure used to specify how to handle argv options. + */ + +typedef struct { + char *key; /* The key string that flags the option in the + * argv array. */ + int type; /* Indicates option type; see below. */ + char *src; /* Value to be used in setting dst; usage + * depends on type. */ + char *dst; /* Address of value to be modified; usage + * depends on type. */ + char *help; /* Documentation message describing this option. */ +} Tk_ArgvInfo; + +/* + * Legal values for the type field of a Tk_ArgvInfo: see the user + * documentation for details. + */ + +#define TK_ARGV_CONSTANT 15 +#define TK_ARGV_INT 16 +#define TK_ARGV_STRING 17 +#define TK_ARGV_UID 18 +#define TK_ARGV_REST 19 +#define TK_ARGV_FLOAT 20 +#define TK_ARGV_FUNC 21 +#define TK_ARGV_GENFUNC 22 +#define TK_ARGV_HELP 23 +#define TK_ARGV_CONST_OPTION 24 +#define TK_ARGV_OPTION_VALUE 25 +#define TK_ARGV_OPTION_NAME_VALUE 26 +#define TK_ARGV_END 27 + +/* + * Flag bits for passing to Tk_ParseArgv: + */ + +#define TK_ARGV_NO_DEFAULTS 0x1 +#define TK_ARGV_NO_LEFTOVERS 0x2 +#define TK_ARGV_NO_ABBREV 0x4 +#define TK_ARGV_DONT_SKIP_FIRST_ARG 0x8 /* * Enumerated type for describing actions to be taken in response @@ -287,12 +418,12 @@ typedef enum { * Relief values returned by Tk_GetRelief: */ -#define TK_RELIEF_RAISED 1 -#define TK_RELIEF_FLAT 2 -#define TK_RELIEF_SUNKEN 4 -#define TK_RELIEF_GROOVE 8 -#define TK_RELIEF_RIDGE 16 -#define TK_RELIEF_SOLID 32 +#define TK_RELIEF_FLAT 0 +#define TK_RELIEF_GROOVE 1 +#define TK_RELIEF_RAISED 2 +#define TK_RELIEF_RIDGE 3 +#define TK_RELIEF_SOLID 4 +#define TK_RELIEF_SUNKEN 5 /* * "Which" argument values for Tk_3DBorderGC: @@ -715,6 +846,8 @@ typedef void Tk_ItemInsertProc _ANSI_ARGS_((Tk_Canvas canvas, typedef void Tk_ItemDCharsProc _ANSI_ARGS_((Tk_Canvas canvas, Tk_Item *itemPtr, int first, int last)); +#ifndef __NO_OLD_CONFIG + typedef struct Tk_ItemType { char *name; /* The name of this type of item, such * as "line". */ @@ -764,6 +897,8 @@ typedef struct Tk_ItemType { * a list. */ } Tk_ItemType; +#endif + /* * The following structure provides information about the selection and * the insertion cursor. It is needed by only a few items, such as @@ -782,16 +917,17 @@ typedef struct Tk_CanvasTextInfo { Tk_Item *selItemPtr; /* Pointer to selected item. NULL means * selection isn't in this canvas. * Writable by items. */ - int selectFirst; /* Index of first selected character. - * Writable by items. */ - int selectLast; /* Index of last selected character. - * Writable by items. */ + int selectFirst; /* Character index of first selected + * character. Writable by items. */ + int selectLast; /* Character index of last selected + * character. Writable by items. */ Tk_Item *anchorItemPtr; /* Item corresponding to "selectAnchor": * not necessarily selItemPtr. Read-only * to items. */ - int selectAnchor; /* Fixed end of selection (i.e. "select to" - * operation will use this as one end of the - * selection). Writable by items. */ + int selectAnchor; /* Character index of fixed end of + * selection (i.e. "select to" operation will + * use this as one end of the selection). + * Writable by items. */ Tk_3DBorder insertBorder; /* Used to draw vertical bar for insertion * cursor. Read-only to items. */ int insertWidth; /* Total width of insertion cursor. Read-only @@ -1043,6 +1179,16 @@ EXTERN void Tk_3DVerticalBevel _ANSI_ARGS_((Tk_Window tkwin, int relief)); EXTERN void Tk_AddOption _ANSI_ARGS_((Tk_Window tkwin, char *name, char *value, int priority)); +EXTERN Pixmap Tk_AllocBitmapFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr)); +EXTERN Tk_3DBorder Tk_Alloc3DBorderFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr)); +EXTERN XColor * Tk_AllocColorFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr)); +EXTERN Tk_Cursor Tk_AllocCursorFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr)); +EXTERN Tk_Font Tk_AllocFontFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr)); EXTERN void Tk_BindEvent _ANSI_ARGS_((Tk_BindingTable bindingTable, XEvent *eventPtr, Tk_Window tkwin, int numObjects, ClientData *objectPtr)); @@ -1095,6 +1241,7 @@ EXTERN int Tk_ClipboardAppend _ANSI_ARGS_((Tcl_Interp *interp, char* buffer)); EXTERN int Tk_ClipboardClear _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin)); +#ifndef __NO_OLD_CONFIG EXTERN int Tk_ConfigureInfo _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, Tk_ConfigSpec *specs, char *widgRec, char *argvName, int flags)); @@ -1105,6 +1252,7 @@ EXTERN int Tk_ConfigureWidget _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, Tk_ConfigSpec *specs, int argc, char **argv, char *widgRec, int flags)); +#endif EXTERN void Tk_ConfigureWindow _ANSI_ARGS_((Tk_Window tkwin, unsigned int valueMask, XWindowChanges *valuePtr)); EXTERN Tk_TextLayout Tk_ComputeTextLayout _ANSI_ARGS_((Tk_Font font, @@ -1127,7 +1275,11 @@ EXTERN void Tk_CreateGenericHandler _ANSI_ARGS_(( Tk_GenericProc *proc, ClientData clientData)); EXTERN void Tk_CreateImageType _ANSI_ARGS_(( Tk_ImageType *typePtr)); +#ifndef __NO_OLD_CONFIG EXTERN void Tk_CreateItemType _ANSI_ARGS_((Tk_ItemType *typePtr)); +#endif +EXTERN Tk_OptionTable Tk_CreateOptionTable _ANSI_ARGS_((Tcl_Interp *interp, + CONST Tk_OptionSpec *templatePtr)); EXTERN void Tk_CreatePhotoImageFormat _ANSI_ARGS_(( Tk_PhotoImageFormat *formatPtr)); EXTERN void Tk_CreateSelHandler _ANSI_ARGS_((Tk_Window tkwin, @@ -1160,6 +1312,8 @@ EXTERN void Tk_DeleteGenericHandler _ANSI_ARGS_(( Tk_GenericProc *proc, ClientData clientData)); EXTERN void Tk_DeleteImage _ANSI_ARGS_((Tcl_Interp *interp, char *name)); +EXTERN void Tk_DeleteOptionTable _ANSI_ARGS_(( + Tk_OptionTable optionTable)); EXTERN void Tk_DeleteSelHandler _ANSI_ARGS_((Tk_Window tkwin, Atom selection, Atom target)); EXTERN void Tk_DestroyWindow _ANSI_ARGS_((Tk_Window tkwin)); @@ -1195,18 +1349,34 @@ EXTERN Tk_PhotoHandle Tk_FindPhoto _ANSI_ARGS_((Tcl_Interp *interp, char *imageName)); EXTERN Font Tk_FontId _ANSI_ARGS_((Tk_Font font)); EXTERN void Tk_Free3DBorder _ANSI_ARGS_((Tk_3DBorder border)); +EXTERN void Tk_Free3DBorderFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_FreeBitmap _ANSI_ARGS_((Display *display, Pixmap bitmap)); +EXTERN void Tk_FreeBitmapFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_FreeColor _ANSI_ARGS_((XColor *colorPtr)); +EXTERN void Tk_FreeColorFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_FreeColormap _ANSI_ARGS_((Display *display, Colormap colormap)); +EXTERN void Tk_FreeConfigOptions _ANSI_ARGS_((char *recordPtr, + Tk_OptionTable optionToken, Tk_Window tkwin)); +EXTERN void Tk_FreeSavedOptions _ANSI_ARGS_(( + Tk_SavedOptions *savePtr)); EXTERN void Tk_FreeCursor _ANSI_ARGS_((Display *display, Tk_Cursor cursor)); -EXTERN void Tk_FreeFont _ANSI_ARGS_((Tk_Font)); +EXTERN void Tk_FreeCursorFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); +EXTERN void Tk_FreeFont _ANSI_ARGS_((Tk_Font tkfont)); +EXTERN void Tk_FreeFontFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_FreeGC _ANSI_ARGS_((Display *display, GC gc)); EXTERN void Tk_FreeImage _ANSI_ARGS_((Tk_Image image)); +#ifndef __NO_OLD_CONFIG EXTERN void Tk_FreeOptions _ANSI_ARGS_((Tk_ConfigSpec *specs, char *widgRec, Display *display, int needFlags)); +#endif EXTERN void Tk_FreePixmap _ANSI_ARGS_((Display *display, Pixmap pixmap)); EXTERN void Tk_FreeTextLayout _ANSI_ARGS_(( @@ -1217,41 +1387,58 @@ EXTERN GC Tk_GCForColor _ANSI_ARGS_((XColor *colorPtr, EXTERN void Tk_GeometryRequest _ANSI_ARGS_((Tk_Window tkwin, int reqWidth, int reqHeight)); EXTERN Tk_3DBorder Tk_Get3DBorder _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window tkwin, Tk_Uid colorName)); + Tk_Window tkwin, char *colorName)); +EXTERN Tk_3DBorder Tk_Get3DBorderFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_GetAllBindings _ANSI_ARGS_((Tcl_Interp *interp, Tk_BindingTable bindingTable, ClientData object)); EXTERN int Tk_GetAnchor _ANSI_ARGS_((Tcl_Interp *interp, char *string, Tk_Anchor *anchorPtr)); +EXTERN int Tk_GetAnchorFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tcl_Obj *objPtr, Tk_Anchor *anchorPtr)); EXTERN char * Tk_GetAtomName _ANSI_ARGS_((Tk_Window tkwin, Atom atom)); EXTERN char * Tk_GetBinding _ANSI_ARGS_((Tcl_Interp *interp, Tk_BindingTable bindingTable, ClientData object, char *eventString)); EXTERN Pixmap Tk_GetBitmap _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window tkwin, Tk_Uid string)); + Tk_Window tkwin, char *string)); EXTERN Pixmap Tk_GetBitmapFromData _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, char *source, int width, int height)); +EXTERN Pixmap Tk_GetBitmapFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN int Tk_GetCapStyle _ANSI_ARGS_((Tcl_Interp *interp, char *string, int *capPtr)); EXTERN XColor * Tk_GetColor _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window tkwin, Tk_Uid name)); + Tk_Window tkwin, char *name)); EXTERN XColor * Tk_GetColorByValue _ANSI_ARGS_((Tk_Window tkwin, XColor *colorPtr)); +EXTERN XColor * Tk_GetColorFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN Colormap Tk_GetColormap _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, char *string)); EXTERN Tk_Cursor Tk_GetCursor _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window tkwin, Tk_Uid string)); + Tk_Window tkwin, char *string)); EXTERN Tk_Cursor Tk_GetCursorFromData _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, char *source, char *mask, int width, int height, int xHot, int yHot, Tk_Uid fg, Tk_Uid bg)); +EXTERN Tk_Cursor Tk_GetCursorFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN Tk_Font Tk_GetFont _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, CONST char *string)); -EXTERN Tk_Font Tk_GetFontFromObj _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window tkwin, Tcl_Obj *objPtr)); +EXTERN Tk_Font Tk_GetFontFromObj _ANSI_ARGS_((Tk_Window tkwin, + Tcl_Obj *objPtr)); EXTERN void Tk_GetFontMetrics _ANSI_ARGS_((Tk_Font font, Tk_FontMetrics *fmPtr)); +EXTERN Tcl_Obj * Tk_GetOptionInfo _ANSI_ARGS_((Tcl_Interp *interp, + char *recordPtr, Tk_OptionTable optionTable, + Tcl_Obj *namePtr, Tk_Window tkwin)); +EXTERN Tcl_Obj * Tk_GetOptionValue _ANSI_ARGS_(( + Tcl_Interp *interp, char *recordPtr, + Tk_OptionTable optionTable, Tcl_Obj *namePtr, + Tk_Window tkwin)); EXTERN GC Tk_GetGC _ANSI_ARGS_((Tk_Window tkwin, unsigned long valueMask, XGCValues *valuePtr)); EXTERN Tk_Image Tk_GetImage _ANSI_ARGS_((Tcl_Interp *interp, @@ -1260,20 +1447,31 @@ EXTERN Tk_Image Tk_GetImage _ANSI_ARGS_((Tcl_Interp *interp, ClientData clientData)); EXTERN ClientData Tk_GetImageMasterData _ANSI_ARGS_ ((Tcl_Interp *interp, char *name, Tk_ImageType **typePtrPtr)); +#ifndef __NO_OLD_CONFIG EXTERN Tk_ItemType * Tk_GetItemTypes _ANSI_ARGS_((void)); +#endif EXTERN int Tk_GetJoinStyle _ANSI_ARGS_((Tcl_Interp *interp, char *string, int *joinPtr)); EXTERN int Tk_GetJustify _ANSI_ARGS_((Tcl_Interp *interp, char *string, Tk_Justify *justifyPtr)); +EXTERN int Tk_GetJustifyFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tcl_Obj *objPtr, Tk_Justify *justifyPtr)); +EXTERN int Tk_GetMMFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr, + double *doublePtr)); EXTERN int Tk_GetNumMainWindows _ANSI_ARGS_((void)); EXTERN Tk_Uid Tk_GetOption _ANSI_ARGS_((Tk_Window tkwin, char *name, char *className)); EXTERN int Tk_GetPixels _ANSI_ARGS_((Tcl_Interp *interp, Tk_Window tkwin, char *string, int *intPtr)); +EXTERN int Tk_GetPixelsFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window tkwin, Tcl_Obj *objPtr, int *intPtr)); EXTERN Pixmap Tk_GetPixmap _ANSI_ARGS_((Display *display, Drawable d, int width, int height, int depth)); EXTERN int Tk_GetRelief _ANSI_ARGS_((Tcl_Interp *interp, char *name, int *reliefPtr)); +EXTERN int Tk_GetReliefFromObj _ANSI_ARGS_((Tcl_Interp *interp, + Tcl_Obj *objPtr, int *resultPtr)); EXTERN void Tk_GetRootCoords _ANSI_ARGS_ ((Tk_Window tkwin, int *xPtr, int *yPtr)); EXTERN int Tk_GetScrollInfo _ANSI_ARGS_((Tcl_Interp *interp, @@ -1301,6 +1499,9 @@ EXTERN void Tk_ImageChanged _ANSI_ARGS_(( int width, int height, int imageWidth, int imageHeight)); EXTERN int Tk_Init _ANSI_ARGS_((Tcl_Interp *interp)); +EXTERN int Tk_InitOptions _ANSI_ARGS_(( + Tcl_Interp *interp, char *recordPtr, + Tk_OptionTable optionToken, Tk_Window tkwin)); EXTERN Atom Tk_InternAtom _ANSI_ARGS_((Tk_Window tkwin, char *name)); EXTERN int Tk_IntersectTextLayout _ANSI_ARGS_(( @@ -1376,6 +1577,8 @@ EXTERN void Tk_QueueWindowEvent _ANSI_ARGS_((XEvent *eventPtr, EXTERN void Tk_RedrawImage _ANSI_ARGS_((Tk_Image image, int imageX, int imageY, int width, int height, Drawable drawable, int drawableX, int drawableY)); +EXTERN void Tk_RestoreSavedOptions _ANSI_ARGS_(( + Tk_SavedOptions *savePtr)); EXTERN void Tk_ResizeWindow _ANSI_ARGS_((Tk_Window tkwin, int width, int height)); EXTERN int Tk_RestackWindow _ANSI_ARGS_((Tk_Window tkwin, @@ -1389,6 +1592,11 @@ EXTERN void Tk_SetBackgroundFromBorder _ANSI_ARGS_(( Tk_Window tkwin, Tk_3DBorder border)); EXTERN void Tk_SetClass _ANSI_ARGS_((Tk_Window tkwin, char *className)); +EXTERN int Tk_SetOptions _ANSI_ARGS_(( + Tcl_Interp *interp, char *recordPtr, + Tk_OptionTable optionTable, int objc, + Tcl_Obj *CONST objv[], Tk_Window tkwin, + Tk_SavedOptions *savePtr, int *maskPtr)); EXTERN void Tk_SetGrid _ANSI_ARGS_((Tk_Window tkwin, int reqWidth, int reqHeight, int gridWidth, int gridHeight)); @@ -1442,61 +1650,73 @@ EXTERN void Tk_UpdatePointer _ANSI_ARGS_((Tk_Window tkwin, EXTERN int Tk_AfterCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_BellCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_BellObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_BindCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_BindtagsCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_ButtonCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_ButtonObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_CanvasCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_CheckbuttonCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_CheckbuttonObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_ClipboardCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_ChooseColorCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_ChooseFontCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_ChooseColorObjCmd _ANSI_ARGS_(( + ClientData clientData, Tcl_Interp *interp, + int objc, Tcl_Obj *CONST objv[])); +EXTERN int Tk_ChooseDirectoryObjCmd _ANSI_ARGS_(( + ClientData clientData, Tcl_Interp *interp, + int objc, Tcl_Obj *CONST objv[])); +EXTERN int Tk_ChooseFontObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_DestroyCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_EntryCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_EventCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_EventObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_FileeventCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_FrameCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_FocusCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_FocusObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_FontObjCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int objc, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); +EXTERN int Tk_GetOpenFileObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); +EXTERN int Tk_GetSaveFileObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[])); -EXTERN int Tk_GetOpenFileCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_GetSaveFileCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_GrabCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_GridCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_ImageCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_LabelCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_LabelObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_ListboxCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_LowerCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_MenuCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_MenubuttonCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_MessageBoxCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_MessageBoxObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_MessageCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_OptionCmd _ANSI_ARGS_((ClientData clientData, @@ -1505,8 +1725,9 @@ EXTERN int Tk_PackCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_PlaceCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_RadiobuttonCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_RadiobuttonObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_RaiseCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_ScaleCmd _ANSI_ARGS_((ClientData clientData, @@ -1517,6 +1738,9 @@ EXTERN int Tk_SelectionCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_SendCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_SendObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_TextCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_TkObjCmd _ANSI_ARGS_((ClientData clientData, @@ -1526,8 +1750,9 @@ EXTERN int Tk_TkwaitCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); EXTERN int Tk_ToplevelCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int argc, char **argv)); -EXTERN int Tk_UpdateCmd _ANSI_ARGS_((ClientData clientData, - Tcl_Interp *interp, int argc, char **argv)); +EXTERN int Tk_UpdateObjCmd _ANSI_ARGS_((ClientData clientData, + Tcl_Interp *interp, int objc, + Tcl_Obj *CONST objv[])); EXTERN int Tk_WinfoObjCmd _ANSI_ARGS_((ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[])); diff --git a/generic/tk3d.c b/generic/tk3d.c index 53eec8b..36399cc 100644 --- a/generic/tk3d.c +++ b/generic/tk3d.c @@ -10,36 +10,162 @@ * See the file "license.terms" for information on usage and redistribution * of this file, and for a DISCLAIMER OF ALL WARRANTIES. * - * SCCS: @(#) tk3d.c 1.60 97/01/13 17:23:10 + * SCCS: @(#) tk3d.c 1.67 97/12/24 15:50:00 */ -#include +#include "tk3d.h" /* - * Hash table to map from a border's values (color, etc.) to a - * Border structure for those values. + * Hash table to map from a string color name to a TkBorder structure + * that can be used to draw borders with that color. */ static Tcl_HashTable borderTable; -typedef struct { - Tk_Uid colorName; /* Color for border. */ - Colormap colormap; /* Colormap used for allocating border - * colors. */ - Screen *screen; /* Screen on which border will be drawn. */ -} BorderKey; static int initialized = 0; /* 0 means static structures haven't * been initialized yet. */ +/* + * The following table defines the string values for reliefs, which are + * used by Tk_GetReliefFromObj. + */ + +static char *reliefStrings[] = {"flat", "groove", "raised", "ridge", "solid", + "sunken", (char *) NULL}; /* * Forward declarations for procedures defined in this file: */ static void BorderInit _ANSI_ARGS_((void)); +static void DupBorderObjProc _ANSI_ARGS_((Tcl_Obj *srcObjPtr, + Tcl_Obj *dupObjPtr)); +static void FreeBorderObjProc _ANSI_ARGS_((Tcl_Obj *objPtr)); static int Intersect _ANSI_ARGS_((XPoint *a1Ptr, XPoint *a2Ptr, XPoint *b1Ptr, XPoint *b2Ptr, XPoint *iPtr)); +static void InitBorderObj _ANSI_ARGS_((Tcl_Obj *objPtr)); static void ShiftLine _ANSI_ARGS_((XPoint *p1Ptr, XPoint *p2Ptr, int distance, XPoint *p3Ptr)); + +/* + * The following structure defines the implementation of the "border" Tcl + * object, used for drawing. The border object remembers the hash table entry + * associated with a border. The actual allocation and deallocation of the + * border should be done by the configuration package when the border option + * is set. + */ + +static Tcl_ObjType borderObjType = { + "border", /* name */ + FreeBorderObjProc, /* freeIntRepProc */ + DupBorderObjProc, /* dupIntRepProc */ + NULL, /* updateStringProc */ + NULL /* setFromAnyProc */ +}; + +/* + *---------------------------------------------------------------------- + * + * Tk_AllocBorderFromObj -- + * + * Given a Tcl_Obj *, map the value to a corresponding + * Tk_3DBorder structure based on the tkwin given. + * + * Results: + * The return value is a token for a data structure describing a + * 3-D border. This token may be passed to procedures such as + * Tk_Draw3DRectangle and Tk_Free3DBorder. If an error prevented + * the border from being created then NULL is returned and an error + * message will be left in the interp's result. + * + * Side effects: + * The border is added to an internal database with a reference + * count. For each call to this procedure, there should eventually + * be a call to Tk_FreeBorderFromObj so that the database is + * cleaned up when borders aren't in use anymore. + * + *---------------------------------------------------------------------- + */ + +Tk_3DBorder +Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr) + Tcl_Interp *interp; /* Interp for error results. */ + Tk_Window tkwin; /* Need the screen the border is used on.*/ + Tcl_Obj *objPtr; /* Object giving name of color for window + * background. */ +{ + TkBorder *borderPtr; + + if (objPtr->typePtr != &borderObjType) { + InitBorderObj(objPtr); + } + borderPtr = (TkBorder *) objPtr->internalRep.twoPtrValue.ptr1; + + /* + * If the object currently points to a TkBorder, see if it's the + * one we want. If so, increment its reference count and return. + */ + + if (borderPtr != NULL) { + if (borderPtr->resourceRefCount == 0) { + /* + * This is a stale reference: it refers to a border that's + * no longer in use. Clear the reference. + */ + + FreeBorderObjProc(objPtr); + borderPtr = NULL; + } else if ((Tk_Screen(tkwin) == borderPtr->screen) + && (Tk_Colormap(tkwin) == borderPtr->colormap)) { + borderPtr->resourceRefCount++; + return (Tk_3DBorder) borderPtr; + } + } + + /* + * The object didn't point to the border that we wanted. Search + * the list of borders with the same name to see if one of the + * others is the right one. + */ + + /* + * If the cached value is NULL, either the object type was not a + * color going in, or the object is a color type but had + * previously been freed. + * + * If the value is not NULL, the internal rep is the value + * of the color the last time this object was accessed. Check + * the screen and colormap of the last access, and if they + * match, we are done. + */ + + if (borderPtr != NULL) { + TkBorder *firstBorderPtr = + (TkBorder *) Tcl_GetHashValue(borderPtr->hashPtr); + FreeBorderObjProc(objPtr); + for (borderPtr = firstBorderPtr ; borderPtr != NULL; + borderPtr = borderPtr->nextPtr) { + if ((Tk_Screen(tkwin) == borderPtr->screen) + && (Tk_Colormap(tkwin) == borderPtr->colormap)) { + borderPtr->resourceRefCount++; + borderPtr->objRefCount++; + objPtr->internalRep.twoPtrValue.ptr1 = (VOID *) borderPtr; + return (Tk_3DBorder) borderPtr; + } + } + } + + /* + * Still no luck. Call Tk_Get3DBorder to allocate a new border. + */ + + borderPtr = (TkBorder *) Tk_Get3DBorder(interp, tkwin, + Tcl_GetString(objPtr)); + objPtr->internalRep.twoPtrValue.ptr1 = (VOID *) borderPtr; + if (borderPtr != NULL) { + borderPtr->objRefCount++; + } + return (Tk_3DBorder) borderPtr; +} /* *-------------------------------------------------------------- @@ -49,12 +175,11 @@ static void ShiftLine _ANSI_ARGS_((XPoint *p1Ptr, XPoint *p2Ptr, * Create a data structure for displaying a 3-D border. * * Results: - * The return value is a token for a data structure - * describing a 3-D border. This token may be passed - * to Tk_Draw3DRectangle and Tk_Free3DBorder. If an - * error prevented the border from being created then - * NULL is returned and an error message will be left - * in interp->result. + * The return value is a token for a data structure describing a + * 3-D border. This token may be passed to procedures such as + * Tk_Draw3DRectangle and Tk_Free3DBorder. If an error prevented + * the border from being created then NULL is returned and an error + * message will be left in the interp's result. * * Side effects: * Data structures, graphics contexts, etc. are allocated. @@ -69,70 +194,72 @@ Tk_Get3DBorder(interp, tkwin, colorName) Tcl_Interp *interp; /* Place to store an error message. */ Tk_Window tkwin; /* Token for window in which border will * be drawn. */ - Tk_Uid colorName; /* String giving name of color + char *colorName; /* String giving name of color * for window background. */ { - BorderKey key; Tcl_HashEntry *hashPtr; - register TkBorder *borderPtr; + TkBorder *borderPtr, *existingBorderPtr; int new; XGCValues gcValues; + XColor *bgColorPtr; if (!initialized) { BorderInit(); } - /* - * First, check to see if there's already a border that will work - * for this request. - */ - - key.colorName = colorName; - key.colormap = Tk_Colormap(tkwin); - key.screen = Tk_Screen(tkwin); - - hashPtr = Tcl_CreateHashEntry(&borderTable, (char *) &key, &new); + hashPtr = Tcl_CreateHashEntry(&borderTable, colorName, &new); if (!new) { - borderPtr = (TkBorder *) Tcl_GetHashValue(hashPtr); - borderPtr->refCount++; + existingBorderPtr = (TkBorder *) Tcl_GetHashValue(hashPtr); + for (borderPtr = existingBorderPtr; borderPtr != NULL; + borderPtr = borderPtr->nextPtr) { + if ((Tk_Screen(tkwin) == borderPtr->screen) + && (Tk_Colormap(tkwin) == borderPtr->colormap)) { + borderPtr->resourceRefCount++; + return (Tk_3DBorder) borderPtr; + } + } } else { - XColor *bgColorPtr; + existingBorderPtr = NULL; + } - /* - * No satisfactory border exists yet. Initialize a new one. - */ - - bgColorPtr = Tk_GetColor(interp, tkwin, colorName); - if (bgColorPtr == NULL) { + /* + * No satisfactory border exists yet. Initialize a new one. + */ + + bgColorPtr = Tk_GetColor(interp, tkwin, colorName); + if (bgColorPtr == NULL) { + if (new) { Tcl_DeleteHashEntry(hashPtr); - return NULL; } - - borderPtr = TkpGetBorder(); - borderPtr->screen = Tk_Screen(tkwin); - borderPtr->visual = Tk_Visual(tkwin); - borderPtr->depth = Tk_Depth(tkwin); - borderPtr->colormap = key.colormap; - borderPtr->refCount = 1; - borderPtr->bgColorPtr = bgColorPtr; - borderPtr->darkColorPtr = NULL; - borderPtr->lightColorPtr = NULL; - borderPtr->shadow = None; - borderPtr->bgGC = None; - borderPtr->darkGC = None; - borderPtr->lightGC = None; - borderPtr->hashPtr = hashPtr; - Tcl_SetHashValue(hashPtr, borderPtr); - - /* - * Create the information for displaying the background color, - * but delay the allocation of shadows until they are actually - * needed for drawing. - */ - - gcValues.foreground = borderPtr->bgColorPtr->pixel; - borderPtr->bgGC = Tk_GetGC(tkwin, GCForeground, &gcValues); + return NULL; } + + borderPtr = TkpGetBorder(); + borderPtr->screen = Tk_Screen(tkwin); + borderPtr->visual = Tk_Visual(tkwin); + borderPtr->depth = Tk_Depth(tkwin); + borderPtr->colormap = Tk_Colormap(tkwin); + borderPtr->resourceRefCount = 1; + borderPtr->objRefCount = 0; + borderPtr->bgColorPtr = bgColorPtr; + borderPtr->darkColorPtr = NULL; + borderPtr->lightColorPtr = NULL; + borderPtr->shadow = None; + borderPtr->bgGC = None; + borderPtr->darkGC = None; + borderPtr->lightGC = None; + borderPtr->hashPtr = hashPtr; + borderPtr->nextPtr = existingBorderPtr; + Tcl_SetHashValue(hashPtr, borderPtr); + + /* + * Create the information for displaying the background color, + * but delay the allocation of shadows until they are actually + * needed for drawing. + */ + + gcValues.foreground = borderPtr->bgColorPtr->pixel; + borderPtr->bgGC = Tk_GetGC(tkwin, GCForeground, &gcValues); return (Tk_3DBorder) borderPtr; } @@ -208,7 +335,7 @@ Tk_NameOf3DBorder(border) { TkBorder *borderPtr = (TkBorder *) border; - return ((BorderKey *) borderPtr->hashPtr->key.words)->colorName; + return borderPtr->hashPtr->key.string; } /* @@ -303,34 +430,51 @@ void Tk_Free3DBorder(border) Tk_3DBorder border; /* Token for border to be released. */ { - register TkBorder *borderPtr = (TkBorder *) border; + TkBorder *borderPtr = (TkBorder *) border; Display *display = DisplayOfScreen(borderPtr->screen); + TkBorder *prevPtr; - borderPtr->refCount--; - if (borderPtr->refCount == 0) { - TkpFreeBorder(borderPtr); - if (borderPtr->bgColorPtr != NULL) { - Tk_FreeColor(borderPtr->bgColorPtr); - } - if (borderPtr->darkColorPtr != NULL) { - Tk_FreeColor(borderPtr->darkColorPtr); - } - if (borderPtr->lightColorPtr != NULL) { - Tk_FreeColor(borderPtr->lightColorPtr); - } - if (borderPtr->shadow != None) { - Tk_FreeBitmap(display, borderPtr->shadow); - } - if (borderPtr->bgGC != None) { - Tk_FreeGC(display, borderPtr->bgGC); - } - if (borderPtr->darkGC != None) { - Tk_FreeGC(display, borderPtr->darkGC); + borderPtr->resourceRefCount--; + if (borderPtr->resourceRefCount > 0) { + return; + } + + prevPtr = (TkBorder *) Tcl_GetHashValue(borderPtr->hashPtr); + TkpFreeBorder(borderPtr); + if (borderPtr->bgColorPtr != NULL) { + Tk_FreeColor(borderPtr->bgColorPtr); + } + if (borderPtr->darkColorPtr != NULL) { + Tk_FreeColor(borderPtr->darkColorPtr); + } + if (borderPtr->lightColorPtr != NULL) { + Tk_FreeColor(borderPtr->lightColorPtr); + } + if (borderPtr->shadow != None) { + Tk_FreeBitmap(display, borderPtr->shadow); + } + if (borderPtr->bgGC != None) { + Tk_FreeGC(display, borderPtr->bgGC); + } + if (borderPtr->darkGC != None) { + Tk_FreeGC(display, borderPtr->darkGC); + } + if (borderPtr->lightGC != None) { + Tk_FreeGC(display, borderPtr->lightGC); + } + if (prevPtr == borderPtr) { + if (borderPtr->nextPtr == NULL) { + Tcl_DeleteHashEntry(borderPtr->hashPtr); + } else { + Tcl_SetHashValue(borderPtr->hashPtr, borderPtr->nextPtr); } - if (borderPtr->lightGC != None) { - Tk_FreeGC(display, borderPtr->lightGC); + } else { + while (prevPtr->nextPtr != borderPtr) { + prevPtr = prevPtr->nextPtr; } - Tcl_DeleteHashEntry(borderPtr->hashPtr); + prevPtr->nextPtr = borderPtr->nextPtr; + } + if (borderPtr->objRefCount == 0) { ckfree((char *) borderPtr); } } @@ -338,6 +482,105 @@ Tk_Free3DBorder(border) /* *---------------------------------------------------------------------- * + * Tk_Free3DBorderFromObj -- + * + * This procedure is called to release a border allocated by + * Tk_Alloc3DBorderFromObj. It does not throw away the Tcl_Obj *; + * it only gets rid of the hash table entry for this border + * and clears the cached value that is normally stored in the object. + * + * Results: + * None. + * + * Side effects: + * The reference count associated with the border represented by + * objPtr is decremented, and the border's resources are released + * to X if there are no remaining uses for it. + * + *---------------------------------------------------------------------- + */ + +void +Tk_Free3DBorderFromObj(tkwin, objPtr) + Tk_Window tkwin; /* The window this border lives in. Needed + * for the screen and colormap values. */ + Tcl_Obj *objPtr; /* The Tcl_Obj * to be freed. */ +{ + Tk_Free3DBorder(Tk_Get3DBorderFromObj(tkwin, objPtr)); +} + +/* + *--------------------------------------------------------------------------- + * + * FreeBorderObjProc -- + * + * This proc is called to release an object reference to a border. + * Called when the object's internal rep is released or when + * the cached borderPtr needs to be changed. + * + * Results: + * None. + * + * Side effects: + * The object reference count is decremented. When both it + * and the hash ref count go to zero, the border's resources + * are released. + * + *--------------------------------------------------------------------------- + */ + +static void +FreeBorderObjProc(objPtr) + Tcl_Obj *objPtr; /* The object we are releasing. */ +{ + TkBorder *borderPtr = (TkBorder *) objPtr->internalRep.twoPtrValue.ptr1; + + if (borderPtr != NULL) { + borderPtr->objRefCount--; + if ((borderPtr->objRefCount == 0) + && (borderPtr->resourceRefCount == 0)) { + ckfree((char *) borderPtr); + } + objPtr->internalRep.twoPtrValue.ptr1 = (VOID *) NULL; + } +} + +/* + *--------------------------------------------------------------------------- + * + * DupBorderObjProc -- + * + * When a cached border object is duplicated, this is called to + * update the internal reps. + * + * Results: + * None. + * + * Side effects: + * The border's objRefCount is incremented and the internal rep + * of the copy is set to point to it. + * + *--------------------------------------------------------------------------- + */ + +static void +DupBorderObjProc(srcObjPtr, dupObjPtr) + Tcl_Obj *srcObjPtr; /* The object we are copying from. */ + Tcl_Obj *dupObjPtr; /* The object we are copying to. */ +{ + TkBorder *borderPtr = (TkBorder *) srcObjPtr->internalRep.twoPtrValue.ptr1; + + dupObjPtr->typePtr = srcObjPtr->typePtr; + dupObjPtr->internalRep.twoPtrValue.ptr1 = (VOID *) borderPtr; + + if (borderPtr != NULL) { + borderPtr->objRefCount++; + } +} + +/* + *---------------------------------------------------------------------- + * * Tk_SetBackgroundFromBorder -- * * Change the background of a window to one appropriate for a given @@ -365,6 +608,35 @@ Tk_SetBackgroundFromBorder(tkwin, border) /* *---------------------------------------------------------------------- * + * Tk_GetReliefFromObj -- + * + * Return an integer value based on the value of the objPtr. + * + * Results: + * The return value is a standard Tcl result. If an error occurs during + * conversion, an error message is left in the interpreter's result + * unless "interp" is NULL. + * + * Side effects: + * The object gets converted by Tcl_GetIndexFromObj. + * + *---------------------------------------------------------------------- + */ + +int +Tk_GetReliefFromObj(interp, objPtr, resultPtr) + Tcl_Interp *interp; /* Used for error reporting. */ + Tcl_Obj *objPtr; /* The object we are trying to get the + * value from. */ + int *resultPtr; /* Where to place the answer. */ +{ + return Tcl_GetIndexFromObj(interp, objPtr, reliefStrings, "relief", 0, + resultPtr); +} + +/* + *---------------------------------------------------------------------- + * * Tk_GetRelief -- * * Parse a relief description and return the corresponding @@ -407,8 +679,11 @@ Tk_GetRelief(interp, name, reliefPtr) } else if ((c == 's') && (strncmp(name, "sunken", length) == 0)) { *reliefPtr = TK_RELIEF_SUNKEN; } else { - sprintf(interp->result, "bad relief type \"%.50s\": must be %s", + char buf[200]; + + sprintf(buf, "bad relief type \"%.50s\": must be %s", name, "flat, groove, raised, ridge, solid, or sunken"); + Tcl_SetResult(interp, buf, TCL_VOLATILE); return TCL_ERROR; } return TCL_OK; @@ -785,7 +1060,7 @@ static void BorderInit() { initialized = 1; - Tcl_InitHashTable(&borderTable, sizeof(BorderKey)/sizeof(int)); + Tcl_InitHashTable(&borderTable, TCL_STRING_KEYS); } /* @@ -947,3 +1222,167 @@ Intersect(a1Ptr, a2Ptr, b1Ptr, b2Ptr, iPtr) } return 0; } + +/* + *---------------------------------------------------------------------- + * + * Tk_Get3DBorderFromObj -- + * + * Returns the border referred to by a Tcl object. The border must + * already have been allocated via a call to Tk_Alloc3DBorderFromObj + * or Tk_Get3DBorder. + * + * Results: + * Returns the Tk_3DBorder that matches the tkwin and the string rep + * of the name of the border given in objPtr. + * + * Side effects: + * If the object is not already a border, the conversion will free + * any old internal representation. + * + *---------------------------------------------------------------------- + */ + +Tk_3DBorder +Tk_Get3DBorderFromObj(tkwin, objPtr) + Tk_Window tkwin; + Tcl_Obj *objPtr; /* The object whose string value selects + * a border. */ +{ + TkBorder *borderPtr = NULL; + Tcl_HashEntry *hashPtr; + + if (objPtr->typePtr != &borderObjType) { + InitBorderObj(objPtr); + } + + borderPtr = (TkBorder *) objPtr->internalRep.twoPtrValue.ptr1; + if (borderPtr != NULL) { + if ((borderPtr->resourceRefCount > 0) + && (Tk_Screen(tkwin) == borderPtr->screen) + && (Tk_Colormap(tkwin) == borderPtr->colormap)) { + /* + * The object already points to the right border structure. + * Just return it. + */ + + return (Tk_3DBorder) borderPtr; + } + hashPtr = borderPtr->hashPtr; + FreeBorderObjProc(objPtr); + } else { + hashPtr = Tcl_FindHashEntry(&borderTable, Tcl_GetString(objPtr)); + if (hashPtr == NULL) { + goto error; + } + } + + /* + * At this point we've got a hash table entry, off of which hang + * one or more TkBorder structures. See if any of them will work. + */ + + for (borderPtr = (TkBorder *) Tcl_GetHashValue(hashPtr); + (borderPtr != NULL); borderPtr = borderPtr->nextPtr) { + if ((Tk_Screen(tkwin) == borderPtr->screen) + && (Tk_Colormap(tkwin) == borderPtr->colormap)) { + objPtr->internalRep.twoPtrValue.ptr1 = (VOID *) borderPtr; + borderPtr->objRefCount++; + return (Tk_3DBorder) borderPtr; + } + } + + error: + panic("Tk_Get3DBorderFromObj called with non-existent border!"); + /* + * The following code isn't reached; it's just there to please compilers. + */ + return NULL; +} + +/* + *---------------------------------------------------------------------- + * + * InitBorderObj -- + * + * Attempt to generate a border internal form for the Tcl object + * "objPtr". + * + * Results: + * The return value is a standard Tcl result. If an error occurs during + * conversion, an error message is left in the interpreter's result + * unless "interp" is NULL. + * + * Side effects: + * If no error occurs, a blank internal format for a border value + * is intialized. The final form cannot be done without a Tk_Window. + * + *---------------------------------------------------------------------- + */ + +static void +InitBorderObj(objPtr) + Tcl_Obj *objPtr; /* The object to convert. */ +{ + Tcl_ObjType *typePtr; + + /* + * Free the old internalRep before setting the new one. + */ + + Tcl_GetString(objPtr); + typePtr = objPtr->typePtr; + if ((typePtr != NULL) && (typePtr->freeIntRepProc != NULL)) { + (*typePtr->freeIntRepProc)(objPtr); + } + objPtr->typePtr = &borderObjType; + objPtr->internalRep.twoPtrValue.ptr1 = (VOID *) NULL; +} + +/* + *---------------------------------------------------------------------- + * + * TkDebugBorder -- + * + * This procedure returns debugging information about a border. + * + * Results: + * The return value is a list with one sublist for each TkBorder + * corresponding to "name". Each sublist has two elements that + * contain the resourceRefCount and objRefCount fields from the + * TkBorder structure. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +Tcl_Obj * +TkDebugBorder(tkwin, name) + Tk_Window tkwin; /* The window in which the border will be + * used (not currently used). */ + char *name; /* Name of the desired color. */ +{ + TkBorder *borderPtr; + Tcl_HashEntry *hashPtr; + Tcl_Obj *resultPtr, *objPtr; + + resultPtr = Tcl_NewObj(); + hashPtr = Tcl_FindHashEntry(&borderTable, name); + if (hashPtr != NULL) { + borderPtr = (TkBorder *) Tcl_GetHashValue(hashPtr); + if (borderPtr == NULL) { + panic("TkDebugBorder found empty hash table entry"); + } + for ( ; (borderPtr != NULL); borderPtr = borderPtr->nextPtr) { + objPtr = Tcl_NewObj(); + Tcl_ListObjAppendElement(NULL, objPtr, + Tcl_NewIntObj(borderPtr->resourceRefCount)); + Tcl_ListObjAppendElement(NULL, objPtr, + Tcl_NewIntObj(borderPtr->objRefCount)); + Tcl_ListObjAppendElement(NULL, resultPtr, objPtr); + } + } + return resultPtr; +} diff --git a/generic/tk3d.h b/generic/tk3d.h index cd9ecd5..4e17eb3 100644 --- a/generic/tk3d.h +++ b/generic/tk3d.h @@ -4,12 +4,12 @@ * Declarations of types and functions shared by the 3d border * module. * - * Copyright (c) 1996 by Sun Microsystems, Inc. + * Copyright (c) 1996-1997 by 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: @(#) tk3d.h 1.1 96/11/04 13:52:59 + * SCCS: @(#) tk3d.h 1.4 97/12/24 15:50:02 */ #ifndef _TK3D @@ -18,13 +18,13 @@ #include /* - * One of the following data structures is allocated for - * each 3-D border currently in use. Structures of this - * type are indexed by borderTable, so that a single - * structure can be shared for several uses. + * One of the following data structures is allocated for each 3-D border + * currently in use. Structures of this type are indexed by + * borderTable, so that a single structure can be shared for several + * uses. */ -typedef struct { +typedef struct TkBorder { Screen *screen; /* Screen on which the border will be used. */ Visual *visual; /* Visual for all windows and pixmaps using * the border. */ @@ -32,8 +32,18 @@ typedef struct { * the border will be used. */ Colormap colormap; /* Colormap out of which pixels are * allocated. */ - int refCount; /* Number of different users of - * this border. */ + int resourceRefCount; /* Number of active uses of this color (each + * active use corresponds to a call to + * Tk_Alloc3DBorderFromObj or Tk_Get3DBorder). + * If this count is 0, then this structure + * is no longer valid and it isn't present + * in borderTable: it is being kept around + * only because there are objects referring + * to it. The structure is freed when + * resourceRefCount and objRefCount are + * both 0. */ + int objRefCount; /* The number of Tcl objects that reference + * this structure. */ XColor *bgColorPtr; /* Background color (intensity * between lightColorPtr and * darkColorPtr). */ @@ -58,6 +68,11 @@ typedef struct { * haven't been allocated yet. */ Tcl_HashEntry *hashPtr; /* Entry in borderTable (needed in * order to delete structure). */ + struct TkBorder *nextPtr; /* Points to the next TkBorder structure with + * the same color name. Borders with the + * same name but different screens or + * colormaps are chained together off a + * single entry in borderTable. */ } TkBorder; diff --git a/generic/tkArgv.c b/generic/tkArgv.c index 5842687..66a703c 100644 --- a/generic/tkArgv.c +++ b/generic/tkArgv.c @@ -5,12 +5,12 @@ * argv-argc parsing. * * Copyright (c) 1990-1994 The Regents of the University of California. - * Copyright (c) 1994 Sun Microsystems, Inc. + * 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: @(#) tkArgv.c 1.21 97/04/25 16:50:27 + * SCCS: @(#) tkArgv.c 1.22 97/11/07 21:13:03 */ #include "tkPort.h" @@ -45,7 +45,7 @@ static void PrintUsage _ANSI_ARGS_((Tcl_Interp *interp, * * Results: * The return value is a standard Tcl return value. If an - * error occurs then an error message is left in interp->result. + * error occurs then an error message is left in the interp's result. * Under normal conditions, both *argcPtr and *argv are modified * to return the arguments that couldn't be processed here (they * didn't match the option table, or followed an TK_ARGV_REST @@ -291,10 +291,14 @@ Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags) srcIndex += 2; argc -= 2; break; - default: - sprintf(interp->result, "bad argument type %d in Tk_ArgvInfo", + default: { + char buf[64 + TCL_INTEGER_SPACE]; + + sprintf(buf, "bad argument type %d in Tk_ArgvInfo", infoPtr->type); + Tcl_SetResult(interp, buf, TCL_VOLATILE); return TCL_ERROR; + } } } @@ -328,7 +332,7 @@ Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags) * Generate a help string describing command-line options. * * Results: - * Interp->result will be modified to hold a help string + * The interp's result will be modified to hold a help string * describing all the options in argTable, plus all those * in the default table unless TK_ARGV_NO_DEFAULTS is * specified in flags. @@ -353,7 +357,7 @@ PrintUsage(interp, argTable, flags) int width, i, numSpaces; #define NUM_SPACES 20 static char spaces[] = " "; - char tmp[30]; + char tmp[TCL_DOUBLE_SPACE]; /* * First, compute the width of the widest option key, so that we diff --git a/generic/tkBind.c b/generic/tkBind.c index bb37b00..0aa0e9e 100644 --- a/generic/tkBind.c +++ b/generic/tkBind.c @@ -5,12 +5,12 @@ * with X events or sequences of X events. * * Copyright (c) 1989-1994 The Regents of the University of California. - * Copyright (c) 1994-1996 Sun Microsystems, Inc. + * 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: @(#) tkBind.c 1.133 97/07/01 17:59:53 + * SCCS: @(#) tkBind.c 1.144 98/02/18 17:08:07 */ #include "tkPort.h" @@ -571,6 +571,20 @@ static int flagArray[TK_LASTEVENT] = { }; /* + * The following table is used to map between the location where an + * generated event should be queued and the string used to specify the + * location. + */ + +static TkStateMap queuePosition[] = { + {-1, "now"}, + {TCL_QUEUE_HEAD, "head"}, + {TCL_QUEUE_MARK, "mark"}, + {TCL_QUEUE_TAIL, "tail"}, + {-2, NULL} +}; + +/* * The following tables are used as a two-way map between X's internal * numeric values for fields in an XEvent and the strings used in Tcl. The * tables are used both when constructing an XEvent from user input and @@ -644,7 +658,8 @@ static int GetVirtualEvent _ANSI_ARGS_((Tcl_Interp *interp, static Tk_Uid GetVirtualEventUid _ANSI_ARGS_((Tcl_Interp *interp, char *virtString)); static int HandleEventGenerate _ANSI_ARGS_((Tcl_Interp *interp, - Tk_Window main, int argc, char **argv)); + Tk_Window main, int objc, + Tcl_Obj *CONST objv[])); static void InitKeymapInfo _ANSI_ARGS_((TkDisplay *dispPtr)); static void InitVirtualEventTable _ANSI_ARGS_(( VirtualEventTable *vetPtr)); @@ -652,9 +667,14 @@ static PatSeq * MatchPatterns _ANSI_ARGS_((TkDisplay *dispPtr, BindingTable *bindPtr, PatSeq *psPtr, PatSeq *bestPtr, ClientData *objectPtr, PatSeq **sourcePtrPtr)); +static int NameToWindow _ANSI_ARGS_((Tcl_Interp *interp, + Tk_Window main, Tcl_Obj *objPtr, + Tk_Window *tkwinPtr)); static int ParseEventDescription _ANSI_ARGS_((Tcl_Interp *interp, char **eventStringPtr, Pattern *patPtr, unsigned long *eventMaskPtr)); +static void SetKeycodeAndState _ANSI_ARGS_((Tk_Window tkwin, + KeySym keySym, XEvent *eventPtr)); /* * The following define is used as a short circuit for the callback @@ -776,6 +796,7 @@ TkBindFree(mainPtr) bindInfoPtr = (BindInfo *) mainPtr->bindInfo; DeleteVirtualEventTable(&bindInfoPtr->virtualEventTable); + ckfree((char *) bindInfoPtr); mainPtr->bindInfo = NULL; } @@ -890,7 +911,7 @@ Tk_DeleteBindingTable(bindingTable) * Results: * The return value is 0 if an error occurred while setting * up the binding. In this case, an error message will be - * left in interp->result. If all went well then the return + * left in the interp's result. If all went well then the return * value is a mask of the event types that must be made * available to Tk_BindEvent in order to properly detect when * this binding triggers. This value can be used to determine @@ -995,7 +1016,7 @@ Tk_CreateBinding(interp, bindingTable, object, eventString, command, append) * Results: * The return value is 0 if an error occurred while setting * up the binding. In this case, an error message will be - * left in interp->result. If all went well then the return + * left in the interp's result. If all went well then the return * value is a mask of the event types that must be made * available to Tk_BindEvent in order to properly detect when * this binding triggers. This value can be used to determine @@ -1079,7 +1100,7 @@ TkCreateBindingProcedure(interp, bindingTable, object, eventString, * * Results: * The result is a standard Tcl return value. If an error - * occurs then interp->result will contain an error message. + * occurs then the interp's result will contain an error message. * * Side effects: * The binding given by object and eventString is removed @@ -1174,7 +1195,7 @@ Tk_DeleteBinding(interp, bindingTable, object, eventString) * given by bindingTable. If there is no binding for * eventString, or if eventString is improperly formed, * then NULL is returned and an error message is left in - * interp->result. The return value is semi-static: it + * the interp's result. The return value is semi-static: it * will persist until the binding is changed or deleted. * * Side effects: @@ -1217,7 +1238,7 @@ Tk_GetBinding(interp, bindingTable, object, eventString) * associated with a given object. * * Results: - * There is no return value. Interp->result is modified to + * There is no return value. The interp's result is modified to * hold a Tcl list with one entry for each binding associated * with object in bindingTable. Each entry in the list * contains the event string associated with one binding. @@ -1381,9 +1402,9 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) { BindingTable *bindPtr; TkDisplay *dispPtr; + ScreenInfo *screenPtr; BindInfo *bindInfoPtr; TkDisplay *oldDispPtr; - ScreenInfo *screenPtr; XEvent *ringPtr; PatSeq *vMatchDetailList, *vMatchNoDetailList; int flags, oldScreen, i, deferModal; @@ -1614,12 +1635,12 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) unsigned int oldSize, newSize; oldSize = sizeof(staticPending) - - sizeof(staticPending.matchArray) - + matchSpace * sizeof(PatSeq*); + - sizeof(staticPending.matchArray) + + matchSpace * sizeof(PatSeq*); matchSpace *= 2; newSize = sizeof(staticPending) - - sizeof(staticPending.matchArray) - + matchSpace * sizeof(PatSeq*); + - sizeof(staticPending.matchArray) + + matchSpace * sizeof(PatSeq*); new = (PendingBinding *) ckalloc(newSize); memcpy((VOID *) new, (VOID *) pendingPtr, oldSize); if (pendingPtr != &staticPending) { @@ -1650,7 +1671,7 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) * * There are two tricks here: * 1. Bindings can be invoked from in the middle of Tcl commands, - * where interp->result is significant (for example, a widget + * where the interp's result is significant (for example, a widget * might be deleted because of an error in creating it, so the * result contains an error message that is eventually going to * be returned by the creating command). To preserve the result, @@ -1681,6 +1702,13 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) } if (matchCount > 0) { + /* + * Remember the list of pending C binding callbacks, so we can mark + * them as deleted and not call them if the act of evaluating a C + * or Tcl binding deletes a C binding callback or even the whole + * window. + */ + pendingPtr->nextPtr = bindInfoPtr->pendingList; pendingPtr->tkwin = tkwin; pendingPtr->deleted = 0; @@ -1700,10 +1728,19 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) end = p + Tcl_DStringLength(&scripts); i = 0; + /* + * Be carefule when dereferencing screenPtr or bindInfoPtr. If we + * evaluate something that destroys ".", bindInfoPtr would have been + * freed, but we can tell that by first checking to see if + * winPtr->mainPtr == NULL. + */ + while (p < end) { int code; - screenPtr->bindingDepth++; + if (winPtr->mainPtr != NULL) { + screenPtr->bindingDepth++; + } Tcl_AllowExceptions(interp); if (*p == '\0') { @@ -1729,7 +1766,10 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) p += strlen(p); } p++; - screenPtr->bindingDepth--; + + if (winPtr->mainPtr != NULL) { + screenPtr->bindingDepth--; + } if (code != TCL_OK) { if (code == TCL_CONTINUE) { /* @@ -1759,8 +1799,9 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) } } - if ((screenPtr->bindingDepth != 0) && - ((oldDispPtr != screenPtr->curDispPtr) + if ((winPtr->mainPtr != NULL) + && (screenPtr->bindingDepth != 0) + && ((oldDispPtr != screenPtr->curDispPtr) || (oldScreen != screenPtr->curScreenIndex))) { /* @@ -1777,14 +1818,21 @@ Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr) Tcl_DStringFree(&scripts); if (matchCount > 0) { - PendingBinding **curPtrPtr; + if (winPtr->mainPtr != NULL) { + /* + * Delete the pending list from the list of pending scripts + * for this window. + */ + + PendingBinding **curPtrPtr; - for (curPtrPtr = &bindInfoPtr->pendingList; ; ) { - if (*curPtrPtr == pendingPtr) { - *curPtrPtr = pendingPtr->nextPtr; - break; + for (curPtrPtr = &bindInfoPtr->pendingList; ; ) { + if (*curPtrPtr == pendingPtr) { + *curPtrPtr = pendingPtr->nextPtr; + break; + } + curPtrPtr = &(*curPtrPtr)->nextPtr; } - curPtrPtr = &(*curPtrPtr)->nextPtr; } if (pendingPtr != &staticPending) { ckfree((char *) pendingPtr); @@ -2164,7 +2212,8 @@ MatchPatterns(dispPtr, bindPtr, psPtr, bestPtr, objectPtr, sourcePtrPtr) bestPtr = matchPtr; bestSourcePtr = sourcePtr; - nextSequence: continue; + nextSequence: + continue; } *sourcePtrPtr = bestSourcePtr; @@ -2208,8 +2257,11 @@ ExpandPercents(winPtr, before, eventPtr, keySym, dsPtr) int number, flags, length; #define NUM_SIZE 40 char *string; + Tcl_DString buf; char numStorage[NUM_SIZE+1]; + Tcl_DStringInit(&buf); + if (eventPtr->type < TK_LASTEVENT) { flags = flagArray[eventPtr->type]; } else { @@ -2358,37 +2410,8 @@ ExpandPercents(winPtr, before, eventPtr, keySym, dsPtr) goto doNumber; case 'A': if (flags & KEY) { - int numChars; - - /* - * If we're using input methods and this is a keypress - * event, invoke XmbTkFindStateString. Otherwise just use - * the older XTkFindStateString. - */ - -#ifdef TK_USE_INPUT_METHODS - Status status; - if ((winPtr->inputContext != NULL) - && (eventPtr->type == KeyPress)) { - numChars = XmbLookupString(winPtr->inputContext, - &eventPtr->xkey, numStorage, NUM_SIZE, - (KeySym *) NULL, &status); - if ((status != XLookupChars) - && (status != XLookupBoth)) { - numChars = 0; - } - } else { - numChars = XLookupString(&eventPtr->xkey, numStorage, - NUM_SIZE, (KeySym *) NULL, - (XComposeStatus *) NULL); - } -#else /* TK_USE_INPUT_METHODS */ - numChars = XLookupString(&eventPtr->xkey, numStorage, - NUM_SIZE, (KeySym *) NULL, - (XComposeStatus *) NULL); -#endif /* TK_USE_INPUT_METHODS */ - numStorage[numChars] = '\0'; - string = numStorage; + Tcl_DStringFree(&buf); + string = TkpGetString(winPtr, eventPtr, &buf); } goto doString; case 'B': @@ -2482,6 +2505,7 @@ ExpandPercents(winPtr, before, eventPtr, keySym, dsPtr) Tcl_DStringSetLength(dsPtr, length + spaceNeeded); before += 2; } + Tcl_DStringFree(&buf); } /* @@ -2514,7 +2538,7 @@ ChangeScreen(interp, dispName, screenIndex) { Tcl_DString cmd; int code; - char screen[30]; + char screen[TCL_INTEGER_SPACE]; Tcl_DStringInit(&cmd); Tcl_DStringAppend(&cmd, "tkScreenChanged ", 16); @@ -2548,87 +2572,98 @@ ChangeScreen(interp, dispName, screenIndex) */ int -Tk_EventCmd(clientData, interp, argc, argv) - ClientData clientData; /* Main window associated with - * interpreter. */ +Tk_EventObjCmd(clientData, interp, objc, objv) + ClientData clientData; /* Main window associated with interpreter. */ Tcl_Interp *interp; /* Current interpreter. */ - int argc; /* Number of arguments. */ - char **argv; /* Argument strings. */ + int objc; /* Number of arguments. */ + Tcl_Obj *CONST objv[]; /* Argument objects. */ { - int i; - size_t length; - char *option; + int index; Tk_Window tkwin; VirtualEventTable *vetPtr; TkBindInfo bindInfo; - - if (argc < 2) { - Tcl_AppendResult(interp, "wrong # args: should be \"", - argv[0], " option ?arg1?\"", (char *) NULL); - return TCL_ERROR; - } - - option = argv[1]; - length = strlen(option); - if (length == 0) { - goto badopt; - } + static char *optionStrings[] = { + "add", "delete", "generate", "info", + NULL + }; + enum options { + EVENT_ADD, EVENT_DELETE, EVENT_GENERATE, EVENT_INFO + }; tkwin = (Tk_Window) clientData; bindInfo = ((TkWindow *) tkwin)->mainPtr->bindInfo; vetPtr = &((BindInfo *) bindInfo)->virtualEventTable; - if (strncmp(option, "add", length) == 0) { - if (argc < 4) { - Tcl_AppendResult(interp, "wrong # args: should be \"", argv[0], - " add virtual sequence ?sequence ...?\"", (char *) NULL); - return TCL_ERROR; - } - for (i = 3; i < argc; i++) { - if (CreateVirtualEvent(interp, vetPtr, argv[2], argv[i]) - != TCL_OK) { + if (objc < 2) { + Tcl_WrongNumArgs(interp, 1, objv, "option ?arg?"); + return TCL_ERROR; + } + if (Tcl_GetIndexFromObj(interp, objv[1], optionStrings, "option", 0, + &index) != TCL_OK) { + return TCL_ERROR; + } + + switch ((enum options) index) { + case EVENT_ADD: { + int i; + char *name, *event; + + if (objc < 4) { + Tcl_WrongNumArgs(interp, 2, objv, + "virtual sequence ?sequence ...?"); return TCL_ERROR; } + name = Tcl_GetStringFromObj(objv[2], NULL); + for (i = 3; i < objc; i++) { + event = Tcl_GetStringFromObj(objv[i], NULL); + if (CreateVirtualEvent(interp, vetPtr, name, event) != TCL_OK) { + return TCL_ERROR; + } + } + break; } - } else if (strncmp(option, "delete", length) == 0) { - if (argc < 3) { - Tcl_AppendResult(interp, "wrong # args: should be \"", argv[0], - " delete virtual ?sequence sequence ...?\"", - (char *) NULL); - return TCL_ERROR; - } - if (argc == 3) { - return DeleteVirtualEvent(interp, vetPtr, argv[2], NULL); - } - for (i = 3; i < argc; i++) { - if (DeleteVirtualEvent(interp, vetPtr, argv[2], argv[i]) - != TCL_OK) { + case EVENT_DELETE: { + int i; + char *name, *event; + + if (objc < 3) { + Tcl_WrongNumArgs(interp, 2, objv, + "virtual ?sequence sequence ...?"); return TCL_ERROR; } + name = Tcl_GetStringFromObj(objv[2], NULL); + if (objc == 3) { + return DeleteVirtualEvent(interp, vetPtr, name, NULL); + } + for (i = 3; i < objc; i++) { + event = Tcl_GetStringFromObj(objv[i], NULL); + if (DeleteVirtualEvent(interp, vetPtr, name, event) != TCL_OK) { + return TCL_ERROR; + } + } + break; } - } else if (strncmp(option, "generate", length) == 0) { - if (argc < 4) { - Tcl_AppendResult(interp, "wrong # args: should be \"", argv[0], - " generate window event ?options?\"", (char *) NULL); - return TCL_ERROR; + case EVENT_GENERATE: { + if (objc < 4) { + Tcl_WrongNumArgs(interp, 2, objv, "window event ?options?"); + return TCL_ERROR; + } + return HandleEventGenerate(interp, tkwin, objc - 2, objv + 2); + break; } - return HandleEventGenerate(interp, tkwin, argc - 2, argv + 2); - } else if (strncmp(option, "info", length) == 0) { - if (argc == 2) { - GetAllVirtualEvents(interp, vetPtr); - return TCL_OK; - } else if (argc == 3) { - return GetVirtualEvent(interp, vetPtr, argv[2]); - } else { - Tcl_AppendResult(interp, "wrong # args: should be \"", argv[0], - " info ?virtual?\"", (char *) NULL); - return TCL_ERROR; + case EVENT_INFO: { + if (objc == 2) { + GetAllVirtualEvents(interp, vetPtr); + return TCL_OK; + } else if (objc == 3) { + return GetVirtualEvent(interp, vetPtr, + Tcl_GetStringFromObj(objv[2], NULL)); + } else { + Tcl_WrongNumArgs(interp, 2, objv, "?virtual?"); + return TCL_ERROR; + } + break; } - } else { - badopt: - Tcl_AppendResult(interp, "bad option \"", argv[1], - "\": should be add, delete, generate, info", (char *) NULL); - return TCL_ERROR; } return TCL_OK; } @@ -2715,8 +2750,8 @@ DeleteVirtualEventTable(vetPtr) * Results: * The return value is TCL_ERROR if an error occured while * creating the virtual binding. In this case, an error message - * will be left in interp->result. If all went well then the return - * value is TCL_OK. + * will be left in the interp's result. If all went well then the + * return value is TCL_OK. * * Side effects: * The virtual event may cause future calls to Tk_BindEvent to @@ -2821,7 +2856,7 @@ CreateVirtualEvent(interp, vetPtr, virtString, eventString) * * Results: * The result is a standard Tcl return value. If an error - * occurs then interp->result will contain an error message. + * occurs then the interp's result will contain an error message. * It is not an error to attempt to delete a virtual event that * does not exist or a definition that does not exist. * @@ -2873,7 +2908,10 @@ DeleteVirtualEvent(interp, vetPtr, virtString, eventString) eventPSPtr = FindSequence(interp, &vetPtr->patternTable, NULL, eventString, 0, 0, &eventMask); if (eventPSPtr == NULL) { - return (interp->result[0] != '\0') ? TCL_ERROR : TCL_OK; + char *string; + + string = Tcl_GetStringResult(interp); + return (string[0] != '\0') ? TCL_ERROR : TCL_OK; } } @@ -2975,12 +3013,12 @@ DeleteVirtualEvent(interp, vetPtr, virtString, eventString) * given virtual event. * * Results: - * The return value is TCL_OK and interp->result is filled with the + * The return value is TCL_OK and the interp's result is filled with the * string representation of the physical events associated with the * virtual event; if there are no physical events for the given virtual - * event, interp->result is filled with and empty string. If the + * event, the interp's result is filled with and empty string. If the * virtual event string is improperly formed, then TCL_ERROR is - * returned and an error message is left in interp->result. + * returned and an error message is left in the interp's result. * * Side effects: * None. @@ -3032,7 +3070,7 @@ GetVirtualEvent(interp, vetPtr, virtString) * event defined. * * Results: - * There is no return value. Interp->result is modified to + * There is no return value. The interp's result is modified to * hold a Tcl list with one entry for each virtual event in * nameTable. * @@ -3101,56 +3139,69 @@ GetAllVirtualEvents(interp, vetPtr) *--------------------------------------------------------------------------- */ static int -HandleEventGenerate(interp, main, argc, argv) - Tcl_Interp *interp; /* Interp for error messages and name lookup. */ - Tk_Window main; /* Main window associated with interp. */ - int argc; /* Number of arguments. */ - char **argv; /* Argument strings. */ +HandleEventGenerate(interp, main, objc, objv) + Tcl_Interp *interp; /* Interp for errors return and name lookup. */ + Tk_Window main; /* Main window associated with interp. */ + int objc; /* Number of arguments. */ + Tcl_Obj *CONST objv[]; /* Argument objects. */ { + XEvent event; + char *name, *p; + int count, flags, synch, i, number; + Tcl_QueuePosition pos; Pattern pat; - Tk_Window tkwin; - char *p; + Tk_Window tkwin, tkwin2; + TkWindow *mainPtr; unsigned long eventMask; - int count, i, state, flags, synch; - Tcl_QueuePosition pos; - XEvent event; + static char *fieldStrings[] = { + "-when", "-above", "-borderwidth", "-button", + "-count", "-detail", "-focus", "-height", + "-keycode", "-keysym", "-mode", "-override", + "-place", "-root", "-rootx", "-rooty", + "-sendevent", "-serial", "-state", "-subwindow", + "-time", "-width", "-window", "-x", + "-y", NULL + }; + enum field { + EVENT_WHEN, EVENT_ABOVE, EVENT_BORDER, EVENT_BUTTON, + EVENT_COUNT, EVENT_DETAIL, EVENT_FOCUS, EVENT_HEIGHT, + EVENT_KEYCODE, EVENT_KEYSYM, EVENT_MODE, EVENT_OVERRIDE, + EVENT_PLACE, EVENT_ROOT, EVENT_ROOTX, EVENT_ROOTY, + EVENT_SEND, EVENT_SERIAL, EVENT_STATE, EVENT_SUBWINDOW, + EVENT_TIME, EVENT_WIDTH, EVENT_WINDOW, EVENT_X, + EVENT_Y + }; + + if (NameToWindow(interp, main, objv[0], &tkwin) != TCL_OK) { + return TCL_ERROR; + } - if (argv[0][0] == '.') { - tkwin = Tk_NameToWindow(interp, argv[0], main); - if (tkwin == NULL) { - return TCL_ERROR; - } - } else { - if (TkpScanWindowId(NULL, argv[0], &i) != TCL_OK) { - Tcl_AppendResult(interp, "bad window name/identifier \"", - argv[0], "\"", (char *) NULL); - return TCL_ERROR; - } - tkwin = Tk_IdToWindow(Tk_Display(main), (Window) i); - if ((tkwin == NULL) || (((TkWindow *) main)->mainPtr - != ((TkWindow *) tkwin)->mainPtr)) { - Tcl_AppendResult(interp, "window id \"", argv[0], - "\" doesn't exist in this application", (char *) NULL); - return TCL_ERROR; - } + mainPtr = (TkWindow *) main; + if ((tkwin == NULL) + || (mainPtr->mainPtr != ((TkWindow *) tkwin)->mainPtr)) { + char *name; + + name = Tcl_GetStringFromObj(objv[0], NULL); + Tcl_AppendResult(interp, "window id \"", name, + "\" doesn't exist in this application", (char *) NULL); + return TCL_ERROR; } - p = argv[1]; + name = Tcl_GetStringFromObj(objv[1], NULL); + + p = name; count = ParseEventDescription(interp, &p, &pat, &eventMask); if (count == 0) { return TCL_ERROR; } if (count != 1) { - interp->result = "Double or Triple modifier not allowed"; + Tcl_SetResult(interp, "Double or Triple modifier not allowed", + TCL_STATIC); return TCL_ERROR; } if (*p != '\0') { - interp->result = "only one event specification allowed"; - return TCL_ERROR; - } - if (argc & 1) { - Tcl_AppendResult(interp, "value for \"", argv[argc - 1], - "\" missing", (char *) NULL); + Tcl_SetResult(interp, "only one event specification allowed", + TCL_STATIC); return TCL_ERROR; } @@ -3165,34 +3216,7 @@ HandleEventGenerate(interp, main, argc, argv) if (flags & (KEY_BUTTON_MOTION_VIRTUAL)) { event.xkey.state = pat.needMods; if (flags & KEY) { - /* - * When mapping from a keysym to a keycode, need information about - * the modifier state that should be used so that when they call - * XKeycodeToKeysym taking into account the xkey.state, they will - * get back the original keysym. - */ - - if (pat.detail.keySym == NoSymbol) { - event.xkey.keycode = 0; - } else { - event.xkey.keycode = XKeysymToKeycode(event.xany.display, - pat.detail.keySym); - } - if (event.xkey.keycode != 0) { - for (state = 0; state < 4; state++) { - if (XKeycodeToKeysym(event.xany.display, - event.xkey.keycode, state) == pat.detail.keySym) { - if (state & 1) { - event.xkey.state |= ShiftMask; - } - if (state & 2) { - TkDisplay *dispPtr = ((TkWindow *) tkwin)->dispPtr; - event.xkey.state |= dispPtr->modeModMask; - } - break; - } - } - } + SetKeycodeAndState(tkwin, pat.detail.keySym, &event); } else if (flags & BUTTON) { event.xbutton.button = pat.detail.button; } else if (flags & VIRTUAL) { @@ -3210,366 +3234,396 @@ HandleEventGenerate(interp, main, argc, argv) synch = 1; pos = TCL_QUEUE_TAIL; - for (i = 2; i < argc; i += 2) { - char *field, *value; - Tk_Window tkwin2; - int number; - KeySym keysym; + for (i = 2; i < objc; i += 2) { + Tcl_Obj *optionPtr, *valuePtr; + int index; - field = argv[i]; - value = argv[i+1]; - - if (strcmp(field, "-when") == 0) { - if (strcmp(value, "now") == 0) { - synch = 1; - } else if (strcmp(value, "head") == 0) { - pos = TCL_QUEUE_HEAD; - synch = 0; - } else if (strcmp(value, "mark") == 0) { - pos = TCL_QUEUE_MARK; - synch = 0; - } else if (strcmp(value, "tail") == 0) { - pos = TCL_QUEUE_TAIL; + optionPtr = objv[i]; + valuePtr = objv[i + 1]; + + if (Tcl_GetIndexFromObj(interp, optionPtr, fieldStrings, "option", + TCL_EXACT, &index) != TCL_OK) { + return TCL_ERROR; + } + if (objc & 1) { + /* + * This test occurs after Tcl_GetIndexFromObj() so that + * "event generate