From 0cc374250b55b7362e02c5a8720ae9e06cbec14f Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 10 Mar 2009 11:13:52 +0000 Subject: Tidy up and expand examples. --- ChangeLog | 114 +++++++++++++++++++++++++++++++----------------------------- doc/event.n | 47 ++++++++++++++++++++----- 2 files changed, 97 insertions(+), 64 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1685ab6..a7646c4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,30 +1,34 @@ +2009-03-10 Donal K. Fellows + + * doc/event.n: Tidy up and improve examples. + 2009-03-09 Benjamin Riefenstahl - * tkMacOSXFont.c (GetFontFamilyName): [Bug #2548661] Handle NULL + * tkMacOSXFont.c (GetFontFamilyName): [Bug 2548661]: Handle NULL return from CFStringCreate. 2009-02-27 Jan Nijtmans - * doc/GetBitmap.3 [Feature Request 2636558] Tk_DefineBitmap + * doc/GetBitmap.3 [Feature Request 2636558]: Tk_DefineBitmap * generic/tk.decls and Tk_GetBitmapFromData signature problem * generic/tkInt.decls * generic/tkBitmap.c * generic/tkInt.h * generic/tkStubInit.c - * generic/tkDecls.h (regenerated) - * generic/tkIntDecls.h (regenerated) + * generic/tkDecls.h: (regenerated) + * generic/tkIntDecls.h: (regenerated) * macosx/tkMacOSXBitmap.c 2009-02-27 Pat Thoyts - * generic/tkWindow.c: [Bug 2645457] check for dead windows after + * generic/tkWindow.c: [Bug 2645457]: Check for dead windows after calling Tk_MakeWindowExist to avoid a crash when mapping dead windows. 2009-02-23 Pat Thoyts - * win/rc/*.cur: [Patch 2513104] fix cursor hotspots (cjmcdonald) + * win/rc/*.cur: [Patch 2513104]: Fix cursor hotspots (cjmcdonald) - * win/tkWinMenu.c: Applied patch for menu image display bug + * win/tkWinMenu.c: Applied patch for menu image display bug. [Bug 1329198, 456299] [Patch 2507419] (cjmcdonald) 2009-02-22 Pat Thoyts @@ -37,21 +41,21 @@ * library/ttk/vistaTheme.tcl: Correct the ttk::treeview border on * win/ttkWinXpTheme.c: XP and vista. - * library/console.tcl: [Bug 2546087] In 2004 a fix to Tcl channels + * library/console.tcl: [Bug 2546087]: In 2004 a fix to Tcl channels prevented the exposure of the internal UTF-8 representation of the - ASCII NUL character (\uc080). Since then strings in the console - have been truncated at NUL. This restores the older behaviour. + ASCII NUL character (\uc080). Since then strings in the console have + been truncated at NUL. This restores the older behaviour. 2009-02-17 Jeff Hobbs - * win/tcl.m4, win/configure: Check if cl groks _WIN64 already to - avoid CC manipulation that can screw up later configure checks. - Use 'd'ebug runtime in 64-bit builds. + * win/tcl.m4, win/configure: Check if cl groks _WIN64 already to avoid + CC manipulation that can screw up later configure checks. Use 'd'ebug + runtime in 64-bit builds. 2009-02-16 Jeff Hobbs - * win/configure.in, win/configure: align better with tcl - version. Ensures finding correct CPP for Win64. + * win/configure.in, win/configure: Align better with tcl version. + Ensures finding correct CPP for Win64. 2009-02-16 Donal K. Fellows @@ -76,16 +80,16 @@ 2009-02-10 Jan Nijtmans - * unix/tcl.m4: fix [tcl-Bug 2502365]: Building of head on HPUX is - broken when using the native CC. + * unix/tcl.m4: fix [Bug 2502365]: Building of head on HPUX is broken + when using the native CC. * unix/configure (autoconf-2.59) 2008-02-08 Joe English - * generic/ttk/*.[ch]: Renamed several internal data structures - and functions: ElementImpl -> ElementClass, LayoutNode -> Element. - Remove more unnecessary casts. Add function Ttk_ClientRegion, - common factor of entry, scale, progress, and treeview widgets. + * generic/ttk/*.[ch]: Renamed several internal data structures and + functions: ElementImpl -> ElementClass, LayoutNode -> Element. Remove + more unnecessary casts. Add function Ttk_ClientRegion, common factor + of entry, scale, progress, and treeview widgets. * generic/ttk/ttkTrack.c: Fix [Bug 2431428]. 2008-02-06 Daniel Steffen @@ -155,39 +159,38 @@ * unix/Makefile.in: Added a CONFIG_INSTALL_DIR parameter so that * unix/tcl.m4: distributors can control where tclConfig.sh goes. - Made the installation of 'ldAix' conditional - upon actually being on an AIX system. Allowed for downstream - packagers to customize SHLIB_VERSION on BSD-derived systems. + Made the installation of 'ldAix' conditional upon actually being on an + AIX system. Allowed for downstream packagers to customize + SHLIB_VERSION on BSD-derived systems. Thanks to Stuart Cassoff for [Patch 907924]. * unix/configure: Autoconf 2.59 2009-01-16 Don Porter * generic/tk.h: Bump patchlevel to 8.6b1.1 to distinguish - * library/tk.tcl: CVS snapshots from the 8.6b1 and 8.6b2 releases. - * unix/configure.in: + * library/tk.tcl: CVS snapshots from the 8.6b1 and 8.6b2 + * unix/configure.in: releases. * win/configure.in: * unix/configure: autoconf-2.59 * win/configure: - 2009-01-14 Jan Nijtmans - * generic/tkImgPhoto.c: fix for aMSN compatibility [tcl-Bug 2507326] + * generic/tkImgPhoto.c: [Bug 2507326]: Fix for aMSN compatibility * generic/tkMenu.h: CONSTify Tk(Create|Find)MenuReferences * generic/tkMenu.c: various internal "const" decorations. 2009-01-13 Jan Nijtmans - * unix/tcl.m4: fix [tcl-Bug 2502365] Building of head on - HPUX is broken when using the native CC + * unix/tcl.m4: fix [Bug 2502365]: Building of head on HPUX is broken + when using the native CC * unix/configure (autoconf-2.59) 2009-01-13 Pat Thoyts - * tests/constraints.tcl: Made the tests more independent of the presence - * tests/*.test: of images in the interpreter. + * tests/constraints.tcl: Made the tests more independent of the + * tests/*.test: presence of images in the interpreter. 2009-01-11 Pat Thoyts @@ -195,21 +198,21 @@ 2009-01-11 George Peter Staplin - * generic/tkEvent.c: Fix a possible segv due to a NULL - pointer dereference that occurs when XCreateIC fails. + * generic/tkEvent.c: Fix a possible segv due to a NULL pointer + dereference that occurs when XCreateIC fails. 2009-01-11 Pat Thoyts - * library/bgerror.tcl: Pretty up the unix tk_messageBox - * library/icons.tcl: icons with PNG images and grouped - * library/msgbox.tcl: all the stock icons in one file. + * library/bgerror.tcl: Pretty up the unix tk_messageBox icons with PNG + * library/icons.tcl: images and grouped all the stock icons in one + * library/msgbox.tcl: file. * library/tk.tcl: 2009-01-11 Joe English - * generic/ttk/ttkNotebook.c(NotebookCleanup): - Don't call Tk_DeleteOptionTable(), it's unnecessary - and quite possibly harmful [Bug 2496162]. + * generic/ttk/ttkNotebook.c (NotebookCleanup): [Bug 2496162]: Don't + call Tk_DeleteOptionTable(), it's unnecessary and quite possibly + harmful. 2009-01-08 Jan Nijtmans @@ -225,26 +228,27 @@ 2009-01-08 Pat Thoyts - * library/bgerror.tcl: Theme the bgerror dialog and make use of - our PNG support to improve the icon. + * library/bgerror.tcl: Theme the bgerror dialog and make use of our + PNG support to improve the icon. 2009-01-07 Pat Thoyts - * library/tkfbox.tcl: [Bug 2473120] mis-ordered messagebox args. + * library/tkfbox.tcl: [Bug 2473120]: Mis-ordered messagebox args. - * win/tkWinWm.c: prevent grabs being bypassed on Windows [Bug 1847002] + * win/tkWinWm.c: [Bug 1847002]: Prevent grabs being bypassed on + Windows. 2009-01-06 Jan Nijtmans - * generic/tk.h: A few const -> CONST86 modifications, improving - * generic/tkCanvas.c: backwards compatibility. Change Tk_ItemIndexProc - * generic/tkCanvLine.c: and Tk_ItemInsertProc signature to have a Tcl_Obj parameter - * generic/tkCanvPoly.c: in stead of a string parameter. This is binary - * generic/tkCanvText.c: and source compatible with previous API, it just prevents - * doc/CrtItemType.3: the need for a type cast in the Tk_ItemType table construction. - * doc/Clipboard.3: Bring doc in line with API - * doc/ConfigWidg.3: - * doc/ParseArgv.3: + * generic/tk.h: A few const -> CONST86 modifications, + * generic/tkCanvas.c: improving backwards compatibility. Change + * generic/tkCanvLine.c: Tk_ItemIndexProc and Tk_ItemInsertProc + * generic/tkCanvPoly.c: signature to have a Tcl_Obj parameter instead + * generic/tkCanvText.c: of a string parameter. This is binary and + * doc/CrtItemType.3: source compatible with previous API, it just + * doc/Clipboard.3: prevents the need for a type cast in the + * doc/ConfigWidg.3: Tk_ItemType table construction. Bring doc in + * doc/ParseArgv.3: line with API. 2009-01-06 Donal K. Fellows @@ -258,8 +262,8 @@ 2009-01-03 Donal K. Fellows - * doc/canvas.n: Improve the documentation of the -offset and - -outlineoffset item options. [Bug 1836621] + * doc/canvas.n: [Bug 1836621]: Improve the documentation of the + -offset and -outlineoffset item options. 2009-01-03 Jan Nijtmans diff --git a/doc/event.n b/doc/event.n index 8e23025..01b1208 100644 --- a/doc/event.n +++ b/doc/event.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: event.n,v 1.21 2008/09/23 13:36:39 dkf Exp $ +'\" RCS: @(#) $Id: event.n,v 1.22 2009/03/10 11:13:53 dkf Exp $ '\" .so man.macros .TH event n 8.3 Tk "Tk Built-In Commands" @@ -376,24 +376,29 @@ Redo one undone action. .TP \fB<>\fR Undo the last action. -.SH "VIRTUAL EVENT EXAMPLES" +.SH EXAMPLES +.SS "MAPPING KEYS TO VIRTUAL EVENTS" .PP In order for a virtual event binding to trigger, two things must happen. First, the virtual event must be defined with the \fBevent add\fR command. Second, a binding must be created for the virtual event with the \fBbind\fR command. Consider the following virtual event definitions: +.PP .CS -event add <> -event add <> -event add <> -event add <> +\fBevent add\fR <> +\fBevent add\fR <> +\fBevent add\fR <> +\fBevent add\fR <> .CE +.PP In the \fBbind\fR command, a virtual event can be bound like any other builtin event type as follows: +.PP .CS bind Entry <> {%W insert [selection get]} .CE +.PP The double angle brackets are used to specify that a virtual event is being bound. If the user types Control-y or presses button 2, or if a \fB<>\fR virtual event is synthesized with \fBevent generate\fR, @@ -402,11 +407,13 @@ then the \fB<>\fR binding will be invoked. If a virtual binding has the exact same sequence as a separate physical binding, then the physical binding will take precedence. Consider the following example: +.PP .CS -event add <> +\fBevent add\fR <> bind Entry {puts Control-y} bind Entry <> {puts Paste} .CE +.PP When the user types Control-y the \fB\fR binding will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. @@ -424,15 +431,37 @@ ungeneratable. When a definition of a virtual event changes at run time, all windows will respond immediately to the new definition. Starting from the preceding example, if the following code is executed: +.PP .CS -bind {} -event add <> +bind Entry {} +\fBevent add\fR <> .CE +.PP the behavior will change such in two ways. First, the shadowed \fB<>\fR binding will emerge. Typing Control-y will no longer invoke the \fB\fR binding, but instead invoke the virtual event \fB<>\fR. Second, pressing the F6 key will now also invoke the \fB<>\fR binding. +.SS "MOVING THE MOUSE POINTER" +.PP +Sometimes it is useful to be able to really move the mouse pointer. For +example, if you have some software that is capable of demonstrating directly +to the user how to use the program. To do this, you need to +.QW warp +the mouse around by using \fBevent generate\fR, like this: +.PP +.CS +for {set xy 0} {$xy < 200} {incr xy} { + \fBevent generate\fR . -x $xy -y $xy -warp 1 + update + after 50 +} +.CE +.PP +Note that it is usually considered bad style to move the mouse pointer for the +user because it removes control from them. Therefore this technique should be +used with caution. Also note that it is not guaranteed to function on all +platforms. .SH "SEE ALSO" bind(n) .SH KEYWORDS -- cgit v0.12