summaryrefslogtreecommitdiffstats
path: root/src/H5FDdrvr_module.h
blob: 4a7a4d10f1e5fc6a5b09bc3f507d6969bf3d1725 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Programmer:	Quincey Koziol
 *		Saturday, September 12, 2015
 *
 * Purpose:	This file contains declarations which define macros for the
 *		H5FD driver package.  Including this header means that the source file
 *		is part of the H5FD driver package.
 */
#ifndef H5FDdrvr_module_H
#define H5FDdrvr_module_H

/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error
 *      reporting macros.
 */
#define H5_MY_PKG     H5FD
#define H5_MY_PKG_ERR H5E_FILE

#endif /* H5FDdrvr_module_H */
sts/winDialog.test | 335 +++++ tests/winFont.test | 91 +- tests/winMenu.test | 356 +++--- tests/winSend.test | 428 +++++++ tests/winWm.test | 55 +- tests/window.test | 48 +- tests/winfo.test | 102 +- tests/xmfbox.test | 153 +++ unix/Makefile.in | 227 ++-- unix/README | 12 +- unix/configure.in | 103 +- unix/mkLinks | 120 +- unix/tkAppInit.c | 13 +- unix/tkUnix.c | 6 +- unix/tkUnixButton.c | 49 +- unix/tkUnixConfig.c | 45 + unix/tkUnixCursor.c | 19 +- unix/tkUnixDefault.h | 13 +- unix/tkUnixEmbed.c | 61 +- unix/tkUnixEvent.c | 112 +- unix/tkUnixFocus.c | 3 +- unix/tkUnixFont.c | 2776 +++++++++++++++++++++++++++++++--------- unix/tkUnixInit.c | 12 +- unix/tkUnixInt.h | 7 +- unix/tkUnixKey.c | 90 ++ unix/tkUnixMenu.c | 447 ++++--- unix/tkUnixMenubu.c | 13 +- unix/tkUnixPort.h | 19 +- unix/tkUnixScale.c | 42 +- unix/tkUnixSelect.c | 85 +- unix/tkUnixSend.c | 107 +- unix/tkUnixWm.c | 320 +++-- unix/tkUnixXId.c | 7 +- win/README | 44 +- win/makefile.bc | 20 +- win/makefile.vc | 115 +- win/rc/tk.rc | 33 +- win/tkWin.h | 6 +- win/tkWin32Dll.c | 38 +- win/tkWin3d.c | 6 +- win/tkWinButton.c | 158 +-- win/tkWinClipboard.c | 33 +- win/tkWinColor.c | 25 +- win/tkWinConfig.c | 60 + win/tkWinCursor.c | 7 +- win/tkWinDefault.h | 11 +- win/tkWinDialog.c | 1591 ++++++++++++++--------- win/tkWinDraw.c | 61 +- win/tkWinEmbed.c | 61 +- win/tkWinFont.c | 2232 ++++++++++++++++++++++++++++---- win/tkWinInit.c | 4 +- win/tkWinInt.h | 14 +- win/tkWinKey.c | 72 +- win/tkWinMenu.c | 813 +++++++----- win/tkWinPointer.c | 3 +- win/tkWinPort.h | 15 +- win/tkWinScrlbr.c | 8 +- win/tkWinTest.c | 230 ++++ win/tkWinWindow.c | 50 +- win/tkWinWm.c | 356 +++--- win/tkWinX.c | 124 +- win/winMain.c | 124 +- xlib/X11/X.h | 6 +- xlib/X11/Xlib.h | 71 +- xlib/X11/Xutil.h | 24 - xlib/xdraw.c | 4 +- xlib/xgc.c | 5 +- 332 files changed, 48276 insertions(+), 23652 deletions(-) create mode 100644 doc/SetOptions.3 create mode 100644 generic/prolog.ps delete mode 100644 generic/tkIntPlatStubs.c delete mode 100644 generic/tkIntStubs.c delete mode 100644 generic/tkIntXlibStubs.c create mode 100644 generic/tkObj.c create mode 100644 generic/tkOldConfig.c delete mode 100644 generic/tkPlatStubs.c delete mode 100644 generic/tkStubs.c create mode 100644 library/images/logo.eps create mode 100644 library/images/pwrdLogo.eps create mode 100644 library/images/tai-ku.gif create mode 100644 mac/tkMacConfig.c delete mode 100644 tests/all create mode 100644 tests/all.tcl create mode 100644 tests/bitmap.test create mode 100644 tests/border.test create mode 100644 tests/config.test create mode 100644 tests/cursor.test delete mode 100644 tests/defs create mode 100644 tests/defs.tcl create mode 100644 tests/get.test create mode 100644 tests/obj.test create mode 100644 tests/unixSend.test delete mode 100644 tests/visual create mode 100644 tests/visual_bb.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 create mode 100644 unix/tkUnixKey.c create mode 100644 win/tkWinConfig.c create mode 100644 win/tkWinTest.c diff --git a/ChangeLog b/ChangeLog index ed72b4e..11bd657 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,42 +1,247 @@ 1999-04-15 - * Merged changes from 8.0.5: - - Updated for Mac release + * Merged 8.1 branch into the main trunk + +1999-04-09 + + * generic/tkWindow.c: Fixed deadlock situation when the Initialize() + function returns without releasing the mutex. Found while testing + Bug 1700, during safe.test (tk). + +1999-04-06 + + * generic/tkMain.c (Tk_MainEx): Changed to reset result before + calling Tcl_EvalFile. The ensures that error messages will be + generated cleanly. + + * tests/winfo.test: Enabled tests that previously failed. + +1999-04-05 + + * library/bgerror.tcl: + * library/button.tcl: + * library/clrpick.tcl: + * library/console.tcl: + * library/dialog.tcl: + * library/entry.tcl: + * library/focus.tcl: + * library/listbox.tcl: + * library/menu.tcl: + * library/msgbox.tcl: + * library/palette.tcl: + * library/scale.tcl: + * library/scrlbar.tcl: + * library/tearoff.tcl: + * library/text.tcl: + * library/tk.tcl: Lots of minor performance improvements + contributed by Jeffrey Hobbs. [Bug: 1118] + + * win/tkWinWm.c (Tk_WmCmd): Fixed bad code in tracing + suboption. [Bug: 1519] + + * library/tkfbox.tcl: Change to restore button text after an + action to avoid the sticky "Open" button in a save dialog. + [Bug: 1640] + + * library/entry.tcl: Fixed so selection is returned using the + -show character during cut and paste operations. [Bug: 1687] -1999-03-22 +1999-04-5 - * unix/configure.in: Removed --enable-tcl-stub from configure - scripts. Due to linking problems with wish and potentially anyone - else linking directly to Tk, linking Tk to the Tcl stubs is being - disabled until Tk is a truly loadable extension. + * generic/tkInt.decls: + * generic/tkIntXlibDecls.h: + * generic/tkStubInit.c: + * xlib/xgc.c: + * xlib/X11/Xlib.h: + * xlib/X11/Xutil.h: Added more X functions to the Win & Mac stubs + tables. +1999-04-05 + + * unix/configure.in: + * generic/tkCanvPs.c: Added configure test for pw_gecos field in + pwd to support OS/390. [Bug: 1724] + +1999-04-02 + + * tests/text.test: + * generic/tkText.c: Fixed handling of Unicode in text searches. + The -count option was returning byte counts instead of character + counts. [Bug: 1056, 1148, 1666] + +1999-04-01 + + * generic/tk.decls: + * generic/tk.h: + * generic/tkStubInit.c: + * generic/tkWindow.c: + * unix/Makefile.in: + * win/makefile.vc: Tk now uses its own stub library to store + pointers to its own stubs table. + + * doc/dde.n: (removed) + * doc/send.n: + * generic/tk.decls: + * tests/winSend.test: + * generic/tkPlatDecls.h: + * win/tkWinSend.c: Removed the DDE-based send and dde commands, + they were causing Tk to lock up when any window on the system was + not processing its message queue (more importantly, windows in Tcl + and Tk). The send command needs to be rewritten to prevent the + deadlock situation (soon). The dde command is being pushed into + its own package and will provide almost all of the capabilities + that send did before (using a "dde eval" command), not yet + completed. + +1999-03-31 + + * win/tkWinSend.c: Modified dde/send code to work properly on + Win95/Win98. String lengths are not returned properly by DDE, so + NULL terminate all strings going in and ignore the string length + coming back out. Do not destroy handles until all necessary work + on those handles (and child handles) is done. + +1999-03-30 + + * generic/tkWindow.c (Tk_DestroyWindow): Image handlers are now + finalized before the font subsystem since complex image handlers + may contain references to fonts (e.g. Tix compound images). + [Bug: 1603] + +1999-03-29 + + * doc/MeasureChar.3: + * doc/TextLayout.3: + * generic/tk.decls: + * generic/tkCanvText.c: + * generic/tkEntry.c: + * generic/tkFont.c: + * generic/tkListbox.c: + * generic/tkMessage.c: + * mac/tkMacFont.c: + * unix/tkUnixButton.c: + * unix/tkUnixFont.c: + * unix/tkUnixMenu.c: + * win/tkWinFont.c: + * win/tkWinMenu.c: Standardized text layout and font interfaces + so they are consistent with respect to byte versus character + oriented indices. The layout functions all manipulate character + oriented values while the lower level measurement functions all + operate on byte oriented values. This distinction was not clear + and so the functions were being used improperly in a number of + places. [Bug: 1053, 747, 749, 1646] + + * generic/tk.decls: Eliminated uses of C++ STL types string and + list from declarations. + + * generic/tkFont.c: Changes to named fonts were not being + propagated in some cases. [Bug: 1144] + + * xlib/X11/Xlib.h: + * generic/tkInt.decls: Added XParseColor to xlib stub + tables. [Bug: 1574] + + * doc/GetBitmap.3: + * generic/tkBitmap.c (BitmapInit): Eliminated use of Tk_Uid's in + bitmaps. Added a few CONST declarations. + +1999-03-29 + + * unix/configure.in: + * unix/Makefile.in: + * win/makefile.vc: + * generic/tkDecls.h: + * generic/tkIntDecls.h: + * generic/tkIntPlatDecls.h: + * generic/tkPlatDecls.h: + * generic/tkIntXlibDecls.h: Removed stub functions. Always use the + Tcl stubs when building with --enable-shared. + + +1999-03-26 + + * generic/tkTextIndex.c: + * tests/testIndex.test: Avoid looking past the beginning of the + array storing data for the text widget (.t index end-2c). Added + test case to check for the bug. [Bug 991] + + * generic/tkConsole.c: Copy static strings into a Tcl_DString + before passing to Tcl_Eval, in case the compiler puts static + strings into read-only memory. + +1999-03-26 + + * unix/configure.in: + --nameble-shared is now the default and builds Tk as a shared + library; specify --disable-shared to build a static Tk library + and shell. + +1999-03-26 + + * library/menu.tcl: Fixed bug reported by Bryan Oakley in the + menubutton bindings. There was a false assumption that there was + always a menu attached to the button. [Bug 1116] + +1999-03-26 + + * unix/configure.in: Removed --enable-tcl-stub. Linking Tk to Tcl + stubs is causing too many problems when linking executables like wish. + Until the Tk is a fully loadable extension, linking against the Tcl + stubs is not supported in Tk. + +1999-03-19 + + * generic/tkBitmap.c: + * generic/tkCursor.c: + * generic/tkGC.c: When creating hash tables that key off of XID + handles, make sure to pass TCL_ONE_WORD_KEYS. XIDs are guaranteed + to be 32bit numbers, although on some 64bit systems (including 64bit + Solaris 7) they are packed into a 64bit value where the upper 32bits + are zero. The normal method of sizeof(XID)/sizeof(int) causes the + hash table code to assume that the XID is a pointer to an array of + two ints, which it is not. Tk now supports 64bit Solaris 7. + +1999-03-17 + + * win/makefile.vc: + * generic/tk.h: Changed to use TCL_BETA_RELEASE macro, and fixed + so this works in rc files. + + * win/makefile.vc: + * win/makefile.bc: + * win/README: + * unix/configure.in: + * generic/tk.h: + * README: Updated version to 8.1b3. + +1999-03-14 + + * unix/configure.in: Added missing stub related definitions. + + * unix/Makefile.in: Install tkDecls.h in addition to tk.h. + + * generic/tkStubLib.c: Added flags to ensure we are using Tcl + stub macros. + 1999-03-11 * generic/tkInt.decls: Added reserved slot for XSetDashes for use by the dash patch. 1999-03-10 - * win/tkWinInt.h: - * win/tkWinPointer.c: - * win/tkWinWm.c: Fixed bug with "focus -force". Windows' - SetForegroundWindow doesn't work properly if you don't pass the - handle to the true toplevel window. Added a wrapper function - TkWinSetForegroundWindow to work around the problem. Back-ported - from Tk 8.1. - -1999-03-10 + * xlib/xdraw.c: * xlib/X11/Xlib.h: - * unix/tkUnixInt.h: * mac/tkMac.h: * mac/tkMacInt.h: * mac/tkMacPort.h: * mac/tkMacXStubs.c: + * mac/tkMacAppInit.c: + * mac/tkMacCursor.c: * win/makefile.vc: * win/tkWin.h: * win/tkWinInt.h: * win/tkWinPort.h: - * win/tkWinDraw.c: * win/winMain.c: * generic/tk.h: * generic/tkInt.h: @@ -56,31 +261,143 @@ * generic/tkStubLib.c: * generic/tkBind.c: * generic/tkCmds.c: - * generic/tkConsole.c + * generic/tkConfig.c: + * generic/tkConsole.c: + * generic/tkCursor.c: * generic/tkGrab.c: * generic/tkImgPhoto.c: * generic/tkMain.c: + * generic/tkMenu.c: * generic/tkPointer.c: * generic/tkTextDisp.c: * generic/tkWindow.c: + * unix/tkUnixInt.h: + * unix/tkUnixPort.h: * unix/Makefile.in: * unix/configure.in: * unix/tkConfig.sh.in: * unix/tkUnix.c: * unix/tkUnix3d.c: * unix/tkUnixDraw.c: - * unix/tkUnixFont.c: Stubs implementation for 8.0.6. Tk_Main() is - now a wrapper around Tk_MainEx() and will be removed in 8.1 and - replaced with a macro. Tk does not link to the Tcl stubs library - for now, because of issues with wish (will be fixed in 8.1). - Exported all public functions through the stubs mechanism (see the - *.decls files) and many of the internal functions. Most of the - changes dealt with shifting around the function declarations in - the header files. Mac code may not compile, but it shouldn't take - much work to fix this. + * unix/tkUnixFont.c: + * unix/tkUnixMenubu.c: Stubs implementation for 8.1. Tk_Main() is + replaced with a macro which calls Tk_MainEx(). Tk can link to the Tcl + stubs library, wish links directly to Tcl and Tk. Use + --enable-tcl-stubs to link Tk to the Tcl stubs library (Unix), on + by default on Windows. Exported all public functions through the + stubs mechanism (see the *.decls files) and many of the internal + functions. Most of the changes dealt with shifting around the + function declarations in the header files. Mac code may not + compile, but it shouldn't take much work to fix this. + + * mac/tkMacMenu.c: Added dummy TkpMenuThreadInit for Mac to be + consistent with Unix and Windows versions. + +1999-03-08 + + * win/tkWinWm.c: Toplevel class no longer shared between + threads. + + * win/tkWinX.c: Multiple threads no longer share the same + TkDisplay structure. Required because TkDisplay stores much + thread-specific data for a given thread. + + * win/tkWinSend.c: Moved application instance handle out + out thread-local storage. DDE was failing to initialize + when the instance handles were different between threads. + + * win/makefile.vc: Added THREADDEFINES for building with + threads enabled. + + * generic/tkMenu.c: + * win/tkWinMenu.c: + * unix/tkUnixMenu.c: Added TkpMenuThreadInit for initializing + thread-specific Menu state. + +1999-03-01 + + * win/tkWinWm.c: + * win/tkWinPointer.c: + * win/tkWinInt.h: Fix "focus -force" for Windows. The Win32 API + function SetForegroundWindow() does not work unless the window + handle is a toplevel window (a Windows toplevel). The handle + being passed was a Tk toplevel, which is a child of the Windows + toplevel. + +1999-02-26 + + * win/cat.c: Remove this file, use the one in the Tcl source directory. + + * win/makefile.vc: Remove the wishc.exe from the default targets. Add + a separate console-wish target to build it. The need for a + console-wish will go away soon, so we don't want to encourage its + use. + +1999-02-25 + + * win/tkWinWm.c: Properly initialize the tsdPtr->firstWindow field. + + * win/cat.c: Code for cat32.exe, copied from the Tcl sources. Required + in order to run the test suite from the makefile + + * win/winMain.c: Add main() for a console-based wishc.exe, which meant + adding code to disable the call to Tk_ConsoleInit(). + + * generic/tkConsole.c: Check the standard handles before creating the + new standard channels. This allows a windows app that has stdin, + stdout, or stderr to correctly connect to them. + + * generic/tkMain.c: Add a proper check for the interactive mode, since + the standard channels may actually be connected in windows mode or + even in the console-based wish. + + * win/makefile.vc: Add targets for wishc.exe (console-based wish) and + cat32.exe (for testing). Fix the test suite target so it can be run + from the makefile (which can happen since the standard handles have + been fixed). + +1999-02-12 + + * generic/tkMenuButton.h: + * generic/tkMenuButton.c: + * mac/tkMacMenubutton.c: + * mac/tkMacDefault.h + * unix/tkUnixMenubu.c: Eliminated Tk_Uids used by -state option. + * unix/tkUnixDefault.h + * win/tkWinDefault.h + + + * generic/tk.h: + * generic/tkScale.h: + * generic/tkScale.c: + * generic/tkWindow.c: + * unix/tkUnixScale.c: + * unix/tkUnixDefault.h: + * unix/tkWinDefault.h: + * mac/tkMacDefault.h: Objectified scale widget. + + * win/tkWinX.c: Removed Thread-specific data from process + initialization code that was stopping the Tk Dll from + loading. + +1999-02-11 + + * README: + * generic/tk.h: + * unix/configure.in: + * win/README: + * win/makefile.bc: + * win/makefile.vc: Updated version to 8.1b2. + + * unix/tkUnixSend.c: Fixed one more Tcl_*ObjVar instance. 1999-02-04 + * Various cleanup related to the Tcl_Eval and Tcl_ObjSetVar + changes in Tcl. + + INTEGRATED PATCHES FROM 8.0.5b2: + * win/tkWinMenu.c (TkpDestroyMenu): Changed so modalMenuPtr is cleared when it is being destroyed. @@ -95,7 +412,7 @@ mask changed but ended up with the same XID, the GC failed to be updated and so the new mask was not used. [Bug: 970] - * generic/tkFocus.c (SetFocus): Changed o focus window is always + * generic/tkFocus.c (SetFocus): Changed so focus window is always set if -force is specified. This fixes the problem on Windows where Tk does not activate the window if it already has focus. @@ -142,15 +459,96 @@ * unix/tkUnixSend.c (Tk_SetAppName): Fixed uninitialized memory access bug. [Bug: 919] -1998-12-30 +1999-1-28 * generic/tkGrid.c: Fixed bug in "grid forget" that failed to cancel pending idle handlers, resulting in a crash in a few odd cases. +1999-01-06 + + * generic/tk.h, generic/tkGet.c, generic/tkConfig.c, + * generic/tkOldConfig.c, generic/tkEntry.c, generic/tkMenubutton.c, + * generic/tkMenubutton.h, generic/tkScale.c, generic/tkScale.h, + * generic/tkTextDisplay.c, generic/tkText.c, unix/tkUnixMenubu.c, + * unix/tkUnixScale.c, mac/tkMacMenu.c, mac/tkMacMenubutton.c, + + Removed global Tk_Uids dealing with "-state" configuration option + and added new TK_CONFIG_STATE configSpec that doesn't use + Tk_Uids. + +1998-12-11 === Tk 8.1b1 Release === + +1998-12-11 + + * generic/tkMain.c (Tk_Main): Fixed improper command line encoding + handling. + +1998-12-08 + + * win/tkWinClipboard.c (TkSelGetSelection, TkWinClipboardRender): + Changed to handle multibyte characters properly. [Bug: 935] + +1998-12-07 + + * library/xmfbox.tcl (tkMotifFDialog_Create): In the cached case, + the data array was not being initialized with the correct set of + widgets. + +1998-12-4 + + * Changed patchLevel to 8.1b1 + + * generic/tkMenu.c (ConfigureMenuCloneEntries): The -menu configuration + option was being incorrectly specified as just "menu". + +1998-11-30 + + * generic/tkButton.c (ConfigureButton): The error result was + getting lost when restoring configuration options. [Bug: 619] + +1998-11-25 + + * unix/tkUnixFont.c (GetFontAttributes): Initialize an unspecified + family to an empty string. + (FontMapLoadPage): if the font included characters below 32, the + index computation was incorrect because the range was shifted up + to 32. + (CreateClosestFont): check for empty locale as well as NULL. + + * generic/tkFont.c (TkFontParseXLFD): initialize charset to + iso8859-1 if no charset is specified. + + * mac/tkMacHLEvents.c (OdocHandler): added conversion from + external string to UTF [Bug: 869] + + * integrated tk8.0.4 changes. + + * generic/tkBind.c: fixed deletion order bug where a crash would + result if a binding deleted "." + + * generic/tkMenu.c (MenuWidgetObjCmd): disabled menu entries were + getting reenabled whenever the mouse passed over the entry [Bug: 860] + + * unix/tkUnixMenu.c (TkpComputeStandardMenuGeometry): hidemargin + option was not honored properly in menus [Bug: 859] + 1998-11-24 - * unix/tkUnixFont.c (TkpGetNativeFont): On some X servers, - XQueryLoadFont will always return a font, even if the name is - meaningless. This prevents Tk from parsing the font name, so now - we perform a quick sanity check on the name before letting X have - it. [Bug: 846] + * tkMacMenu.c, tkUnixMenu.c, tkWinMenu.c, tkMenuDraw.c, tkMenu.h, + * tkMenu.c: Backed out the previous fix for bug 620 and + eliminated a bunch of code that created unnecessary objects. + Changed back to using internal types instead of objects for many + configuration options. There are many more fixes like this that + could be made, but some require a little restructuring of the + code. In any case the leaks are fixed and there is a lot less + allocation happening. [Bug: 620] + +1998-11-19 + + * tkMenu.c (DestroyMenuEntry): fixed memory leaks [Bug: 620] + + * tkWinX.c (GetTranslatedKey): fixed bad code merge + + * tkWinWm.c, tkWinMenu.c: fixed titles and menus so they properly + display Unicode [Bug: 819] + diff --git a/README b/README index 346e16f..5c86346 100644 --- a/README +++ b/README @@ -3,7 +3,7 @@ README: Tk Tk is maintained, enhanced, and distributed freely as a service to the Tcl community by Scriptics Corporation. -RCS: @(#) $Id: README,v 1.13 1999/02/17 02:34:36 hershey Exp $ +RCS: @(#) $Id: README,v 1.14 1999/04/16 01:51:07 stanton Exp $ Contents -------- @@ -11,7 +11,7 @@ Contents 2. Documentation 3. Compiling and installing Tk 4. Getting started - 5. Summary of changes in Tk 8.0 + 5. Summary of changes in Tk 8.1 6. Development tools 7. Tcl newsgroup 8. Tcl contributed archive @@ -25,19 +25,23 @@ Contents This directory contains the sources and documentation for Tk, an X11 toolkit implemented with the Tcl scripting language. The information -here corresponds to release 8.0.5, which is the fifth patch update for -Tk 8.0. This release is designed to work with Tcl 8.0.5 and may not -work with any other version of Tcl. +here corresponds to release 8.1b3, which is the third beta release +for Tk 8.1. This release is mostly feature complete but may have bugs +and be missing some minor features. This release is for early +adopters who are willing to help us find and fix problems. Please let +us know about any problems you uncover. -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. +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 -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. + http://www.scriptics.com/software/8.1.html + +or refer to the "changes" file in this directory, which contains a +historical record of all changes to Tk. Tk is a freely available open source package. You can do virtually anything you like with it, such as modifying it, redistributing it, @@ -153,120 +157,9 @@ 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 +5. Summary of changes in Tk 8.1 ------------------------------- -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. Development tools -------------------- diff --git a/changes b/changes index 69aeccd..4c7d01e 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. -RCS: @(#) $Id: changes,v 1.31 1999/04/16 01:25:53 stanton Exp $ +RCS: @(#) $Id: changes,v 1.32 1999/04/16 01:51:07 stanton Exp $ 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 @@ -4343,10 +4343,242 @@ on Win NT 4.0/Japanese that cause a crash in some cases. (stanton) 2/4/99 (bug fix) Fixed uninitialized memory access bug in Unix send code. (stanton) ------------------ Released 8.0.5, 3/9/99 ------------------------- - ---------------------------------------------------------- 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 ----------------------- + +10/21/98 (bug fix) Tk_UnderlineChars did not handle UTF strings properly +so underline indices were in bytes instead of characters. (stanton) + +11/19/98 (bug fix) Fixed menus and titles so they properly display +Unicode characters under Windows. [Bug: 819] (stanton) + +11/24/98 (bug fix) Fixed a bunch of memory leaks in the Windows menu +code. [Bug: 620] (stanton) + +11/25/98 (bug fix) Various small bug fixes: (stanton) + - hidemargin option was not honored properly in menus [Bug: 859] + - disabled menu entries were getting reenabled whenever the + mouse passed over the entry [Bug: 860] + - fixed deletion order bug where a crash would result if a + binding deleted "." + +11/30/98 (bug fix) The error result was getting lost when restoring +configuration options in buttons. [Bug: 619] (stanton) + +12/8/98 (bug fix) The Windows clipboard was not correctly traslating +multibyte characters. [Bug: 935] (stanton) + +----------------- Released 8.1b1, Dec 11 1998 ----------------------- + +1/29/99 (bug fix) Fixed bug in "grid forget" that failed to cancel +pending idle handlers, resulting in a crash in a few odd +cases. (stanton) + +2/4/99 (bug fix): Fixed uninitialized memory access in +Tk_SetAppName. [Bug: 919] (stanton) + +2/4/99 (bug fix): Added a workaround for a bug in GetTextExtentExPoint +on Win NT 4.0/Japanese. [Bug: 1006] (stanton) + +2/4/99 (bug fix): Changed so keyboard shortcuts for menus will only be +found in the current toplevel. Previously, they might be found in +menus attached to other toplevels that might not even be mapped. +[Bug: 924] (stanton) + +2/4/99 (bug fix): Changed to treat zero width lines in the canvas like +they have width 1 for purposes of selection. [Bug: 925] (stanton) + +2/4/99 (bug fix): TK_LD_SEARCH_FLAGS was set incorrectly if +SHLIB_LD_LIBS='${LIBS}', and shared linking is performed through the C +compiler. Systems affected are Linux, MP-RAS and NEXTSTEP, but also +with gcc on many more systems. [Bug: 908] (stanton) + +2/4/99 (feature enhancement): Changed so windows that aren't resizable +don't have resize handles and the zoom box is disabled on +Windows. (stanton) + +2/4/99 (bug fix): Fixed so errors in console eval are reported +properly. Eliminated duplicate result messages. [Bug: 973] (stanton) + +2/4/99 (bug fix): Changed so focus window is always set if -force is +specified. This fixes the problem on Windows where Tk does not +activate the window if it already has focus. (stanton) + +2/4/99 (bug fix): If an image mask changed but ended up with the same +XID, the GC failed to be updated and so the new mask was not +used. [Bug: 970] (stanton) + +2/12/99 (new feature): Tk is now thread safe. You enable this by +configuring with --enable-threads. Tcl must also be compiled with +--enable-threads. See Tcl for more information about the threading +interfaces. (lfb) + +2/25/99 (bug fix) Under Windows, wish can now inherit pipe handles on +stdio so it is possible to use the wish executable in a command +pipeline to capture the output of puts or read from the pipe with +gets. (redman) + +3/1/99 (bug fix) Under Windows, Tk was not properly handling focus and +activation changes in some cases. (redman) + +3/10/99 (new feature) Tk now uses the new stub library feature in Tcl. +The Tk library now contains no direct references to any symbols in +Tcl. In addition, there is a new Tk_MainEx() function that takes an +interpreter as an argument. See the Tcl documentation for more +information about the stubs mechanism. (redman) + +3/14/99 (feature change) Test suite now uses "test" namespace to +define the test procedure and other auxiliary procedures as well as +global variables. + - Global array testConfige is now called ::test::testConfig. + - Global variable VERBOSE is now called ::test::verbose, and + ::test::verbose no longer works with numerical values. We've + switched to a bitwise character string. You can set + ::test::verbose by using the -verbose option on the Tk command + line. + - Global variable TESTS is now called ::test::matchingTests, and + can be set on the Tk command line via the -match option. + - There is now a ::test::skipTests variable (works similarly to + ::test::matchTests) that can be set on the Tk command line via + the -match option. + - The test suite can now be run in any working directory. When + you run "make test", the working directory is nolonger switched + to ../tests. +(hirschl) +*** POTENTIAL INCOMPATIBILITY *** + +----------------- Released 8.1b2, March 16, 1999 --------------------- + +3/23/99 (feature change) Test suite now uses "tcltest" namespace to +define the test procedure and other auxiliary procedures as well as +global variables. The previously chosen "test" namespace was thought +to be too generic and likely to create conflits. +(hirschl) +*** POTENTIAL INCOMPATIBILITY *** + +3/26/99 [bug fix] Fixed bug reported by Bryan Oakley in the +menubutton bindings. There was a false assumption that there was +always a menu attached to the button. [Bug 1116] (surles) + +3/26/99 (feature change) Removed --enable-tcl-stub from the configure +script. Linking Tk to Tcl stubs is causing too many problems when +linking executables like wish. Until the Tk is a fully loadable +extension, linking against the Tcl stubs is not supported in Tk. +(redman) + +3/26/99 (feature change) --nameble-shared is now the default and builds +Tk as a shared library; specify --disable-shared to build a static Tk +library and shell. +*** POTENTIAL INCOMPATIBILITY *** + +3/29/99 (api change) Standardized text layout and font interfaces +so they are consistent with respect to byte versus character +oriented indices. The layout functions all manipulate character +oriented values while the lower level measurement functions all +operate on byte oriented values. (stanton) + +4/1/99 (bug fix) Image handlers are finalized before the font subsystem +to fix crashes during finalization of complex widgets. (stanton) + +4/1/99 (feature change) Removed the send command on Windows. Moved +the DDE basis of that command out to its own extension. The send +implementation on top of DDE was causing Tk to lock up in some cases. +(redman) + +4/5/99 (bug fix) Fixed handling of Unicode in text searches. The +-count option was returning byte counts instead of character counts. + +4/5/99 (feature change) Cut and paste to an entry widget returns the +selection instead of the widget contents, which can be different if the +-show option is used to hide the display. (stanton) + +--------------- Released 8.1b3, April 6, 1999 ---------------------- + diff --git a/compat/stdlib.h b/compat/stdlib.h index 650750d..4b76fe5 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. * - * RCS: @(#) $Id: stdlib.h,v 1.2 1998/09/14 18:03:09 stanton Exp $ + * RCS: @(#) $Id: stdlib.h,v 1.3 1999/04/16 01:51:07 stanton Exp $ */ #ifndef _STDLIB diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index ea1a629..2780bde 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. '\" -'\" RCS: @(#) $Id: 3DBorder.3,v 1.2 1998/09/14 18:22:45 stanton Exp $ +'\" RCS: @(#) $Id: 3DBorder.3,v 1.3 1999/04/16 01:51:07 stanton Exp $ '\" .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 04daead..0b8b91b 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. '\" -'\" RCS: @(#) $Id: ConfigWidg.3,v 1.2 1998/09/14 18:22:46 stanton Exp $ +'\" RCS: @(#) $Id: ConfigWidg.3,v 1.3 1999/04/16 01:51:07 stanton Exp $ '\" .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/GetAnchor.3 b/doc/GetAnchor.3 index 5342ea5..b12d48f 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. '\" -'\" RCS: @(#) $Id: GetAnchor.3,v 1.2 1998/09/14 18:22:48 stanton Exp $ +'\" RCS: @(#) $Id: GetAnchor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .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 4321cce..28b5cb1 100644 --- a/doc/GetBitmap.3 +++ b/doc/GetBitmap.3 @@ -1,42 +1,61 @@ '\" '\" 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. '\" -'\" RCS: @(#) $Id: GetBitmap.3,v 1.2 1998/09/14 18:22:48 stanton Exp $ +'\" RCS: @(#) $Id: GetBitmap.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .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 +\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR .sp -Tk_Uid +char * \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR .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 "CONST char" *info in +Same as \fIobjPtr\fR except description of bitmap is passed as a string and +resulting Pixmap isn't cached. +.VE +.AP "CONST 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 @@ -196,36 +239,40 @@ which was created by the \fBbitmap\fR program and contains a stipple pattern. The following code uses \fBTk_DefineBitmap\fR to define a new bitmap named \fBfoo\fR: +.VS .CS Pixmap bitmap; #include "stip.bitmap" -Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits, +Tk_DefineBitmap(interp, "foo", stip_bits, stip_width, stip_height); \&... -bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo")); +bitmap = Tk_GetBitmap(interp, tkwin, "foo"); .CE +.VE This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using \fBTk_GetBitmap\fR: +.VS .CS Pixmap bitmap; -bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap")); +bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); .CE +.VE The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. .PP -\fBTk_GetBitmap\fR maintains a -database of all the bitmaps that are currently in use. +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 +280,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 4b551f2..d5abc78 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. '\" -'\" RCS: @(#) $Id: GetColor.3,v 1.2 1998/09/14 18:22:48 stanton Exp $ +'\" RCS: @(#) $Id: GetColor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .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 dca27ad..55b9c58 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. '\" -'\" RCS: @(#) $Id: GetCursor.3,v 1.2 1998/09/14 18:22:49 stanton Exp $ +'\" RCS: @(#) $Id: GetCursor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .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 8971913..f052935 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. '\" -'\" RCS: @(#) $Id: GetFont.3,v 1.2 1998/09/14 18:22:49 stanton Exp $ +'\" RCS: @(#) $Id: GetFont.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .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 6b12be1..68dced7 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. '\" -'\" RCS: @(#) $Id: GetJustify.3,v 1.2 1998/09/14 18:22:49 stanton Exp $ +'\" RCS: @(#) $Id: GetJustify.3,v 1.3 1999/04/16 01:51:08 stanton Exp $ '\" .so man.macros -.TH