Tk Source Code

1999-04-09    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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-04-5     <[email protected]>

	* 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    <[email protected]>

	* unix/configure.in:
	* generic/tkCanvPs.c: Added configure test for pw_gecos field in
	pwd to support OS/390. [Bug: 1724]

1999-04-02    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>
	
	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <stanton@GASPODE>

	* 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    <stanton@GASPODE>

	* generic/tkInt.decls: Added reserved slot for XSetDashes for use
	by the dash patch.

1999-03-10    <[email protected]>

	* xlib/xdraw.c:
	* xlib/X11/Xlib.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/winMain.c:
	* generic/tk.h:
	* generic/tkInt.h:
	* generic/tk.decls:
	* generic/tkInt.decls:
	* generic/tkDecls.h:
	* generic/tkPlatDecls.h:
	* generic/tkIntDecls.h:
	* generic/tkIntPlatDecls.h:
	* generic/tkIntXlibDecls.h:
	* generic/tkStubs.c:
	* generic/tkPlatStubs.c:
	* generic/tkIntStubs.c:
	* generic/tkIntPlatStubs.c:
	* generic/tkIntXlibStubs.c:
	* generic/tkStubInit.c:
	* generic/tkStubLib.c:
	* generic/tkBind.c:
	* generic/tkCmds.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:
	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <[email protected]>

	* 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    <stanton@GASPODE>

	* 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    <stanton@GASPODE>

	* 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.

	* generic/tkImgPhoto.c: Changed so color tables are freed
	immediately instead of being delayed.  This ensures that color
	tables are properly disposed at process exit.

	* library/prolog.ps: Changed string that determines font height to
	include European character with an umlaut.

	* generic/tkImgBmap.c (ImgBmapConfigureInstance): 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]

	* 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.

	* generic/tkConsole.c: Fixed so errors in console eval are
	reported properly.  Eliminated duplicate result messages. [Bug: 973]

	* win/tkWinWm.c: Changed so windows that aren't resizable don't
	have resize handles and the zoom box is disabled.

	* win/tkWinInt.h:
	* win/tkWinPointer.c: Changed to cancel the mouse timer when a
	user initiated move/resize loop begins.

	* unix/configure.in: 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]

	* win/makefile.vc: First stab at install target.  Fixed quoting so
	paths with spaces work.
	
	* tests/main.test:
	* tests/unixWm.test: Better cleanup of temporary files.
	
	* mac/tkMacAppInit.c:
	* generic/tkTest.c:
	* generic/tkAppInit.c:
	* win/winMain.c: Changed some EXTERN declarations to extern
	since they are not defining exported interfaces.  This avoids
	generating useless declspec() attributes and makes the windows
	makefile simpler.

	* library/menu.tcl (tkMenuFind): Changed so keyboard shortcuts
	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]

	* generic/tkCanvLine.c: Changed to treat zero width lines like
	they have width 1 for purposes of selection. [Bug: 925]

	* win/tkWinFont.c (Tk_MeasureChars): Added a workaround for a bug
	in GetTextExtentExPoint on Win NT 4.0/Japanese. [Bug: 1006]

	* unix/tkUnixSend.c (Tk_SetAppName): Fixed uninitialized memory
	access bug. [Bug: 919]

1999-1-28    <stanton@GASPODE>

	* 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  <lfb@JUSTICE>

	* 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    <stanton@GASPODE>

	* generic/tkMain.c (Tk_Main): Fixed improper command line encoding
	handling. 

1998-12-08    <stanton@GASPODE>

	* win/tkWinClipboard.c (TkSelGetSelection, TkWinClipboardRender):
	Changed to handle multibyte characters properly. [Bug: 935]

1998-12-07    <stanton@GASPODE>

	* 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    <welch@SAGE>

	* Changed patchLevel to 8.1b1

	* generic/tkMenu.c (ConfigureMenuCloneEntries): The -menu configuration
	option was being incorrectly specified as just "menu". 

1998-11-30    <stanton@GASPODE>

	* generic/tkButton.c (ConfigureButton): The error result was
	getting lost when restoring configuration options. [Bug: 619]

1998-11-25    <stanton@GASPODE>

	* 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    <stanton@GASPODE>

	* 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    <stanton@GASPODE>

	* 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]

README:  Tk

	Tk is maintained, enhanced, and distributed freely as a
	service to the Tcl community by Scriptics Corporation.

RCS: @(#) $Id: README,v 1.1.4.6 1999/03/17 22:06:27 stanton Exp $

Contents
--------
    1. Introduction
    2. Documentation
    3. Compiling and installing Tk
    4. Getting started
    5. Summary of changes in Tk 8.1
    6. Development tools
    7. Tcl newsgroup
    8. Tcl contributed archive
    9. Tcl Resource Center
    10. Mailing lists
    11. Support and bug fixes
    12. Tk version numbers

1. Introduction
---------------

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.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.

The most important change in Tk 8.1 is that it supports the new
internationalization features in Tcl 8.1.  It also contains a new


library for handling configuration options some of the widgets have
been converted to use the Tcl object facilities.  For details on
features, incompatibilities, and potential problems with this release,

see the Tcl/Tk 8.1 Web page at

	http://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,
and selling it either in whole or in part.  See the file
"license.terms" for complete information.

2. Documentation
----------------

The best way to get started with Tk is to read about Tk on the
Scriptics Web site at:

	http://www.scriptics.com/scripting

Another good way to get started with Tcl is to read one of the
introductory books on Tcl:

    Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
    Prentice-Hall, 1997, ISBN 0-13-616830-2

    Tcl and the Tk Toolkit, by John Ousterhout,
    Addison-Wesley, 1994, ISBN 0-201-63337-X

    Exploring Expect, by Don Libes,
    O'Reilly and Associates, 1995, ISBN 1-56592-090-2

Other books are listed at
http://www.scriptics.com/resource/doc/books/

There is also an official home for Tcl and Tk on the Scriptics Web site:

	http://www.scriptics.com

These Web pages include information about the latest releases, products
related to Tcl and Tk, reports on bug fixes and porting issues, HTML
versions of the manual pages, and pointers to many other Tcl/Tk Web
pages at other sites.  Check them out!

If you are porting Tk 3.6 scripts to Tk 4.0 or later releases, you may
find the Postscript file doc/tk4.0.ps useful.  It is a porting guide
that summarizes the new features and discusses how to deal with the
changes in Tk 4.0 that are not backwards compatible.

2a. Unix Documentation
----------------------

The "doc" subdirectory in this release contains a complete set of
reference manual entries for Tk.  Files with extension ".1" are for
programs such as wish; files with extension ".3" are for C library
procedures; and files with extension ".n" describe Tcl commands.  To
print any of the manual entries, cd to the "doc" directory and invoke
your favorite variant of troff using the normal -man macros, for example

		ditroff -man wish.1

to print wish.1.  If Tk has been installed correctly and your "man"
program supports it, you should be able to access the Tcl manual entries
using the normal "man" mechanisms, such as

		man wish

2b. Windows Documentation



-------------------------

The "doc/help" subdirectory in this release contains a complete set of
Windows help files for TclPro.  Once you install this Tcl release, a
shortcut to the Windows help Tcl documentation will appear in the
"Start" menu:

	Start | Programs | Tk | Tk Help


3. Compiling and installing Tk
------------------------------

This release contains everything you should need to compile and run
Tk under UNIX, PCs (either Windows NT, Windows 95, or Win 3.1 with
Win32s), and Macintoshes.

Before trying to compile Tk you should do the following things:

    (a) Check for a binary release.  Pre-compiled binary releases are
        available now for PCs, Macintoshes, and several flavors of UNIX.
        Binary releases are much easier to install than source releases.
        To find out whether a binary release is available for your
        platform, check the Scriptics Tcl Resource Center
        (http://www.scriptics.com/resource).  Also, check in
        the FTP directory from which you retrieved the base
        distribution.

    (b) Make sure you have the most recent patch release.  Look in the
	FTP directory from which you retrieved this distribution to see
	if it has been updated with patches.  Patch releases fix bugs
	without changing any features, so you should normally use the
	latest patch release for the version of Tk that you want. 






























Once you've done this, change to the "unix" subdirectory if you're
compiling under UNIX, "win" if you're compiling under Windows, or
"mac" if you're compiling on a Macintosh.  Then follow the instructions
in the README file in that directory for compiling Tk, installing it,
and running the test suite.

4. Getting started
------------------

The best way to get started with Tk is by reading one of the
introductory books.  See the documentation section above for more
details.

The subdirectory library/demos contains a number of pre-canned scripts
that demonstrate various features of Tk.  See the README file in the
directory for a description of what's available.  The file
library/demos/widget is a script that you can use to invoke many
individual demonstrations of Tk's facilities, see the code that
produced the demos, and modify the code to try out alternatives.

5. Summary of changes in Tk 8.1
-------------------------------




6. Development tools









--------------------








































A high quality set of commercial development tools is now available to

accelerate your Tk application development.  Scriptics' TclPro



product provides a debugger, static code checker, packaging utility,


and bytecode compiler.  Visit the Scriptics Web site at:






	http://www.scriptics.com/tclpro








for more information on TclPro and for a free 30-day evaluation


download.




























7. Tcl newsgroup
















----------------





There is a network news group "comp.lang.tcl" intended for the

exchange of information about Tcl, Tk, and related applications.  The

newsgroup is a greata place to ask general information questions.  For

bug reports, please see the "Support and bug fixes" section below.


















8. Tcl contributed archive
--------------------------

Many people have created exciting packages and applications based on Tcl
and/or Tk and made them freely available to the Tcl community.  An archive
of these contributions is kept on the machine ftp.neosoft.com.  You
can access the archive using anonymous FTP;  the Tcl contributed archive is
in the directory "/pub/tcl".  The archive also contains several FAQ
("frequently asked questions") documents that provide solutions to problems
that are commonly encountered by TCL newcomers.

9. Tcl Resource Center
----------------------

Visit http://www.scriptics.com/resource/ to see an annotated index of
many Tcl resources available on the World Wide Web.  This includes
papers, books, and FAQs, as well as development tools, extensions,
applications, binary releases, and patches.  You can also recommend
additional URLs for the resource center using the forms labeled "Add a
Resource".

10. Mailing lists
-----------------

A couple of  Mailing List have been set up to discuss Macintosh or
Windows related Tcl issues.  To subscribe send a message to:
	
	[email protected]
	[email protected]
	
In the body of the message (the subject will be ignored) put:
	
	subscribe mactcl Joe Smith
	
Replacing Joe Smith with your real name, of course.  (Use wintcl
instead of mactcl if your interested in the Windows list.)  If you
would just like to receive more information about the list without
subscribing put the line:

	information mactcl
	
in the body instead (or wintcl).

11. Support and bug fixes
-------------------------

Scriptics is very interested in receiving bug reports, patches, and
suggestions for improvements.  We prefer that you send this
information to us via the bug form on the Scriptics Web site, rather
than emailing us directly.  The bug form is at:

	http://www.scriptics.com/support/bugForm.html

The bug form was designed to give uniform structure to bug reports as
well as to solicit enough information to minimize followup questions.
The bug form also includes an option to automatically post your report
on comp.lang.tcl.  We strongly recommend that you select this option
because someone else who reads comp.lang.tcl may be able to offer a
solution.

When reporting bugs, please provide full information about the Tcl/Tk
version and the platform on which you are running Tcl/Tk.  Also,
please include a short wish script that we can use to reproduce the
bug.  Make sure that the script runs with a bare-bones wish and
doesn't depend on any extensions or other programs, particularly those
that exist only at your site.  Also, please include three additional
pieces of information with the script:

    (a) how do we use the script to make the problem happen (e.g.
	what things do we click on, in what order)?
    (b) what happens when you do these things (presumably this is
        undesirable)?
    (c) what did you expect to happen instead?

We will log and follow-up on each bug, although we cannot promise a
specific turn-around time.  Enhancements may take longer and may not
happen at all unless there is widespread support for them (we're
trying to slow the rate at which Tcl/Tk turns into a kitchen sink).
It's very difficult to make incompatible changes to Tcl/Tk at this
point, due to the size of the installed base.

The Tcl community is too large for us to provide much individual
support for users.  If you need help we suggest that you post
questions to comp.lang.tcl.  We read the newsgroup and will attempt to
answer esoteric questions for which no-one else is likely to know the
answer.  In addition, Tcl/Tk support and training are available
commercially from Scriptics at:

	http://www.scriptics.com/training

Also see the following Web site for links to other organizations that
offer Tcl/Tk training:

	http://www.scriptics.com/resource/commercial/training

12. Tk version numbers
----------------------

You can test the current version of Tk by examining the
tk_version and tk_patchLevel variables.  The tk_patchLevel
variable follows the naming rules outlined below (e.g., 8.0.5).
The tk_version just has the major.minor numbers in it (e.g., 8.0)

Each Tk release is identified by two numbers separated by a dot, e.g.
3.6 or 4.0.  If a new release contains changes that are likely to break
existing C code or Tcl scripts then the major release number increments
and the minor number resets to zero: 3.0, 4.0, etc.  If a new release
contains only bug fixes and compatible changes, then the minor number
increments without changing the major number, e.g. 4.1, 4.2, etc.  If
you have C code or Tcl scripts that work with release X.Y, then they
should also work with any release X.Z as long as Z > Y.

Alpha and beta releases have an additional suffix of the form a2 or
b1.  For example, Tk 4.0b1 is the first beta release of Tk version
4.0, Tk 4.0b2 is the second beta release, and so on.  A beta release
is an initial version of a new release, used to fix bugs and bad
features before declaring the release stable.  An alpha release is
like a beta release, except it's likely to need even more work before
it's "ready for prime time".  New releases are normally preceded by
one or more alpha and beta releases.  We hope that lots of people will
try out the alpha and beta releases and report problems.  We'll make
new alpha/beta releases to fix the problems, until eventually there is
a beta release that appears to be stable.  Once this occurs we'll make
the final release.

We can't promise to maintain compatibility among alpha and beta releases.
For example, release 4.1b2 may not be backward compatible with 4.1b1, even
though the final 4.1 release will be backward compatible with 4.0.  This
allows us to change new features as we find problems during beta testing.
We'll try to minimize incompatibilities between beta releases, but if
a major problem turns up then we'll fix it even if it introduces an
incompatibility.  Once the official release is made then there won't
be any more incompatibilities until the next release with a new major
version number.

(Note: This compatibility is true for Tcl scripts, but historically
the Tcl C APIs have changed enough between releases that you may need
to work a bit to upgrade extensions.)

Patch releases now have a suffix such as ".4" or ".5".  Prior to
version 8.0.3, patch releases had the suffix "p1" or "p2".  So, the
8.0 release went to 8.0p1, 8.0p2, 8.0.3, 8.0.4, and 8.0.5.  The alphas
and betas continue to use the 'a' and 'b' letters in their
tk_patchLevel.  Patch releases normally contain bug fixes only.  A
patch release (e.g Tk 8.0.5) should be completely compatible with the
base release from which it is derived (e.g. Tk 8.0), and you should
normally use the highest available patch release.

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.

13. Thank You
-------------

We'd like to express our thanks to the Tcl community for all the
helpful suggestions, bug reports, and patches we have received.
Tcl/Tk has improved vastly and will continue to do so with your help.

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.1.4.13 1999/04/06 05:48:56 welch 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
be dangling pointers to the non-existent window).

3/16/91 (bug fix) Modified tkColor.c not to free black or white colors:
some X servers get upset at this.

key sequences from having the character echoed to the widget. Also
fixed Cut & Copy bindings.  (JI) (RJ)

9/18/97 (bug fix) Revamped Macintosh focus code.  Cut, Copy & Paste
virtual events now go to the correct (focus) window. (RJ)

9/19/97 (bug fix) Made Macintosh tearoff menus non-resizable. (RJ)

10/9/97 (bug fix) 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/10/97 (bug fix) In canvas text items, if the text ended with a \n, it 
was not counted in the bbox height, as it did in tk4.2.  This caused 
"hello\n" to be the same height as "hello" and you couldn't see the 
cursor positioned on the next line. (CCS)

10/10/97 (bug fix) The grid geometry manager didn't always properly
forget about windows after a "grid forget" or "grid remove" command:
the windows could reappear on the screen later.  (JO)

10/13/97 (bug fix) Selection could not be restored to a text widget

11/20/97 (bug fix) Fixed bug in rendering transparent gifs on Text
widgets. (JI)

11/20/97 (enhancement) Made the changes required to work with the new
Apple Universal Headers V. 3.0 so we can compile with CW Pro 2.0 (JI)

----------------- Released 8.0p2, 11/25/97 -----------------------

11/25/97 (security bug fix + added feature) Tk Safe Init now asks
the master's safe::TkInit for the 'argv' to use. This is transparently
dealt with by the safe::loadTk API. New optional "-display displayName"
argument to safe::loadTk, and the "-use" argument accepts both window
Ids and Tk window names: see loadTk(n). Made the ":0.0" default display
work on the Mac as it works on Windows and Unix. (DL)

12/3/97 (bug fix/optimization) Removed unneeded and potentially dangerous
instances of double evaluations if "if" and "expr" statements from
the library files. It is recommended that unless you need a double
evaluation you always use "expr {...}" instead of "expr ..." and
"if {...} ..." instead of "if ... ...". It will also be faster
thanks to the byte compiler. (DL)

12/3/97 (new feature) Added support for browser/plugin style embedding, 
and made various other fixes to get the plugin working on the Mac. (JI)

12/8/97 (bug fix) on Windows, using "winfo pathname" before "." was mapped
was crashing. (DL)

---- Shipped as part of the plugin2.0b5 as 8.0p2Plugin1, Dec 8th 97 ----

12/97 (bug fix) more Macintosh embeding fixes needed for the plugin. (JI)

Jan/9/98 (improvement) Allow applications to have custom init script
without  having to patch the Tk core: Tk_Init will use an existing
"tkInit" proc if one exists in the interp where one tries to install Tk
instead of defining it's own (tkInit is the transient proc defined in
generic/tkInitScript.h that searches and sources tk.tcl and defines 
the 'correct' tk_library). (DL)

---- Shipped as part of the plugin2.0 as 8.0p2Plugin2, Jan 15th 98 ----

6/3/98 (bug fix) Fixed bugs in the tk_getOpenFile under Unix.
 1) If the -initialdir option was "." the result would be "././foo.tcl"
    instead of an absolute path, like the Windows interface.  
 2) There is a traceVar on the data(selectPath) where the script was
    assumes the window exists. (BS)

6/12/98 (feature change) Focus -force now sets the foreground window
on Windows platforms in addition to moving the focus. (SS)

6/12/98 (bug fix) Fixed bug in Windows font measurement that did not
take kerning into account. (BS)

6/24/98 (bug fix) On Unix, fixed -initialdir switch to tk_getOpenFile
and tk_getSaveFile to convert the specified directory to an absolute
path and to use the current working directory if the specified
directory does not exist. (SS)

6/25/98 (bug fix) On Unix, both the Tk and the Motif file dialogs
would fail if the -parent flag changed between two parent windows that
had been previously used as file dialog parents. (SS)

6/29/98 (compatibility patch)  Added reserved fields to several Tk
structures to match additions made by Jan Nijtmans dash patch.  This
means that extensions can be compiled against the dash patch
and still work with unpatched Tk, and vice versa.

7/6/98 (bug fix) Added keysym definitions for the new keys on the
Microsoft keyboards.  You can bind to <App>, <Win_L>, and <Win_R>,
but you cannot use the Win keys as modifiers. (SS, BW)

7/6/98 (new feature) Added support for the Macintosh Appearance Manager. (JI)

7/24/98 (feature change) Eliminated the static variable that sets
tk_library and simplified search order for tk.tcl.  The tk_library
variable can now be set before calling Tk_Init to avoid doing any
searches.  If it isn't set, then Tk checks env(TK_LIBRARY), relative
to tcl_library, an install directory relative to the executable, a
source directory relative to the executable, and a tk directory
relative to the source heirarchy containing the executable.  See the
comment at the top of generic/tkInitScript.h for more details. (SS)

7/27/98 (bug fix) The bbox for coords in the canvas were incorrectly
including the center of the coord as part of the bound area.  (RJ)

8/4/98 (bug fix) Fixed memory leak in Windows menu code. (SS)

8/4/98 (bug fix) Fixed bug where bgerror's were not being generated 
from menu callbacks on Windows. (SS)

8/4/98 (bug fix) Alt-key bindings were not being handled properly 
under Windows, resulting in annoying beeps. (SS)

8/4/98 (bug fix) Fixed bug in Windows menubar handling that allowed
a shared menubar to be deleted when any window using it was deleted. (SS)

8/4/98 (feature change) Introduced TkReadBitmapFile to replace
XReadBitmapFile so that all Tk file opens go through the Tcl channel
mechanism.  This lets us wrap applications that define their own
bitmaps and cursors. Note that XReadBitmapFile is no longer
emulated for non-unix platforms platforms (RJ, BW)

8/5/98 (bug fix) <Insert> binding in entries was masking the virtual
event <<Paste>> binding to Shift-Insert on Windows. (SS)

8/5/98 (bug fix) wm frame would crash if the window had not been
mapped yet on Windows. (SS)

8/5/98 (bug fix) Local grabs did not exclude menus or the caption bar
under Windows. (SS)

8/5/98 (bug fix) Reduced message traffic by setting
WS_EX_NOPARENTNOTIFY on TkChild windows. (SS)

8/6/98 (feature change) Changed tkInitScript.h to use the new
tcl_findLibrary procedure to locate its script library. (BW)

8/10/98 (bug fix) Added special case to font code to limit the
length of displayed strings to avoid wrap-around bugs in some
PC X servers when the pixel length of the string exceeds 0x7fff. (SS)

8/12/98 (bug fix) Macintosh, lock down some of the resources
associated with menus to try and stabilise the menu system
on memory limited machines. (JI)

8/12/98 (windows build change) Moved the tkConsole.obj into the tk80.dll
on windows.  If you build your own Tk main program, you no longer
need to compile and link this yourself. (SKS)

-------- Released 8.0.3 to the Tcl Consortium CD-ROM project, 8/13/98 ------

10/5/98 (new feature) Added the event "MouseWheel" that will fire on
Windows applications in response to mouse wheel movement.  You can
bind to the MouseWheel event and use the %D substitution to get the
delta the wheel moved.  The "event generate" command has also been
enhanced with the -delta flag so you can generate these events from
Tcl.  See the bind and event man pages for more details.  The listbox
and text widgets' default bindings have been updated to understand
MouseWheel events. (RJ)

10/12/98 (performance improvement) Added hash table to canvas widget
that holds numeric ids for items.  The hash table makes item lookup
almost constant time which improves certain canvas operations
(exspecially for canvases with large number items).  Thanks to Mark
Weissman <[email protected]> and Jan Nijtmans <[email protected]>
for submitting this improvement.  (RJ)

10/15/98 (bug fix) The -fill option to text items in the canvas did
not allow the empty string as an argument (meaning transparent) even
though every other item type did.  Thanks to Sebastian Wangnick
<[email protected]> for supplying this patch. (RJ)

10/20/98 (feature change) The Makefile and configure scripts have been
changed for IRIX to build n32 binaries instead of the old 32 abi
format.  If you have extensions built with the o32 abi's you will need
to update them to n32 for them to work with Tcl.  (RJ)
*** POTENTIAL INCOMPATIBILITY ***

11/10/98 (feature change) The Macintosh menus will use the Appearance
Theme backgrounds, separators and menu shape, if Appearance version
1.0.1 or greater is installed.  The version of Appearance that shipped
with MacOS 8.0 so it will not work with a straight 8.0, but it will
with MacOS 8.1 or later. (JI)

----------------- Released 8.0.4, 11/20/98 -----------------------

11/24/98 (bug fix) 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. (stanton)

12/30/98 (bug fix) Fixed bug in "grid forget" that failed to cancel
pending idle handlers, resulting in a crash in a few odd cases. (stanton)

1/28/99 (configure change) Now support -pipe option on gcc.  (RJ)

2/4/99 (bug fix) Changed so color tables in photo images are freed
immediately instead of being delayed.  This ensures that color tables
are properly disposed at process exit. (stanton)

2/4/99 (bug fix) Changed postscript template to	include a European
character with an umlaut when determining font height. (stanton)

2/4/99 (bug fix) If an image bitmap mask changed but ended up with the
same XID, the GC failed to be updated and so the new mask was
not used. (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) Fixed so errors in console eval are reported
properly.  Eliminated duplicate result messages. (stanton)

2/4/99 (bug fix) Under Windows, changed so toplevels that aren't
resizable don't have resize handles and the zoom box is disabled. (stanton)

2/4/99 (bug fix) Changed to cancel the mouse timer when a user
initiated move/resize loop begins on Windows. (stanton)

2/4/99 (configure change) 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.

2/4/99 (bug fix) Changed some EXTERN declarations to extern since they
are not defining exported interfaces.  This avoids generating useless
declspec() attributes and makes the Windows makefile simpler. (stanton)

2/4/99 (bug fix) Changed so keyboard shortcuts 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. (stanton)
*** POTENTIAL INCOMPATIBILITY ***

2/4/99 (bug fix) Changed to treat zero width lines in the canvas like
they have width 1 for purposes of selection. (stanton)

2/4/99 (bug fix) Added a workaround for a bug in GetTextExtentExPoint
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)

----------------------------------------------------------
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 ----------------------

 *
 * Copyright (c) 1991 The Regents of the University of California.
 * Copyright (c) 1994 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 *
 * RCS: @(#) $Id: limits.h,v 1.1.4.1 1998/09/30 02:15:14 stanton Exp $
 */

#define LONG_MIN		0x80000000
#define LONG_MAX		0x7fffffff
#define INT_MIN			0x80000000
#define INT_MAX			0x7fffffff
#define SHRT_MIN		0x8000

/*
 * stdlib.h --
 *
 *	Declares facilities exported by the "stdlib" portion of
 *	the C library.  This file isn't complete in the ANSI-C
 *	sense;  it only declares things that are needed by Tcl.
 *	This file is needed even on many systems with their own
 *	stdlib.h (e.g. SunOS) because not all stdlib.h files
 *	declare all the procedures needed here (such as strtod).
 *
 * Copyright (c) 1991 The Regents of the University of California.
 * Copyright (c) 1994-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.1.4.2 1998/09/30 02:15:15 stanton Exp $
 */

#ifndef _STDLIB
#define _STDLIB

#include <tcl.h>

 * software and its documentation for any purpose and without
 * fee is hereby granted, provided that the above copyright
 * notice appear in all copies.  The University of California
 * makes no representations about the suitability of this
 * software for any purpose.  It is provided "as is" without
 * express or implied warranty.
 *
 * RCS: @(#) $Id: unistd.h,v 1.1.4.1 1998/09/30 02:15:15 stanton Exp $
 */

#ifndef _UNISTD
#define _UNISTD

#include <sys/types.h>
#ifndef _TCL

'\"
'\" Copyright (c) 1990-1993 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: 3DBorder.3,v 1.1.4.2 1998/09/30 02:15:16 stanton Exp $
'\" 
.so man.macros
.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
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 <tk.h>\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
void
\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp

\fBTk_NameOf3DBorder(\fIborder\fB)\fR
.sp
XColor *
\fBTk_3DBorderColor(\fIborder\fB)\fR
.sp
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
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window (for all procedures except \fBTk_Get3DBorder\fR,
must be the window for which the border was allocated).
.AP 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
same screen and depth as \fItkwin\fR.
.AP Tk_3DBorder border in
Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
.AP int x in

Specifies which of the border's graphics contexts is desired.
Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
.BE

.SH DESCRIPTION
.PP
These procedures provide facilities for drawing window borders in a
way that produces a three-dimensional appearance.
.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 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 \fIobjPtr\fR, and the shadowed portions of the border will appear
darker than \fIobjPtr\fR.
.PP
\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. 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.
The \fItkwin\fR argument specifies the
window for which the border was allocated, and \fIdrawable\fR
specifies a window or pixmap in which the border is to be drawn.
\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it

TK_RELIEF_SUNKEN means that the interior should appear depressed.
TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be
a groove or ridge around the exterior of the rectangle.
.PP
\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
that it first fills the rectangular area with the background color
(one corresponding
to the 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
happens is to fill the rectangle with the background color).
.PP
The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
shapes with a three-dimensional appearance.  The \fIpointPtr\fR and

For example, to draw a rectangular border the top bevel should be
drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the
bottom bevel should be drawn with 0 for both arguments.
.PP
The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
pixel and/or pixmap of \fItkwin\fR to produce a result compatible
with \fIborder\fR.  For color displays, the resulting background will

just be the color 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 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 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
The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts
that are used to draw the border.
The argument \fIwhich\fR selects which one of the three possible GC's:
TK_3D_FLAT_GC returns the context used for flat surfaces,
TK_3D_LIGHT_GC returns the context for light shadows,
and TK_3D_DARK_GC returns the context for dark shadows.
.PP
.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, object, polygon, raised, shadow, three-dimensional effect

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: BindTable.3,v 1.1.4.1 1998/09/30 02:15:16 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateBindingTable 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CanvPsY.3,v 1.1.4.1 1998/09/30 02:15:17 stanton Exp $
'\" 
.so man.macros
.TH Tk_CanvasPsY 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CanvTkwin.3,v 1.1.4.1 1998/09/30 02:15:18 stanton Exp $
'\" 
.so man.macros
.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CanvTxtInfo.3,v 1.1.4.1 1998/09/30 02:15:18 stanton Exp $
'\" 
.so man.macros
.TH Tk_CanvasTextInfo 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CanvasTextInfo \- additional information for managing text items in canvases
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Clipboard.3,v 1.1.4.1 1998/09/30 02:15:18 stanton Exp $
'\" 
.so man.macros
.TH Tk_ClipboardClear 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ClipboardClear, Tk_ClipboardAppend \- Manage the clipboard
.SH SYNOPSIS

'\"
'\" Copyright (c) 1992-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ClrSelect.3,v 1.1.4.1 1998/09/30 02:15:19 stanton Exp $
'\" 
.so man.macros
.TH Tk_ClearSelection 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ClearSelection \- Deselect a selection
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ConfigWidg.3,v 1.1.4.2 1998/09/30 02:15:19 stanton Exp $
'\" 
.so man.macros
.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
.sp
int
\fBTk_Offset(\fItype, field\fB)\fR
.sp
int
\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
int
\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 in/out
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window used to represent widget (needed to set up X resources).
.AP Tk_ConfigSpec *specs in
Pointer to table specifying legal configuration options for this
widget.

'\"
'\" Copyright (c) 1990-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ConfigWind.3,v 1.1.4.1 1998/09/30 02:15:20 stanton Exp $
'\" 
.so man.macros
.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CoordToWin.3,v 1.1.4.1 1998/09/30 02:15:47 stanton Exp $
'\" 
.so man.macros
.TH Tk_CoordsToWindow 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CoordsToWindow \- Find window containing a point
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtErrHdlr.3,v 1.1.4.1 1998/09/30 02:15:47 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors
.SH SYNOPSIS

'\"
'\" Copyright (c) 1992-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtGenHdlr.3,v 1.1.4.1 1998/09/30 02:15:47 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateGenericHandler 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateGenericHandler, Tk_DeleteGenericHandler \- associate procedure callback with all X events
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtImgType.3,v 1.1.4.1 1998/09/30 02:15:48 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateImageType 3 8.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateImageType, Tk_GetImageMasterData \- define new kind of image
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtItemType.3,v 1.1.4.1 1998/09/30 02:15:48 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Australian National University
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" Author: Paul Mackerras ([email protected]),
'\"	    Department of Computer Science,
'\"	    Australian National University.
'\"
'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.1.4.1 1998/09/30 02:15:49 stanton Exp $
'\"
.so man.macros
.TH Tk_CreatePhotoImageFormat 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreatePhotoImageFormat \- define new file format for photo images
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtSelHdlr.3,v 1.1.4.1 1998/09/30 02:15:49 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateSelHandler 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for a selection
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtWindow.3,v 1.1.4.2 1998/09/30 02:15:49 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: DeleteImg.3,v 1.1.4.1 1998/09/30 02:15:50 stanton Exp $
'\" 
.so man.macros
.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_DeleteImage \- Destroy an image.
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: DrawFocHlt.3,v 1.1.4.1 1998/09/30 02:15:50 stanton Exp $
'\" 
.so man.macros
.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: EventHndlr.3,v 1.1.4.1 1998/09/30 02:15:51 stanton Exp $
'\" 
.so man.macros
.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Australian National University
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" Author: Paul Mackerras ([email protected]),
'\"	    Department of Computer Science,
'\"	    Australian National University.
'\"
'\" RCS: @(#) $Id: FindPhoto.3,v 1.1.4.1 1998/09/30 02:15:51 stanton Exp $
'\"
.so man.macros
.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image.
.SH SYNOPSIS

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: FontId.3,v 1.1.4.1 1998/09/30 02:15:51 stanton Exp $
'\" 
.so man.macros
.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_FontId, Tk_FontMetrics, Tk_PostscriptFontName \- accessor functions for 
fonts

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: FreeXId.3,v 1.1.4.1 1998/09/30 02:15:52 stanton Exp $
'\" 
.so man.macros
.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_FreeXId \- make X resource identifier available for reuse
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" 
'\" RCS: @(#) $Id: GeomReq.3,v 1.1.4.1 1998/09/30 02:15:52 stanton Exp $
'\" 
.so man.macros
.TH Tk_GeometryRequest 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GeometryRequest, Tk_SetInternalBorder \- specify desired geometry or internal border for a window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 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: GetAnchor.3,v 1.1.4.2 1998/09/30 02:15:52 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
int
\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR
.VE
.sp
int
\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR
.sp
char *
\fBTk_NameOfAnchor(\fIanchor\fB)\fR
.SH ARGUMENTS
.AS "Tk_Anchor" *anchorPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, 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
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
\fIobjPtr\fR or \fIstring\fR.
.AP Tk_Anchor anchor in
Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR.
.BE

.SH DESCRIPTION
.PP
.VS 8.1
\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position
(enumerated type \fBTk_Anchor\fR)
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 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, \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
statically-allocated string corresponding to \fIanchor\fR.
If \fIanchor\fR isn't a legal anchor value, then
``unknown anchor position'' is returned.

'\"
'\" Copyright (c) 1990 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: GetBitmap.3,v 1.1.4.4 1999/04/07 00:36:10 stanton Exp $
'\" 
.so man.macros
.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
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 <tk.h>\fR
.sp
.VS 8.1
Pixmap
\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, name, source, width, height\fB)\fR
.sp

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; 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.
.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.
Must be stored in static memory whose value will never change.
.AP "int" width in
Width of bitmap.
.AP "int" height in
Height of bitmap.
.AP "int" *widthPtr out
Pointer to word to fill in with \fIbitmap\fR's width.
.AP "int" *heightPtr out
Pointer to word to fill in with \fIbitmap\fR's height.
.AP Display *display in
Display for which \fIbitmap\fR was allocated.
.AP Pixmap bitmap in
Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
.BE

.SH DESCRIPTION
.PP
These procedures manage a collection of bitmaps (one-plane pixmaps)
being used by an application.  The procedures allow bitmaps to be
re-used efficiently, thereby avoiding server overhead, and also
allow bitmaps to be named with character strings.
.PP
.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
description in the standard X11 or X10 format.
.TP 20
\fIname\fR
\fIName\fR must be the name of a bitmap defined previously with

\fBnote\fR
A face with ballon words.
.TP 12
\fBcaution\fR
A triangle with an exclamation point.
.RE
.LP
.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 \fIobjPtr\fR refers
to a non-existent file, then \fBNone\fR is returned and an error
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_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
describe the bitmap.
\fBTk_DefineBitmap\fR normally returns TCL_OK;  if an error occurs
(e.g. a bitmap named \fInameId\fR has already been defined) then
TCL_ERROR is returned and an error message is left in
\fIinterp->result\fR.
Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
\fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
a private copy of this memory, but uses the bytes pointed to
by \fIsource\fR later in calls to \fBTk_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
the variables defined by the file.
For example, suppose there exists a file \fBstip.bitmap\fR,
which was created by the \fBbitmap\fR program and contains
a stipple pattern.
The following code uses \fBTk_DefineBitmap\fR to define a
new bitmap named \fBfoo\fR:
.VS
.CS
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, "foo", stip_bits,
	stip_width, stip_height);
\&...
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, "@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

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_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
.PP
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
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 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_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_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
.PP
.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_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
see whether the file itself has changed, or whether the current
directory has changed, thereby causing the name to refer to
a different file.

.SH KEYWORDS
bitmap, pixmap

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetCapStyl.3,v 1.1.4.1 1998/09/30 02:15:53 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetClrmap.3,v 1.1.4.1 1998/09/30 02:15:53 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps
.SH SYNOPSIS

'\"
'\" 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.1.4.2 1998/09/30 02:15:54 stanton Exp $
'\" 
.so man.macros
.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.VS 8.1
.sp
XColor *
\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
XColor *
\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(\fIcolorPtr, drawable\fB)\fR
.sp
.VS 8.1
\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR
.VE
.sp
\fBTk_FreeColor(\fIcolorPtr\fB)\fR
.SH ARGUMENTS
.AS "Tcl_Interp" *colorPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which color will be used.
.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_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
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
server's color database file, such as \fBred\fR or \fBPeachPuff\fR.
.TP 20
\fB#\fIRGB\fR
.TP 20
\fB#\fIRRGGBB\fR
.TP 20
\fB#\fIRRRGGGBBB\fR
.TP 20
\fB#\fIRRRRGGGGBBBB\fR
A numeric specification of the red, green, and blue intensities
to use to display the color.  Each \fIR\fR, \fIG\fR, or \fIB\fR
represents a single hexadecimal digit.  The four forms permit
colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values.
When fewer than 16 bits are provided for each color, they represent
the most significant bits of the color.  For example, #3a7 is the
same as #3000a0007000.
.PP



.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 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_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 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 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 this package
may return the same shared
pixel value, callers should never change the color of a pixel
returned by the procedures.
If you need to change a color value dynamically, you should use
\fBXAllocColorCells\fR to allocate the pixel value for the color.
.PP
The procedure \fBTk_NameOfColor\fR is roughly the inverse of
\fBTk_GetColor\fR.  If its \fIcolorPtr\fR argument was created
by \fBTk_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.
.PP
\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR
field is the pixel allocated for \fIcolorPtr\fR and whose other fields
all have default values.
This provides an easy way to do basic drawing with a color.
The graphics context is cached with the color and will exist only as
long as \fIcolorPtr\fR exists;  it is freed when the last reference
to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR.
.PP
.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, object, pixel value

'\"
'\" Copyright (c) 1990 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: GetCursor.3,v 1.1.4.2 1998/09/30 02:15:54 stanton Exp $
'\" 
.so man.macros
.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
Tk_Cursor
\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
.sp
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
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which the cursor will be used.
.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 cursor, in standard cursor format.
.AP char *mask in
Data for mask cursor, in standard cursor format.
.AP "int" width in
Width of \fIsource\fR and \fImask\fR.
.AP "int" height in
Height of \fIsource\fR and \fImask\fR.
.AP "int" xHot in
X-location of cursor hot-spot.
.AP "int" yHot in
Y-location of cursor hot-spot.
.AP Tk_Uid fg in
Textual description of foreground color for cursor.
.AP Tk_Uid bg in
Textual description of background color for cursor.
.AP Display *display in
Display for which \fIcursor\fR was allocated.
.AP Tk_Cursor cursor in
Opaque Tk identifier for cursor.  If passed to \fBTk_FreeCursor\fR, must
have been returned by some previous call to \fBTk_GetCursor\fR or
\fBTk_GetCursorFromData\fR.
.BE

.SH DESCRIPTION
.PP
These procedures manage a collection of cursors
being used by an application.  The procedures allow cursors to be
re-used efficiently, thereby avoiding server overhead, and also
allow cursors to be named with character strings.
.PP
.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 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
cursors looks like.  If \fIfgColor\fR and \fIbgColor\fR are both
specified, they give the foreground and background colors to use
for the cursor (any of the forms acceptable to \fBTk_GetColor\fR
may be used).  If only \fIfgColor\fR is specified, then there
will be no background color:  the background will be transparent.
If no colors are specified, then the cursor
will use black for its foreground color and white for its background
color.
.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
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 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
form of the command will not work on Macintosh or Windows computers.
.TP
\fB@\fIsourceName\0fgColor\fR
This form is similar to the one above, except that the source is
used as mask also.  This means that the cursor's background is
transparent.  This form of the command will not work on Macintosh
or Windows computers.
.PP
.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 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
location of the cursor's hot-spot (the point that is reported when
an event occurs), and \fIfg\fR and \fIbg\fR describe the cursor's
foreground and background colors textually (any of the forms
suitable for \fBTk_GetColor\fR may be used).  Typically, the
arguments to \fBTk_GetCursorFromData\fR are created by including
a cursor file directly into the source code for a program, as in
the following example:
.CS
Tk_Cursor cursor;
#include "source.cursor"
#include "mask.cursor"
cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
	mask_bits, source_width, source_height, source_x_hot,
	source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
.CE
.PP
Under normal conditions \fBTk_GetCursorFromData\fR
will return an identifier for the requested cursor.  If an error

occurs in creating the cursor then \fBNone\fR is returned and an error
message will be stored in \fIinterp\fR's result.
.PP
\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_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.  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 \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
giving the X identifier for the cursor.
Note:  the string returned by \fBTk_NameOfCursor\fR is
only guaranteed to persist until the next call to
\fBTk_NameOfCursor\fR.  Also, this call is not portable except for
cursors returned by \fBTk_GetCursor\fR.
.PP
.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_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_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
cursor created from the same file name:  it will not check to
see whether the file itself has changed, or whether the current
directory has changed, thereby causing the name to refer to
a different file.  Similarly, \fBTk_GetCursorFromData\fR assumes
that if the same \fIsource\fR pointer is used in two different calls,
then the pointers refer to the same data;  it does not check to
see if the actual data values have changed.

.SH KEYWORDS
cursor

'\"
'\" Copyright (c) 1990-1992 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: GetFont.3,v 1.1.4.2 1998/09/30 02:15:55 stanton Exp $
'\" 
.so man.macros
.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
Tk_Font 
\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.  If NULL, then no error
messages are left after errors.
.AP Tk_Window tkwin in
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
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
.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_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 (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
.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

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetGC.3,v 1.1.4.1 1998/09/30 02:15:55 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetGC 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetImage.3,v 1.1.4.1 1998/09/30 02:15:55 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetJoinStl.3,v 1.1.4.1 1998/09/30 02:15:56 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 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: GetJustify.3,v 1.1.4.2 1998/09/30 02:15:56 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
int
\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR
.sp
int
\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR
.sp
char *
\fBTk_NameOfJustify(\fIjustify\fB)\fR
.SH ARGUMENTS
.AS "Tk_Justify" *justifyPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL.
.VS 8.1 br
.AP Tcl_Obj *objPtr in/out
String value contains name of justification style (\fBleft\fR, \fBright\fR, or
\fBcenter\fR).  The
internal rep will be modified to cache corresponding justify value.
.AP char *string in
Same as \fIobjPtr\fR except description of justification style is passed as
a string.
.VE
.AP int *justifyPtr out
Pointer to location in which to store justify value corresponding to
\fIobjPtr\fR or \fIstring\fR.
.AP Tk_Justify justify in
Justification style (one of the values listed below).
.BE

.SH DESCRIPTION
.PP
.VS 8.1
\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value
corresponding to \fIobjPtr\fR's value.
.VE
This value will be one of the following:
.TP
\fBTK_JUSTIFY_LEFT\fR
Means that the text on each line should start at the left edge of
the line;  as a result, the right edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_RIGHT\fR
Means that the text on each line should end at the right edge of
the line;  as a result, the left edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_CENTER\fR
Means that the text on each line should be centered;  as a result,
both the left and right edges of lines may be ragged.
.PP
.VS 8.1
Under normal circumstances the return value is \fBTCL_OK\fR and
\fIinterp\fR is unused.
If \fIobjPtr\fR doesn't contain a valid justification style
or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,

\fI*justifyPtr\fR is unmodified, and an error message is
stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
\fBTk_GetJustifyFromObj\fR caches information about the return
value in \fIobjPtr\fR, which speeds up future calls to
\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR.
.PP
\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except
that the description of the justification is specified with a string instead
of an object.  This prevents \fBTk_GetJustify\fR from caching the
return value, so \fBTk_GetJustify\fR is less efficient than
\fBTk_GetJustifyFromObj\fR.
.VE
.PP
\fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR.
Given a justify value it returns a statically-allocated string
corresponding to \fIjustify\fR.
If \fIjustify\fR isn't a legal justify value, then
``unknown justification style'' is returned.

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetOption.3,v 1.1.4.1 1998/09/30 02:15:56 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetOption 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetOption \- retrieve an option from the option database
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 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: GetPixels.3,v 1.1.4.2 1998/09/30 02:15:57 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
int
\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR
.VE
.sp
int
\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR
.sp
.VS 8.1
int
\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
.VE
.sp
int
\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR
.SH ARGUMENTS
.AS "Tcl_Interp" *joinPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Window whose screen geometry determines the conversion between absolute
units and pixels.
.VS 8.1 br
.AP Tcl_Obj *objPtr in/out
String value specifies a distance on the screen;
internal rep will be modified to cache converted distance.
.AP char *string in
Same as \fIobjPtr\fR except specification of distance is passed as
a string.
.VE
.AP int *intPtr out
Pointer to location in which to store converted distance in pixels.
.AP double *doublePtr out
Pointer to location in which to store converted distance in millimeters.
.BE

.SH DESCRIPTION
.PP
These procedures take as argument a specification of distance on
.VS 8.1
the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
.VE
corresponding distance either in integer pixels or floating-point millimeters.
In either case,
.VS 8.1
\fIobjPtr\fR or \fIstring\fR
.VE
specifies a screen distance as a
floating-point number followed by one of the following characters
that indicates units:
.TP
<none>
The number specifies a distance in pixels.
.TP
\fBc\fR
The number specifies a distance in centimeters on the screen.
.TP
\fBi\fR
The number specifies a distance in inches on the screen.
.TP
\fBm\fR
The number specifies a distance in millimeters on the screen.
.TP
\fBp\fR
The number specifies a distance in printer's points (1/72 inch)
on the screen.
.PP
.VS 8.1
\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
nearest even number of pixels and stores that value at \fI*intPtr\fR.



It returns \fBTCL_OK\fR under normal circumstances.
If an error occurs (e.g. \fIobjPtr\fR contains a number followed
by a character that isn't one of the ones above) then
\fBTCL_ERROR\fR is returned and an error message is left
in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
\fBTk_GetPixelsFromObj\fR caches information about the return
value in \fIobjPtr\fR, which speeds up future calls to
\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR.
.PP
\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except
that the screen distance is specified with a string instead
of an object.  This prevents \fBTk_GetPixels\fR from caching the
return value, so \fBTk_GetAnchor\fR is less efficient than
\fBTk_GetPixelsFromObj\fR.
.PP
\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to
\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except
that they convert the screen distance to millimeters and
store a double-precision floating-point result at \fI*doublePtr\fR.
.VE

.SH KEYWORDS
centimeters, convert, inches, millimeters, pixels, points, screen units

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetPixmap.3,v 1.1.4.1 1998/09/30 02:15:57 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 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: GetRelief.3,v 1.1.4.2 1998/09/30 02:15:57 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
.VS 8.1
int
\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR
.VE
.sp
int
\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR
.sp
char *
\fBTk_NameOfRelief(\fIrelief\fB)\fR
.SH ARGUMENTS
.AS "Tcl_Interp" *reliefPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.VS 8.1 br
.AP Tcl_Obj *objPtr in/out
String value contains name of relief (one of \fBflat\fR, \fBgroove\fR,
\fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR);
internal rep will be modified to cache corresponding relief value.
.AP char *string in
Same as \fIobjPtr\fR except description of relief is passed as
a string.

.VE
.AP int *reliefPtr out
Pointer to location in which to store relief value corresponding to
\fIobjPtr\fR or \fIname\fR.
.AP int relief in
Relief value (one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN,
TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE).
.BE

.SH DESCRIPTION
.PP
.VS 8.1
\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value
corresponding to the value of \fIobjPtr\fR.  This value will be one of
TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN,
TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE.
Under normal circumstances the return value is TCL_OK and
\fIinterp\fR is unused.
If \fIobjPtr\fR doesn't contain one of the valid relief names
or an abbreviation of one of them, then TCL_ERROR is returned,
\fI*reliefPtr\fR is unmodified, and an error message
is stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
\fBTk_GetReliefFromObj\fR caches information about the return
value in \fIobjPtr\fR, which speeds up future calls to
\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR.
.PP
\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except
that the description of the relief is specified with a string instead
of an object.  This prevents \fBTk_GetRelief\fR from caching the
return value, so \fBTk_GetRelief\fR is less efficient than
\fBTk_GetReliefFromObj\fR.
.VE
.PP
\fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR.
Given a relief value it returns the corresponding string (\fBflat\fR,

\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR).
If \fIrelief\fR isn't a legal relief value, then ``unknown relief''
is returned.

.SH KEYWORDS
name, relief, string

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetRootCrd.3,v 1.1.4.1 1998/09/30 02:15:58 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetRootCoords \- Compute root-window coordinates of window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetScroll.3,v 1.1.4.1 1998/09/30 02:15:58 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetScrollInfo 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetScrollInfo \- parse arguments for scrolling commands
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetSelect.3,v 1.1.4.1 1998/09/30 02:15:58 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetSelection \- retrieve the contents of a selection
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetUid.3,v 1.1.4.1 1998/09/30 02:15:59 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetUid 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetUid, Tk_Uid \- convert from string to unique identifier
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetVRoot.3,v 1.1.4.1 1998/09/30 02:15:59 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetVRootGeometry \- Get location and size of virtual root for window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetVisual.3,v 1.1.4.1 1998/09/30 02:15:59 stanton Exp $
'\" 
.so man.macros
.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetVisual \- translate from string to visual
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: HandleEvent.3,v 1.1.4.1 1998/09/30 02:16:00 stanton Exp $
'\" 
.so man.macros
.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_HandleEvent \- invoke event handlers for window system events
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: IdToWindow.3,v 1.1.4.1 1998/09/30 02:16:00 stanton Exp $
'\" 
.so man.macros
.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_IdToWindow \- Find Tk's window information for an X window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ImgChanged.3,v 1.1.4.1 1998/09/30 02:16:01 stanton Exp $
'\" 
.so man.macros
.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ImageChanged \- notify widgets that image needs to be redrawn
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: InternAtom.3,v 1.1.4.1 1998/09/30 02:16:01 stanton Exp $
'\" 
.so man.macros
.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MainLoop.3,v 1.1.4.1 1998/09/30 02:16:01 stanton Exp $
'\" 
.so man.macros
.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MainLoop \- loop for events until all windows are deleted
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MainWin.3,v 1.1.4.1 1998/09/30 02:16:02 stanton Exp $
'\" 
.so man.macros
.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MainWindow \- find the main window for an application
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MaintGeom.3,v 1.1.4.1 1998/09/30 02:16:02 stanton Exp $
'\" 
.so man.macros
.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ManageGeom.3,v 1.1.4.1 1998/09/30 02:16:03 stanton Exp $
'\" 
.so man.macros
.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ManageGeometry \- arrange to handle geometry requests for a window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MapWindow.3,v 1.1.4.1 1998/09/30 02:16:03 stanton Exp $
'\" 
.so man.macros
.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MeasureChar.3,v 1.1.4.3 1999/03/30 04:12:54 stanton Exp $
'\" 
.so man.macros
.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
.sp
int
\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
.sp
void
\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
.sp
void
\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
.sp
.SH ARGUMENTS
.AS "const char" firstChar
.AP Tk_Font tkfont in
Token for font in which text is to be drawn or measured.  Must have been
returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in
Text to be measured or displayed.  Need not be null terminated.  Any
non-printing meta-characters in the string (such as tabs, newlines, and
other control characters) will be measured or displayed in a
platform-dependent manner.  
.VS 8.1
.AP int numBytes in
The maximum number of bytes to consider when measuring or drawing
\fIstring\fR.  Must be greater than or equal to 0.
.VE 8.1
.AP int maxPixels in
If \fImaxPixels\fR is greater than 0, it specifies the longest permissible
line length in pixels.  Characters from \fIstring\fR are processed only
until this many pixels have been covered.  If \fImaxPixels\fR is <= 0, then
the line length is unbounded and the \fIflags\fR argument is ignored.
.AP int flags in
Various flag bits OR-ed together: TK_PARTIAL_OK means include a character
as long as any part of it fits in the length given by \fImaxPixels\fR;
otherwise, a character must fit completely to be considered.
TK_WHOLE_WORDS means stop on a word boundary, if possible.  If
TK_AT_LEAST_ONE is set, it means return at least one character even if no
characters could fit in the length given by \fImaxPixels\fR.  If
TK_AT_LEAST_ONE is set and TK_WHOLE_WORDS is also set, it means that if
not even one word fits on the line, return the first few letters of the
word that did fit; if not even one letter of the word fit, then the first
letter will still be returned.
.AP int *lengthPtr out
Filled with the number of pixels occupied by the number of characters
returned as the result of \fBTk_MeasureChars\fR.



.AP Display *display in
Display on which to draw.
.AP Drawable drawable in
Window or pixmap in which to draw.
.AP GC gc in
Graphics context for drawing characters.  The font selected into this GC 
must be the same as the \fItkfont\fR.
.AP int "x, y" in
Coordinates at which to place the left edge of the baseline when displaying
\fIstring\fR.  
.VS 8.1
.AP int firstByte in
The index of the first byte of the first character to underline in the
\fIstring\fR.  Underlining begins at the left edge of this character.
.AP int lastByte in
The index of the first byte of the last character up to which the
underline will be drawn.  The character specified by \fIlastByte\fR
will not itself be underlined.
.VE 8.1
.BE

.SH DESCRIPTION
.PP
These routines are for measuring and displaying simple single-font,
single-line, strings.  To measure and display single-font, multi-line,
justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR.
There is no programming interface in the core of Tk that supports
multi-font, multi-line text; support for that behavior must be built on
top of simpler layers.  
.VS 8.1
Note that the interfaces described here are
byte-oriented not character-oriented, so index values coming from Tcl
scripts need to be converted to byte offsets using the
\fBTcl_UtfAtIndex\fR and related routines.
.VE 8.1
.PP
A glyph is the displayable picture of a letter, number, or some other
symbol.  Not all character codes in a given font have a glyph.
Characters such as tabs, newlines/returns, and control characters that
have no glyph are measured and displayed by these procedures in a
platform-dependent manner; under X, they are replaced with backslashed
escape sequences, while under Windows and Macintosh hollow or solid boxes
may be substituted.  Refer to the documentation for
\fBTk_ComputeTextLayout\fR for a programming interface that supports the
platform-independent expansion of tab characters into columns and
newlines/returns into multi-line text.  
.PP
\fBTk_MeasureChars\fR is used both to compute the length of a given
string and to compute how many characters from a string fit in a given
amount of space.  The return value is the number of bytes from
\fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to
the conditions described by \fIflags\fR.  If all characters fit, the return
value will be \fInumBytes\fR.  \fI*lengthPtr\fR is filled with the computed
width, in pixels, of the portion of the string that was measured.  For
example, if the return value is 5, then \fI*lengthPtr\fR is filled with the
distance between the left edge of \fIstring\fR[0] and the right edge of
\fIstring\fR[4]. 
.PP
\fBTk_TextWidth\fR is a wrapper function that provides a simpler interface
to the \fBTk_MeasureChars\fR function.  The return value is how much

'\"
'\" Copyright (c) 1990-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: MoveToplev.3,v 1.1.4.1 1998/09/30 02:16:04 stanton Exp $
'\" 
.so man.macros
.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_MoveToplevelWindow \- Adjust the position of a top-level window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Name.3,v 1.1.4.1 1998/09/30 02:16:04 stanton Exp $
'\" 
.so man.macros
.TH Tk_Name 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: NameOfImg.3,v 1.1.4.1 1998/09/30 02:16:04 stanton Exp $
'\" 
.so man.macros
.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_NameOfImage \- Return name of image.
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: OwnSelect.3,v 1.1.4.1 1998/09/30 02:16:05 stanton Exp $
'\" 
.so man.macros
.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_OwnSelection \- make a window the owner of the primary selection
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: ParseArgv.3,v 1.1.4.1 1998/09/30 02:16:05 stanton Exp $
'\" 
.so man.macros
.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ParseArgv \- process command-line options
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: QWinEvent.3,v 1.1.4.1 1998/09/30 02:16:05 stanton Exp $
'\" 
.so man.macros
.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_QueueWindowEvent \- Add a window event to the Tcl event queue
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Restack.3,v 1.1.4.1 1998/09/30 02:16:06 stanton Exp $
'\" 
.so man.macros
.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_RestackWindow \- Change a window's position in the stacking order
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: RestrictEv.3,v 1.1.4.1 1998/09/30 02:16:06 stanton Exp $
'\" 
.so man.macros
.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_RestrictEvents \- filter and selectively delay X events
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetAppName.3,v 1.1.4.1 1998/09/30 02:16:07 stanton Exp $
'\" 
.so man.macros
.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_SetAppName \- Set the name of an application for ``send'' commands
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetClass.3,v 1.1.4.1 1998/09/30 02:16:07 stanton Exp $
'\" 
.so man.macros
.TH Tk_SetClass 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_SetClass, Tk_Class \- set or retrieve a window's class
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetGrid.3,v 1.1.4.1 1998/09/30 02:16:07 stanton Exp $
'\" 
.so man.macros
.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing
.SH SYNOPSIS

'\"
'\" Copyright (c) 1998 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetOptions.3,v 1.1.2.2 1998/09/30 02:16:08 stanton Exp $
'\" 
.so man.macros
.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,  Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_OptionTable
\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
.sp
\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
.sp
int
\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
.sp
int
\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
.sp
\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
.sp
\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
.sp
Tcl_Obj *
\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
.sp
Tcl_Obj *
\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
.sp
\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
.sp
int
\fBTk_Offset(\fItype, field\fB)\fR
.SH ARGUMENTS
.AS Tk_SavedOptions "*CONST objv[]" in/out
.AP Tcl_Interp *interp in
A Tcl interpreter.  Most procedures use this only for returning error
messages; if it is NULL then no error messages are returned.  For
\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the
interpreter in which the option table will be used.
.AP Tk_OptionSpec *templatePtr in
Points to an array of static information that describes the configuration
options that are supported.  Used to build a Tk_OptionTable.  The information
pointed to by this argument must exist for the lifetime of the Tk_OptionTable.
.AP Tk_OptionTable optionTable in
Token for an option table.  Must have been returned by a previous call
to \fBTk_CreateOptionTable\fR.
.AP char *recordPtr in/out
Points to structure in which values of configuration options are stored;
fields of this record are modified by procedures such as \fBTk_SetOptions\fR
and read by procedures such as \fBTk_GetOptionValue\fR.
.AP Tk_Window tkwin in
For options such as TK_OPTION_COLOR, this argument indicates
the window in which the option will be used.  If \fIoptionTable\fR uses
no window-dependent options, then a NULL value may be supplied for
this argument.
.AP int objc in
Number of values in \fIobjv\fR.
.AP Tcl_Obj "*CONST objv[]" in
Command-line arguments for setting configuring options.
.AP Tk_SavedOptions *savePtr out
If not NULL, the structure pointed to by this argument is filled
in with the old values of any options that were modified and old
values are restored automatically if an error occurs in \fBTk_SetOptions\fR.
.AP int *maskPtr out
If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the
bit-wise OR of the \fItypeMask\fR fields for the options that
were modified.
.AP Tk_SavedOptions *savedPtr in/out
Points to a structure previously filled in by \fBTk_SetOptions\fR with
old values of modified options.
.AP Tcl_Obj *namePtr in
The value of this object is the name of a particular option.  If NULL
is passed to \fBTk_GetOptionInfo\fR then information is returned for
all options.  Must not be NULL when \fBTk_GetOptionValue\fR is called.
.AP "type name" type in
The name of the type of a record.
.AP "field name" field in
The name of a field in records of type \fItype\fR.
.BE
.SH DESCRIPTION
.PP
These procedures handle most of the details of parsing configuration
options such as those for Tk widgets.  Given a description of what
options are supported, these procedures handle all the details of
parsing options and storing their values into a C structure associated
with the widget or object. The procedures were designed primarily for
widgets in Tk, but they can also be used for other kinds of objects that
have configuration options.  In the rest of this manual page ``widget'' will
be used to refer to the object whose options are being managed; in
practice the object may not actually be a widget.  The term ``widget
record'' is used to refer to the C-level structure in
which information about a particular widget or object is stored.
.PP
Note: the easiest way to learn how to use these procedures is to
look at a working example.  In Tk, the simplest example is the code
that implements the button family of widgets, which is an \fBtkButton.c\fR.
Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
.PP
In order to use these procedures, the code that implements the widget
must contain a static array of Tk_OptionSpec structures. This is a
template that describes the various options supported by that class of
widget; there is a separate template for each kind of widget.  The
template contains information such as the name of each option, its type,
its default value, and where the value of the option is stored in the
widget record.  See TEMPLATES below for more detail.
.PP
In order to process configuration options efficiently, the static
template must be augmented with additional information that is available
only at runtime.  The procedure \fBTk_CreateOptionTable\fR creates this
dynamic information from the template and returns a Tk_OptionTable token
that describes both the static and dynamic information.  All of the
other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable
token as argument.  Typically, \fBTk_CreateOptionTable\fR is called the
first time that a widget of a particular class is created and the
resulting Tk_OptionTable is used in the future for all widgets of that
class.  A Tk_OptionTable may be used only in a single interpreter, given
by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR.  When an
option table is no longer needed \fBTk_DeleteOptionTable\fR should be
called to free all of its resources.  All of the option tables
for a Tcl interpreter are freed automatically if the interpreter is deleted.
.PP
\fBTk_InitOptions\fR is invoked when a new widget is created to set
the default values for all of the widget's configuration options.
\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR)
and a pointer to a widget record (\fIrecordPtr\fR), which is the C
structure that holds information about this widget. \fBTk_InitOptions\fR
uses the information in the option table to
choose an appropriate default for each option, then it stores the default
value directly into the widget record, overwriting any information that
was already present in the widget record.  \fBTk_InitOptions\fR normally
returns TCL_OK.  If an error occurred while setting the default values
(e.g., because a default value was erroneous) then TCL_ERROR is returned
and an error message is left in \fIinterp\fR's result if \fIinterp\fR
isn't NULL.
.PP
\fBTk_SetOptions\fR is invoked to modify configuration options based
on information specified in a Tcl command.  The command might be one that
creates a new widget, or a command that modifies options on an existing
widget.  The \fIobjc\fR and \fIobjv\fR arguments describe the
values of the arguments from the Tcl command.  \fIObjv\fR must contain
an even number of objects: the first object of each pair gives the name of
an option and the second object gives the new value for that option.
\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that
the new value of the option conforms to the type in \fIoptionTable\fR,
and stores the value of the option into the widget record given by
\fIrecordPtr\fR.  \fBTk_SetOptions\fR normally returns TCL_OK.  If
an error occurred (such as an unknown option name or an illegal option
value) then TCL_ERROR is returned and an error message is left in
\fIinterp\fR's result if \fIinterp\fR isn't NULL.
.PP
\fBTk_SetOptions\fR has two additional features.  First, if the
\fImaskPtr\fR argument isn't NULL then it points to an integer
value that is filled in with information about the options that were
modified.  For each option in the template passed to
\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field.  The
bits of this field are defined by the code that implements the widget;
for example, each bit might correspond to a particular configuration option.
Alternatively, bits might be used functionally.  For example, one bit might
be used for redisplay: all options that affect the widget's display, such
that changing the option requires the widget to be redisplayed, might have
that bit set.  Another bit might indicate that the geometry of the widget
must be recomputed, and so on.  \fBTk_SetOptions\fR OR's together the
\fItypeMask\fR fields from all the options that were modified and returns
this value at *\fImaskPtr\fR; the caller can then use this information
to optimize itself so that, for example, it doesn't redisplay the widget
if the modified options don't affect the widget's appearance.
.PP
The second additional feature of \fBTk_SetOptions\fR has to do with error
recovery.  If an error occurs while processing configuration options, this
feature makes it possible to restore all the configuration options to their
previous values.  Errors can occur either while processing options in
\fBTk_SetOptions\fR or later in the caller.  In many cases the caller does
additional processing after \fBTk_SetOptions\fR returns; for example, it
might use an option value to set a trace on a variable and may detect
an error if the variable is an array instead of a scalar.  Error recovery
is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument
to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized
Tk_SavedOptions structure on the caller's stack.  \fBTk_SetOptions\fR
overwrites the structure pointed to by \fIsavePtr\fR with information
about the old values of any options modified by the procedure.
If \fBTk_SetOptions\fR returns successfully, the
caller uses the structure in one of two ways.  If the caller completes
its processing of the new options without any errors, then it must pass
the structure to \fBTk_FreeSavedOptions\fR so that the old values can be
freed.  If the caller detects an error in its processing of the new
options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR,
which will copy the old values back into the widget record and free
the new values.
If \fBTk_SetOptions\fR detects an error then it automatically restores
any options that had already been modified and leaves *\fIsavePtr\fR in
an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or
\fBTk_RestoreSavedOptions\fR.
If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then
\fBTk_SetOptions\fR frees each old option value immediately when it sets a new
value for the option.  In this case, if an error occurs in the third
option, the old values for the first two options cannot be restored.
.PP
\fBTk_GetOptionValue\fR returns the current value of a configuration option
for a particular widget.  The \fInamePtr\fR argument contains the name of
an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR
to lookup the option and extract its value from the widget record
pointed to by \fIrecordPtr\fR, then it returns an object containing
that value.  If an error occurs (e.g., because \fInamePtr\fR contains an
unknown option name) then NULL is returned and an error message is left
in \fIinterp\fR's result unless \fIinterp\fR is NULL.
.PP
\fBTk_GetOptionInfo\fR returns information about configuration options in
a form suitable for \fBconfigure\fR widget commands.  If the \fInamePtr\fR
argument is not NULL, it points to an object that gives the name of a
configuration option; \fBTk_GetOptionInfo\fR returns an object containing
a list with five elements, which are the name of the option, the name and
class used for the option in the option database, the default value for
the option, and the current value for the option.  If the \fInamePtr\fR
argument is NULL, then \fBTk_GetOptionInfo\fR returns information about
all options in the form of a list of lists; each sublist describes one
option.  Synonym options are handled differently depending on whether
\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for
each synonym option has only two elements, which are the name of the
option and the name of the other option that it refers to; if \fInamePtr\fR
is non-NULL and names a synonym option then the object returned
is the five-element list
for the other option that the synonym refers to.  If an error occurs
(e.g., because \fInamePtr\fR contains an unknown option name) then NULL
is returned and an error message is left in \fIinterp\fR's result unless
\fIinterp\fR is NULL.
.PP
\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted.
It frees all of the resources associated with any of the configuration
options defined in \fIrecordPtr\fR by \fIoptionTable\fR.
.PP
The \fBTk_Offset\fR macro is provided as a safe way of generating the
\fIobjOffset\fR and \fIinternalOffset\fR values for entries in
Tk_OptionSpec structures.  It takes two arguments: the name of a type
of record, and the name of a field in that record. It returns the byte
offset of the named field in records of the given type.

.SH "TEMPLATES"
.PP
The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR
via its \fItemplatePtr\fR argument describes the configuration options
supported by a particular class of widgets.  Each structure specifies
one configuration option and has the following fields:
.CS
typedef struct {
	Tk_OptionType \fItype\fR;
	char *\fIoptionName\fR;
	char *\fIdbName\fR;
	char *\fIdbClass\fR;
	char *\fIdefValue\fR;
	int \fIobjOffset\fR;
	int \fIinternalOffset\fR;
	int \fIflags\fR;
	ClientData \fIclientData\fR;
	int \fItypeMask\fR;
} Tk_OptionSpec;
.CE
The \fItype\fR field indicates what kind of configuration option this is
(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for
an integer value).  \fIType\fR determines how the
value of the option is parsed (more on this below).
The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR;
it is the name used for the option in Tcl commands and passed to
procedures via the \fIobjc\fR or \fInamePtr\fR arguments.
The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR
to look up a default value for this option in the option database; if
\fIdbName\fR is NULL then the option database is not used by
\fBTk_InitOptions\fR for this option.  The \fIdefValue\fR field
specifies a default value for this configuration option if no
value is specified in the option database.  The \fIobjOffset\fR and
\fIinternalOffset\fR fields indicate where to store the value of this
option in widget records (more on this below); values for the \fIobjOffset\fR
and \fIinternalOffset\fR fields should always be generated with the
\fBTk_Offset\fR macro.
The \fIflags\fR field contains additional information
to control the processing of this configuration option (see below
for details).
\fIClientData\fR provides additional type-specific data needed
by certain types.  For instance, for TK_OPTION_COLOR types,
\fIclientData\fR is a string giving the default value to use on
monochrome displays.  See the descriptions of the different types
below for details.
The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to
return information about which options were modified; see the description
of \fBTk_SetOptions\fR above for details.
.PP
When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an
option into the widget record, they can do it in either of two ways.
If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than
or equal to zero, then the value of the option is stored as a
(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR.
If the \fIinternalOffset\fR field of the Tk_OptionSpec is
greater than or equal to zero, then the value of the option is stored
in a type-specific internal form at the location in the widget record
given by \fIinternalOffset\fR.  For example, if the option's type is
TK_OPTION_INT then the internal form is an integer.  If the
\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the
value is not stored in that form.  At least one of the offsets must be
greater than or equal to zero.
.PP
The \fIflags\fR field consists of one or more bits ORed together.  At
present only a single flag is supported: TK_OPTION_NULL_OK.  If
this bit is set for an option then an empty string will be accepted as
the value for the option and the resulting internal form will be a
NULL pointer or \fBNone\fR, depending on the type of the option.
If the flag is not set then empty strings will result
in errors.
TK_OPTION_NULL_OK is typically used to allow a
feature to be turned off entirely, e.g. set a cursor value to
\fBNone\fR so that a window simply inherits its parent's cursor.
Not all option types support the TK_OPTION_NULL_OK
flag; for those that do, there is an explicit indication of that fact
in the descriptions below.
.PP
The \fItype\fR field of each Tk_OptionSpec structure determines
how to parse the value of that configuration option. The
legal value for \fItype\fR, and the corresponding actions, are
described below.  If the type requires a \fItkwin\fR value to be
passed into procedures like \fBTk_SetOptions\fR, or if it uses
the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated
explicitly; if not mentioned, the type requires neither \fItkwin\fR
nor \fIclientData\fR.
.TP
\fBTK_OPTION_ANCHOR\fR
The value must be a standard anchor position such as \fBne\fR or
\fBcenter\fR.  The internal form is a Tk_Anchor value like the ones
returned by \fBTk_GetAnchorFromObj\fR.
.TP
\fBTK_OPTION_BITMAP\fR
The value must be a standard Tk bitmap name. The internal form is a
Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_BOOLEAN\fR
The value must be a standard boolean value such as \fBtrue\fR or
\fBno\fR.  The internal form is an integer with value 0 or 1.
.TP
\fBTK_OPTION_BORDER\fR
The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
The internal form is a Tk_3DBorder token like the ones returned
by \fBTk_Alloc3DBorderFromObj\fR.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_COLOR\fR
The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
The internal form is an (XColor *) token like the ones returned by
\fBTk_AllocColorFromObj\fR.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_CURSOR\fR
The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR.
The internal form is a Tk_Cursor token like the ones returned by
\fBTk_AllocCursorFromObj\fR.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR, and when the option is set the cursor
for the window is changed by calling \fBXDefineCursor\fR.  This
option type also supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_DOUBLE\fR
The string value must be a floating-point number in
the format accepted by \fBstrtol\fR.  The internal form is a C
\fBdouble\fR value.
.TP
\fBTK_OPTION_END\fR
Marks the end of the template.  There must be a Tk_OptionSpec structure
with \fItype\fR TK_OPTION_END at the end of each template.  If the
\fIclientData\fR field of this structure isn't NULL, then it points to
an additional array of Tk_OptionSpec's, which is itself terminated by
another TK_OPTION_END entry.  Templates may be chained arbitrarily
deeply.  This feature allows common options to be shared by several
widget classes.
.TP
\fBTK_OPTION_FONT\fR
The value must be a standard font name such as \fBTimes 16\fR.
The internal form is a Tk_Font handle like the ones returned by
\fBTk_AllocFontFromObj\fR.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_INT\fR
The string value must be an integer in the format accepted by
\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to
specify octal or hexadecimal numbers, respectively).  The internal
form is a C \fBint\fR value.
.TP
\fBTK_OPTION_JUSTIFY\fR
The value must be a standard justification value such as \fBleft\fR.
The internal form is a Tk_Justify like the values returned by
\fBTk_GetJustifyFromObj\fR.
.TP
\fBTK_OPTION_PIXELS\fR
The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR.
The internal form is an integer value giving a
distance in pixels, like the values returned by
\fBTk_GetPixelsFromObj\fR.  Note: if the \fIobjOffset\fR field isn't
used then information about the original value of this option will be lost.
See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.
.TP
\fBTK_OPTION_RELIEF\fR
The value must be standard relief such as \fBraised\fR.
The internal form is an integer relief value such as
TK_RELIEF_RAISED.
.TP
\fBTK_OPTION_STRING\fR
The value may be any string.  The internal form is a (char *) pointer
that points to a dynamically allocated copy of the value.
This option type supports the TK_OPTION_NULL_OK flag.
.TP
\fBTK_OPTION_STRING_TABLE\fR
For this type, \fIclientData\fR is a pointer to an array of strings
suitable for passing to \fBTcl_GetIndexFromObj\fR.  The value must
be one of the strings in the table, or a unique abbreviation of
one of the strings.  The internal form is an integer giving the index
into the table of the matching string, like the return value
from \fBTcl_GetStringFromObj\fR. 
.TP
\fBTK_OPTION_SYNONYM\fR
This type is used to provide alternative names for an option (for
example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR).
The \fBclientData\fR field is a (char *) pointer that gives
the name of another option in the same table.  Whenever the
synonym option is used, the information from the other option
will be used instead.
.TP
\fBTK_OPTION_WINDOW\fR
The value must be a window path name.  The internal form is a
\fBTk_Window\fR token for the window.
This option type requires \fItkwin\fR to be supplied to procedures
such as \fBTk_SetOptions\fR (in order to identify the application),
and it supports the TK_OPTION_NULL_OK flag.

.SH "STORAGE MANAGEMENT ISSUES"
.PP
If a field of a widget record has its offset stored in the \fIobjOffset\fR
or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the
procedures described here will handle all of the storage allocation and
resource management issues associated with the field.  When the value
of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR
will automatically free any resources associated with the old value, such as
Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
TK_OPTION_STRING options.  For an option stored as an object using the
\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the
object pointed to by the \fIobjv\fR value from the call to
\fBTk_SetOptions\fR.  The reference count for this object is incremented
when a pointer to it is stored in the widget record and decremented when
the option is modified.  When the widget is deleted
\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources
associated with all options and decrement reference counts for any
objects.
.PP
However, the widget code is responsible for storing NULL or \fBNone\fR in
all pointer and token fields before invoking \fBTk_InitOptions\fR.
This is needed to allow proper cleanup in the rare case where
an error occurs in \fBTk_InitOptions\fR.

.SH "OBJOFFSET VS. INTERNALOFFSET"
.PP
In most cases it is simplest to use the \fIinternalOffset\fR field of
a Tk_OptionSpec structure and not the \fIobjOffset\fR field.  This
makes the internal form of the value immediately available to the
widget code so the value doesn't have to be extracted from an object
each time it is used.  However, there are two cases where the
\fIobjOffset\fR field is useful.  The first case is for
TK_OPTION_PIXELS options.  In this case, the internal form is
an integer pixel value that is valid only for a particular screen.
If the value of the option is retrieved, it will be returned as a simple
number.  For example, after the command \fB.b configure \-borderwidth 2m\fR,
the command \fB.b configure \-borderwidth\fR might return 7, which is the
integer pixel value corresponding to \fB2m\fR.  Unfortunately, this loses
the original screen-independent value.  Thus for TK_OPTION_PIXELS options
it is better to use the \fIobjOffset\fR field.  In this case the original
value of the option is retained in the object and can be returned when
the option is retrieved.  In most cases it is convenient to use the
\fIinternalOffset\fR field field as well, so that the integer value is
immediately available for use in the widget code (alternatively,
\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from
the object whenever it is needed).  Note: the problem of losing information
on retrievals exists only for TK_OPTION_PIXELS options.
.PP
The second reason to use the \fIobjOffset\fR field is in order to
implement new types of options not supported by these procedures.
To implement a new type of option, use TK_OPTION_STRING as
the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field
but not the \fIinternalOffset\fR field.  Then, after calling
\fBTk_SetOptions\fR, convert the object to internal form yourself.

.SH KEYWORDS
anchor, bitmap, boolean, border, color, configuration option,
cursor, double, font, integer, justify,
pixels, relief, screen distance, synonym

'\"
'\" Copyright (c) 1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: SetVisual.3,v 1.1.4.1 1998/09/30 02:16:08 stanton Exp $
'\" 
.so man.macros
.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_SetWindowVisual \- change visual characteristics of window
.SH SYNOPSIS

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: StrictMotif.3,v 1.1.4.1 1998/09/30 02:16:08 stanton Exp $
'\" 
.so man.macros
.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_StrictMotif \- Return value of tk_strictMotif variable
.SH SYNOPSIS

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: TextLayout.3,v 1.1.4.2 1999/03/30 04:12:54 stanton Exp $
'\" 
.so man.macros
.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp

.AP "const char" *string in
Potentially multi-line string whose dimensions are to be computed and
stored in the text layout.  The \fIstring\fR must remain valid for the
lifetime of the text layout.  
.AP int numChars in
The number of characters to consider from \fIstring\fR.  If
\fInumChars\fR is less than 0, then assumes \fIstring\fR is null
.VS 8.1
terminated and uses \fBTcl_NumUtfChars\fR to determine the length of
\fIstring\fR.
.VE
.AP int wrapLength in
Longest permissible line length, in pixels.  Lines in \fIstring\fR will
automatically be broken at word boundaries and wrapped when they reach
this length.  If \fIwrapLength\fR is too small for even a single
character to fit on a line, it will be expanded to allow one character to
fit on each line.  If \fIwrapLength\fR is <= 0, there is no automatic
wrapping; lines will get as long as they need to be and only wrap if a

.SH DESCRIPTION
.PP
These routines are for measuring and displaying single-font, multi-line,
justified text.  To measure and display simple single-font, single-line
strings, refer to the documentation for \fBTk_MeasureChars\fR.  There is
no programming interface in the core of Tk that supports multi-font,
multi-line text; support for that behavior must be built on top of
simpler layers.  
.VS 8.1
Note that unlike the lower level text display routines, the functions
described here all operate on character-oriented lengths and indices
rather than byte-oriented values.  See the description of
\fBTcl_UtfAtIndex\fR for more details on converting between character
and byte offsets.
.VE 8.1
.PP
The routines described here are built on top of the programming interface
described in the \fBTk_MeasureChars\fR documentation.  Tab characters and
newline/return characters may be treated specially by these procedures,
but all other characters are passed through to the lower level.
.PP
\fBTk_ComputeTextLayout\fR computes the layout information needed to

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Tk_Init.3,v 1.1.4.1 1998/09/30 02:16:09 stanton Exp $
'\" 
.so man.macros
.TH Tk_Init 3 4.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Init \- add Tk to an interpreter and make a new Tk application.
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: Tk_Main.3,v 1.1.4.1 1998/09/30 02:16:10 stanton Exp $
'\" 
.so man.macros
.TH Tk_Main 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_Main \- main program for Tk-based applications
.SH SYNOPSIS

'\"
'\" Copyright (c) 1990-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: WindowId.3,v 1.1.4.1 1998/09/30 02:16:10 stanton Exp $
'\" 
.so man.macros
.TH Tk_WindowId 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, Tk_Visual, Tk_Depth, Tk_Colormap  \- retrieve information from Tk's local data structure
.SH SYNOPSIS

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: bell.n,v 1.1.4.1 1998/09/30 02:16:10 stanton Exp $
'\" 
.so man.macros
.TH bell n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bell \- Ring a display's bell

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 1998 by Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: bind.n,v 1.1.4.2 1998/11/25 21:16:29 stanton Exp $
'\" 
.so man.macros
.TH bind n 8.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bind \- Arrange for X events to invoke Tcl scripts
.SH SYNOPSIS
\fBbind\fI tag\fR
.sp

For example, \fB<Double-Button-1>\fR
is equivalent to \fB<Button-1><Button-1>\fR with the extra
time and space requirement.

.SH "EVENT TYPES"
.PP
The \fItype\fR field may be any of the standard X event types, with a
few extra abbreviations.  The \fItype\fR field will also accept a
couple non-standard X event types that were added to better support
the Macintosh and Windows platforms.  Below is a list of all the valid
types; where two names appear together, they are synonyms.
.DS C
.ta 5c 10c
\fBActivate	Enter	Map
ButtonPress, Button	Expose	Motion
.VS
ButtonRelease	FocusIn	MouseWheel	
.VE
Circulate	FocusOut	Property
Colormap	Gravity	Reparent
Configure	KeyPress, Key	Unmap
Deactivate	KeyRelease	Visibility
Destroy	Leave\fR
.DE
.PP
.VS
Most of the above events have the same fields and behaviors as events
in the X Windowing system.  You can find more detailed descriptions of
these events in any X window programming book.  A couple of the events
are extensions to the X event system to support features unique to the
Macintosh and Windows platforms.  We provide a little more detail on
these events here.  These include:
.IP \fBActivate\fR 5
.IP \fBDeactivate\fR 5
These two events are sent to every sub-window of a toplevel when they
change state.  In addition to the focus Window, the Macintosh platform
and Windows platforms have a notion of an active window (which often
has but is not required to have the focus).  On the Macintosh, widgets
in the active window have a different appearance than widgets in
deactive windows.  The \fBActivate\fR event is sent to all the
sub-windows in a toplevel when it changes from being deactive to
active.  Likewise, the \fBDeactive\fR event is sent when the window's
state changes from active to deactive.  There are no useful percent
substitutions you would make when binding to these events.
.IP \fBMouseWheel\fR 5
Some mice on the Windows platform support a mouse wheel which is used
for scrolling documents without using the scrollbars.  By rolling the
wheel, the system will generate \fBMouseWheel\fR events that the
application can use to scroll.  Like \fBKey\fR events the event is
always routed to the window that currently has focus. When the event
is received you can use the \fB%D\fR substitution to get the
\fIdelta\fR field for the event which is a integer value of motion
that the mouse wheel has moved.  The smallest value for which the
system will report is defined by the OS.  On Windows 95 & 98 machines
this value is at least 120 before it is reported.  However, higher
resolution devices may be available in the future.  The sign of the
value determines which direction your widget should scroll.  Positive
values should scroll up and negative values should scroll down.
.VE
.PP
The last part of a long event specification is \fIdetail\fR.  In the
case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
number of a button (1-5).  If a button number is given, then only an
event on that particular button will match;  if no button number is
given, then an event on any button will match.  Note:  giving a
specific button number is different than specifying a button modifier;

For events other than these, the substituted string is undefined.
.RE
.IP \fB%f\fR 5
The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR).  Valid only
for \fBEnter\fR and \fBLeave\fR events.
.IP \fB%h\fR 5
.VS
The \fIheight\fR field from the event.  Valid for the \fBConfigure\fR and
\fBExpose\fR events.
.VE
.IP \fB%k\fR 5
The \fIkeycode\fR field from the event.  Valid only for \fBKeyPress\fR
and \fBKeyRelease\fR events.
.IP \fB%m\fR 5
The \fImode\fR field from the event.  The substituted string is one of

the empty string if the event doesn't correspond to an ASCII character
(e.g. the shift key was pressed).  \fBXLookupString\fR does all the
work of translating from the event to an ASCII character.
Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
.IP \fB%B\fR 5
The \fIborder_width\fR field from the event.  Valid only for
\fBConfigure\fR events.
.VS
.IP \fB%D\fR 5
This reports the \fIdelta\fR value of a \fBMouseWheel\fR event.  The
\fIdelta\fR value represents the rotation units the mouse wheel has
been moved.  On Windows 95 & 98 systems the smallest value for the
delta is 120.  Future systems may support higher resolution values for
the delta.  The sign of the value represents the direction the mouse
wheel was scrolled.
.VE
.IP \fB%E\fR 5
The \fIsend_event\fR field from the event.  Valid for all event types.
.IP \fB%K\fR 5
The keysym corresponding to the event, substituted as a textual
string.  Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
.IP \fB%N\fR 5
The keysym corresponding to the event, substituted as a decimal

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: bindtags.n,v 1.1.4.1 1998/09/30 02:16:11 stanton Exp $
'\" 
.so man.macros
.TH bindtags n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bindtags \- Determine which bindings apply to a window, and order of evaluation

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: bitmap.n,v 1.1.4.1 1998/09/30 02:16:11 stanton Exp $
'\" 
.so man.macros
.TH bitmap n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bitmap \- Images that display two colors

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: button.n,v 1.1.4.1 1998/09/30 02:16:12 stanton Exp $
'\" 
.so man.macros
.TH button n 4.4 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
button \- Create and manipulate button widgets

'\"
'\" Copyright (c) 1992-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: canvas.n,v 1.1.4.2 1998/11/25 21:16:29 stanton Exp $
'\"
.so man.macros
.TH canvas n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
canvas \- Create and manipulate canvas widgets

the top center point of the rectangular region occupied by the
text will be at the positioning point.
This option defaults to \fBcenter\fR.
.TP
\fB\-fill \fIcolor\fR
\fIColor\fR specifies a color to use for filling the text characters;
it may have any of the forms accepted by \fBTk_GetColor\fR.
If \fIcolor\fR is an empty string then the text will be transparent.
If this option isn't specified then it defaults to \fBblack\fR.
.TP
\fB\-font \fIfontName\fR
Specifies the font to use for the text item.
\fIFontName\fR may be any string acceptable to \fBTk_GetFontStruct\fR.
If this option isn't specified, it defaults to a system-dependent
font.

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: checkbutton.n,v 1.1.4.1 1998/09/30 02:16:13 stanton Exp $
'\" 
.so man.macros
.TH checkbutton n 4.4 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
checkbutton \- Create and manipulate checkbutton widgets

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: chooseColor.n,v 1.1.4.1 1998/09/30 02:16:13 stanton Exp $
'\" 
.so man.macros
.TH tk_chooseColor n 4.2 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tk_chooseColor \- pops up a dialog box for the user to select a color.

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: clipboard.n,v 1.1.4.1 1998/09/30 02:16:14 stanton Exp $
'\" 
.so man.macros
.TH clipboard n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
clipboard \- Manipulate Tk clipboard

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: destroy.n,v 1.1.4.1 1998/09/30 02:16:15 stanton Exp $
'\" 
.so man.macros
.TH destroy n "" Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
destroy \- Destroy one or more windows

'\"
'\" Copyright (c) 1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: dialog.n,v 1.1.4.1 1998/09/30 02:16:15 stanton Exp $
'\" 
.so man.macros
.TH tk_dialog n 4.1 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tk_dialog \- Create modal dialog and wait for response

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: entry.n,v 1.1.4.1 1998/09/30 02:16:16 stanton Exp $
'\" 
.so man.macros
.TH entry n 4.1 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
entry \- Create and manipulate entry widgets

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\" Copyright (c) 1998 by Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: event.n,v 1.1.4.2 1998/11/25 21:16:29 stanton Exp $
'\" 
.so man.macros
.TH event n 8.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
event \- Miscellaneous event facilities: define virtual events and generate events
.SH SYNOPSIS
\fBevent\fI option \fR?\fIarg arg ...\fR?
.BE

any button  number provided in the base \fIevent\fR argument.
Corresponds to the \fB%b\fR substitution for binding scripts.
.TP
\fB\-count\fI number\fR
\fINumber\fR must be an integer;  it specifies the \fIcount\fR field
for the event.  Valid for \fBExpose\fR events.
Corresponds to the \fB%c\fR substitution for binding scripts.
.TP
\fB\-delta\fI number\fR
.VS
\fINumber\fR must be an integer;  it specifies the \fIdelta\fR field
for the \fBMouseWheel\fR event.  The \fIdelta\fR refers to the
direction and magnitude the mouse wheel was rotated.  Note the value
is not a screen distance but are units of motion in the mouse wheel.
Typically these values are multiples of 120.  For example, 120 should
scroll the text widget up 4 lines and -240 would scroll the text
widget down 8 lines.  Of course, other widgets may define different
behaviors for mouse wheel motion.  This field corresponds to the
\fB%D\fR substitution for binding scripts.
.VE
.TP
\fB\-detail\fI detail\fR
\fIDetail\fR specifies the \fIdetail\fR field for the event
and must be one of the following:
.RS
.DS
.ta 6c

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: focus.n,v 1.1.4.1 1998/09/30 02:16:17 stanton Exp $
'\" 
.so man.macros
.TH focus n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
focus \- Manage the input focus

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: focusNext.n,v 1.1.4.1 1998/09/30 02:16:17 stanton Exp $
'\" 
.so man.macros
.TH tk_focusNext n 4.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tk_focusNext, tk_focusPrev, tk_focusFollowsMouse \- Utility procedures for managing the input focus.

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: font.n,v 1.1.4.1 1998/09/30 02:16:18 stanton Exp $
'\" 
.so man.macros
.TH font n 8.0 Tk "Tk Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
font \- Create and inspect fonts.